Create a loyalty program
Create a stamp card, points program, cashback program, membership or gift card. New programs start as draft: activate them with "status": "active" (here or later with an update).
Endpoint
POST/loyalty-programs
Body parameters
| Name | Type | Required | Description |
|---|---|---|---|
organization_id | integer | Yes | Your organization ID (the API key's organization). |
name | string | Yes | Program name (1 to 255 characters). |
type | string | Yes | stamps, points, cashback, membership or gift_card. Cannot be changed later. |
status | string | No | draft (default), active, paused or archived. |
slug | string | No | Link name for the public enrollment page. Generated from name when omitted. |
currency_code | string | No | Currency, for example USD. Required before a cashback or gift_card program can be active. |
description, earn_rules, stamps_required, cashback_percent, welcome_bonus, birthday_bonus, referrals_enabled, referrer_bonus, referred_bonus, expiration_days, min_redeem_amount, membership_uses, membership_validity_days, gift_card_default_amount, tiers_enabled, tier_basis, card_design, locations, enrollment_settings, terms, public_enrollment_enabled, apple_wallet_enabled, google_wallet_enabled | No | See Fields. |
Request
Response
Returns the created loyalty program with enrollment_url and wallet_availability.
json
Defaults by type
| Type | Default when omitted |
|---|---|
stamps | stamps_required: 10 |
points | tier_basis: "lifetime_points" |
cashback | cashback_percent: 5 |
membership | membership_uses: 10 |
card_design and earn_rules get the default design and rules shown above. Keys you send are merged over them.
Errors
All are 400 Bad Request:
| Message | Cause |
|---|---|
This link name is already used by another program | The slug you sent is taken in your organization. Without slug, a free one is generated. |
A stamp card needs between 2 and 30 stamps | stamps_required out of range. |
Cashback must be between 0 and 100 percent | cashback_percent out of range. |
Cashback and gift cards need a currency | active cashback or gift card without currency_code. |
A membership needs at least one use | membership_uses below 1. |
Expiration must be at least one day | expiration_days below 1. |
Tiers are available for points, stamps and cashback programs | tiers_enabled on a membership or gift card. |
Referrals are available for points, stamps and cashback programs | referrals_enabled on a membership or gift card. |
card_design.<key> must be a #RRGGBB color | Invalid color. |
earn_rules.<key> must be a positive number / earn_rules.amount_step must be greater than zero | Invalid earning rule. |
A card supports up to 10 locations / Invalid location latitude / Invalid location longitude | Invalid locations. |
Report an issue with this documentation
Please log in to report issues with our documentation.