Skip to main content

Core Concepts

The Weave API is organized around a handful of loyalty concepts. Understanding how they fit together makes the rest of the API Reference easy to navigate.

The building blocks​

Customers​

A customer is a person enrolled in your loyalty program. Beyond a name (identity), a customer can carry email addresses, phone numbers, postal addresses, external identifiers, tags, and preferences — each managed through its own sub-resource under /customers/{customerId}.

Each program membership can have a referral code for the member to share. Generate it with POST /customers/{customerId}/programs/{customerProgramId}/referrals, which returns the same code on every later call. When a new customer is created with that code in referralCode, they are enrolled in the code's program, the referral is recorded, and two events fire: referral.referrer for the member and referral.referee for the new customer, so an event rule can reward each side. A code that doesn't exist, or whose member is no longer active, rejects the enrollment.

Programs​

A program is a loyalty program: the container that customers earn and spend within. Everything below — currencies, tiers, offers, targets, and rules — is configured per program.

Program currencies​

A program currency is the unit a program awards and tracks — points, miles, stars, or cash-back. A program can define more than one.

Tiers​

Tiers are the membership levels within a program (for example Silver, Gold, Platinum). A customer's tier changes as they meet the program's criteria.

Offers, coupons, and targets​

  • Offers are the rewards and promotions a program makes available.
  • Coupons are redeemable codes issued against offers.
  • Targets are counters a customer progresses toward (spend $500, take 10 flights) that can trigger a reward when reached.

Badges​

Badges are achievements a customer earns. Program configuration defines the badge types; customers accumulate them under /customers/{customerId} and the customer-badges resource.

Events and event rules​

  • An event is a signal you send to Weave — a customer did something worth reacting to (a purchase, a check-in, a referral). You submit events through the events resource.
  • An event rule describes how an event translates into loyalty outcomes: award currency, adjust a tier, progress a target, grant a badge.

This event → rule pipeline is the engine that turns real-world activity into loyalty state.

Program accounts and ledgers​

  • A program account is a customer's standing in a specific program, including their current balances.
  • The program ledger is the append-only history of every change to those balances — each entry recording what happened and why. Ledger statements summarize activity over a period.

Because the ledger is immutable, it's the source of truth for a customer's balance and a complete audit trail.

How it fits together​

A typical program looks like this:

  1. Configure a program, its currency, its tiers, and the event rules that govern earning.
  2. Enroll customers.
  3. Send events as customers act.
  4. Weave applies the matching rules, writing the result to the customer's program ledger.
  5. Balances update, targets advance, badges unlock, and tiers move — all readable back through the API.

Extending the model​

Weave is multi-tenant and schema-driven. Data models and metadata let you extend the standard entities with your own fields and controlled vocabularies (customer statuses, enrollment channels, address types), and partners model the third parties involved in your program.

Next Steps​