Loyalty program configuration
Manage programs, tiers, benefits, multipliers and join pages as code.
The largest part of the Partner API is loyalty configuration: programs, tiers and benefits together account for over forty operations. This is the pattern for managing them from source control rather than by hand.
The surfaces
Programs
loyalty/programs — create as a draft, update, then activate. Only an
active program delivers anything.
Tiers
loyalty/tiers — the tier ladder, its ordering, and per-tier settings such
as an earn multiplier or a booking rate code.
Benefits
loyalty/benefits — benefit definitions, their eligibility rules, and the
audience that currently qualifies. Benefits are created as drafts and must
be published.
Earn configuration
point-multipliers and rule-attributes — the multiplier layers and the
catalogue of attributes eligibility rules can reference.
Public surfaces
pages and theme-kits for the join page, and custom-domains to serve
it on your own domain.
How earn rates resolve
This is the single most misunderstood part of the configuration surface.
The most specific configured layer wins — even when it is lower. It is specificity, not maximum. A tier configured at a lower rate than the program default will reduce earning for members in that tier, not be ignored in favour of the larger number.
The layers, most specific first:
- Program tier
- Program default
- Journey admin override
- Journey membership tier
- A floor, then a system default
Two more things to hold onto:
- The configured value is the total rate, not an add-on. Setting a multiplier replaces the rate; it does not stack on top of one.
0.00is a valid configured value. It means "no points", and it is distinct from leaving a layer unset, which falls through to the next one.
Campaigns are evaluated separately and compete on a best-single-offer basis. They do not stack with each other.
Things that catch people out
- Drafts do not deliver. A program must be activated and a benefit must be published before either does anything.
- Changes are additive and compatible. New response fields appear over time; ignore ones you do not recognise.
- Custom-domain recheck is rate limited with its own 429. Build a backoff rather than a tight retry when verifying DNS.
- Send an
Idempotency-Keyon configuration writes. Re-running a deployment should not create a second program.
Scopes
Programs, tiers and benefits each have separate read and write permissions, and pages, theme kits and custom domains have their own again. The API reference shows the exact requirement per endpoint.