Loyalty & Rewards Open API Specification (1.0.0)

Loyalty & Rewards API invocation guide

Overview

Loyalty & Rewards Open APIs let an integration partner, on behalf of its merchant customers, identify a customer, preview the rewards and points for an order, and then redeem rewards, apply the order to earn points, or void it. The platform computes each reward's discount for the cart. The POS applies the returned amounts and does not compute them from reward definitions.

Money amounts are integers in minor units (for example 1250 is $12.50). An order carries its currency once, and reward amounts carry their own currency.

Checkout flow

At checkout, call the endpoints in this order:

Get customer rewards: preview the rewards and points for the cart.
Redeem rewards on order: once the order is final.
Take payment with your own payment provider.
Apply rewards on order: once payment succeeds.

Redeem, payment and apply are one unit: if payment fails, call Void rewards on order with the order_id.

See the checkout flow page for the full steps, and errors and retries for how to handle failures.

Caution

Our Loyalty & Rewards integration pipeline is still in development. Prospective partners can apply for API access directly through the DoorDash Developer Portal. New to the Developer Portal? Sign up here to create an account and apply for access. Already have a Developer Portal account? Log in and submit your application from the Integrations tab{' '} before building your integration.

Authentication

Every request carries a JWT in the Authorization header (Bearer <JWT>). See the JWT Token guide.

APIs

Get customer rewards

Identifies the customer and returns their loyalty account and rewards. Call it at checkout with order to check rewards against the cart and get the points preview.

loyalty: points and points-based rewards.
available_rewards: non-loyalty rewards the customer can use now.
unavailable_rewards: non-loyalty rewards the customer has but cannot use yet, each with a reason.

An unknown customer returns 200 with customer.status set to NOT_FOUND, and an empty list means there are none. An error is returned only if the customer cannot be determined or every part fails.

Every reward carries a reward_type that distinguishes loyalty rewards (LOYALTY_REWARD), in-store rewards (INSTORE_REWARD) and promotions (LOYALTY_PROMOTIONS).

Request Body schema: application/json
required

location_id required	string Your own store ID.
required	object The customer's phone number or other agreed unique identifier.
required	object The order, with its items, discounts and totals.

Responses

Request samples

Payload

Content type

application/json

{"location_id": "store-1042",
"customer": {"phone": "+14155550123",
"locale": "en-US"
},
"order": {"id": "pos-98231",
"created_at": "2026-10-14T18:30:00Z",
"subtotal": 1450,
"currency": "USD",
"discounts": [{"amount": 100,
"discount_type": "MX_PROMO"
}
],
"tax": 116,
"tip": 200,
"items": [{"merchant_supplied_id": "menu-item-burger-combo",
"name": "Burger Combo",
"quantity": 1,
"price": 1200,
"line_total": 1450,
"extras": [{"name": "Size",
"merchant_supplied_id": "menu-extra-size",
"options": [{"merchant_supplied_id": "menu-option-size-large",
"name": "Large",
"quantity": 1,
"price": 100,
"extras": [{"name": "Add-ons",
"merchant_supplied_id": "menu-extra-addons",
"options": [{"merchant_supplied_id": "menu-option-bacon",
"name": "Bacon",
"quantity": 1,
"price": 150
}
]
}
]
}
]
},
{"name": "Extras",
"merchant_supplied_id": "menu-extra-extras",
"options": [{"merchant_supplied_id": "menu-option-pickles",
"name": "Extra pickles",
"quantity": 1,
"price": 0
}
]
}
]
}
]
}
}

Response samples

Content type

application/json

Example

Customer identified

{"customer": {"status": "IDENTIFIED"
},
"loyalty": {"opt_in_status": "OPTED_IN",
"current_points": 240,
"earn_preview": {"points": 13,
"points_after_order": 253,
"program_status": "EARNING"
},
"rewards": [{"reward_id": "rw-5off",
"reward_type": "LOYALTY_REWARD",
"name": "$5 off",
"loyalty_program_id": "prog-77",
"points_cost": 200,
"definition": {"category": "FLAT_AMOUNT_OFF",
"flat_amount_off": {"amount": 500,
"currency": "USD"
}
}
}
]
},
"available_rewards": [{"reward_id": "rw-fries-isr",
"reward_type": "INSTORE_REWARD",
"name": "Free fries with a burger",
"definition": {"category": "FREE_ITEM",
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "menu-item-fries"
}
]
}
}
},
{"reward_id": "rw-bday-2026",
"reward_type": "LOYALTY_PROMOTIONS",
"name": "Birthday dessert",
"description": "A free dessert on your birthday week",
"expiration_time": "2026-10-31T23:59:59Z",
"definition": {"category": "FREE_ITEM",
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "menu-item-brownie",
"name": "Brownie"
}
]
}
}
}
],
"unavailable_rewards": [{"reward": {"reward_id": "rw-10off-100",
"reward_type": "LOYALTY_PROMOTIONS",
"name": "$10 off $100",
"definition": {"category": "FLAT_AMOUNT_OFF",
"flat_amount_off": {"amount": 1000,
"currency": "USD"
}
}
},
"reason": "SUBTOTAL_BELOW_MINIMUM"
}
]
}

Sign up for loyalty

Signs a customer up for loyalty. Complete the sign-up flow on the POS: collect the customer's phone number.

Call it only when the customer explicitly agrees to sign up, so no separate consent is captured. If the customer already has an account, nothing changes and the call still succeeds.

Request Body schema: application/json
required

location_id required	string Your own store ID.
phone required	string The customer's phone number. It is not validated for now: we do not verify that the customer owns it (for example with an SMS code).

Responses

Request samples

Payload

Content type

application/json

{"location_id": "store-1042",
"phone": "+14155550123"
}

Response samples

Content type

application/json

{"code": "validation_error",
"message": "location_id is required"
}

Get location configuration

Returns how the loyalty program and in-store rewards are set up for the location, and whether each is enabled.

Use loyalty.reward_structures to see what a customer can work towards.

path Parameters

location-id

required

string

Example: store-1042

Your own store ID.

Responses

Response samples

Content type

application/json

{"loyalty": {"loyalty_program_id": "prog-77",
"is_enabled": true,
"terms_and_conditions_url": "https://example.com/loyalty/terms",
"reward_structures": [{"name": "$5 off",
"description": "Spend 200 points for $5 off",
"points_cost": 200,
"definition": {"category": "FLAT_AMOUNT_OFF",
"flat_amount_off": {"amount": 500,
"currency": "USD"
}
}
}
]
},
"in_store_rewards": true
}

Apply rewards on order

Applies loyalty points for the order. Call it once, when the order is finalized, after Redeem rewards on order so loyalty is applied correctly.

An order is applied only once. order.id is the idempotency key: retry with the same body to get the original response. A different body for an already applied order returns 409.

Request Body schema: application/json
required

location_id required	string Your own store ID.
required	object The order, with its items, discounts and totals.
required	object The customer's phone number or other agreed unique identifier.
created_at required	string <date-time> When the transaction was created on your side, for example when the customer paid. Rewards are checked for validity as of this time.
	Array of objects (Tender) How the customer paid for the order.
reward_ids	Array of strings IDs of the rewards used on this order, taken from Get customer rewards.

Responses

Request samples

Payload

Content type

application/json

{"location_id": "store-1042",
"customer": {"phone": "+14155550123"
},
"order": {"id": "pos-98231",
"created_at": "2026-10-14T18:30:00Z",
"subtotal": 1450,
"currency": "USD",
"discounts": [{"amount": 100,
"discount_type": "MX_PROMO"
}
],
"tax": 116,
"tip": 200,
"items": [{"merchant_supplied_id": "menu-item-burger-combo",
"name": "Burger Combo",
"quantity": 1,
"price": 1450
}
]
},
"tenders": [{"tender_type": "CARD",
"amount": 1450,
"card_info": {"last4": "4242",
"exp_month": 8,
"exp_year": 2028
}
}
],
"reward_ids": ["rw-5off",
"rw-bday-2026"
],
"created_at": "2026-10-14T18:31:00Z"
}

Response samples

Content type

application/json

{"loyalty": {"points_awarded": 8,
"current_points": 53
},
"rewards": [{"reward_id": "rw-bday-2026",
"reward_type": "INSTORE_REWARD",
"name": "Birthday dessert",
"definition": {"category": "FREE_ITEM",
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "menu-item-brownie"
}
]
}
}
}
]
}

Redeem rewards on order

Redeems rewards on an order. Loyalty rewards spend points, while promotions and account rewards are simply used. Call it once, when the order is finalized, before Apply rewards on order.

Rewards that cannot be redeemed, including invalid reward IDs, do not fail the call. They are returned in rewards.unavailable_rewards with a reason, and the rest are still redeemed.
An order is redeemed only once. order.id is the idempotency key: retry with the same body to get the original response. A different body for an already redeemed order returns 409.

Request Body schema: application/json
required

location_id required	string Your own store ID.
required	object The order, with its items, discounts and totals.
required	object The customer's phone number or other agreed unique identifier.
reward_ids required	Array of strings IDs of the rewards used on this order, taken from Get customer rewards.
created_at required	string <date-time> When the transaction was created on your side, for example when the customer paid. Rewards are checked for validity as of this time.
	Array of objects (Tender) How the customer paid for the order.

Responses

Request samples

Payload

Content type

application/json

{"location_id": "store-1042",
"customer": {"phone": "+14155550123"
},
"order": {"id": "pos-98231",
"created_at": "2026-10-14T18:30:00Z",
"subtotal": 1450,
"currency": "USD",
"discounts": [{"amount": 100,
"discount_type": "MX_PROMO"
}
],
"tax": 116,
"tip": 200,
"items": [{"merchant_supplied_id": "menu-item-burger-combo",
"name": "Burger Combo",
"quantity": 1,
"price": 1450
}
]
},
"tenders": [{"tender_type": "CARD",
"amount": 1450,
"card_info": {"last4": "4242",
"exp_month": 8,
"exp_year": 2028
}
}
],
"reward_ids": ["rw-5off",
"rw-bday-2026"
],
"created_at": "2026-10-14T18:31:00Z"
}

Response samples

Content type

application/json

{"rewards": {"applied_rewards": [{"reward_id": "rw-bday-2026",
"reward_type": "INSTORE_REWARD",
"name": "Birthday dessert",
"definition": {"category": "FREE_ITEM",
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "menu-item-brownie"
}
]
}
}
}
],
"unavailable_rewards": [{"reward_id": "rw-unknown",
"reason": "INVALID_REWARD_ID"
}
]
}
}

Void rewards on order

Voids every apply and redeem on the order as a whole: voiding an apply deducts the points earned, and voiding a redeem returns the points spent. Partial voids are not supported.

order_id identifies the order to void. Void the order if payment fails. An unknown order returns 404.
An order is voided only once. order_id is the idempotency key: retry with the same body to get the original response. A different body for an already voided order returns 409.
Voiding in-store rewards is not supported at this time.

Request Body schema: application/json
required

location_id required	string Your own store ID.
order_id required	string Your order ID: the `order.id` sent on the apply and redeem. Voids every apply and redeem on the order.
created_at required	string <date-time> When the void was created.

Responses

Request samples

Payload

Content type

application/json

{"location_id": "store-1042",
"order_id": "pos-98231",
"created_at": "2026-10-14T18:45:00Z"
}

Response samples

Content type

application/json

Example

Merchant with a loyalty program

{"loyalty": {"current_points": 254,
"rewards": [ ]
},
"voided_rewards": [{"reward_id": "rw-bday-2026",
"reward_type": "INSTORE_REWARD",
"name": "Birthday dessert",
"definition": {"category": "FREE_ITEM",
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "menu-item-brownie"
}
]
}
},
"applied_discount": {"amount": 600,
"currency": "USD",
"allocations": [{"merchant_supplied_id": "menu-item-brownie",
"amount": 600
}
]
}
}
]
}

Models

CustomerDetails

Customer

Details

phone required	string The customer's phone number. It is not validated for now: we do not verify that the customer owns it (for example with an SMS code).
redemption_code	string Reserved for future use, as an alternative way to identify the customer.

{"phone": "string",
"redemption_code": "string"
}

Customer

status

required

string

Enum: "IDENTIFIED" "NOT_FOUND" "CODE_NOT_CLAIMED" "CODE_EXPIRED" "CODE_WRONG_STORE"

IDENTIFIED: recognized, whether or not they have a loyalty account.
NOT_FOUND: no matching customer.
CODE_NOT_CLAIMED: the redemption_code has not been claimed.
CODE_EXPIRED: the redemption_code has expired.
CODE_WRONG_STORE: the redemption_code belongs to a different store.

The CODE_* statuses only apply when the customer was identified by redemption_code.

{"status": "IDENTIFIED"
}

LoyaltyAccount

opt_in_status required	string Enum: "OPTED_IN" "NOT_OPTED_IN" `OPTED_IN`: the customer can redeem points. `NOT_OPTED_IN`: the customer cannot redeem points yet. Customers earn points whether or not they are opted in.
current_points required	integer <int64> The customer's current points balance.
	Array of objects (Reward) Rewards the customer can redeem with points. Eligibility is checked again when the order is applied.
	object A preview of the points this order would add to the account. Set only when `order` was sent, and only for loyalty customers. The account is not changed.

{"opt_in_status": "OPTED_IN",
"current_points": 0,
"rewards": [{"reward_id": "string",
"reward_type": "LOYALTY_REWARD",
"name": "string",
"definition": {"category": "FLAT_AMOUNT_OFF",
"flat_amount_off": {"amount": 0,
"currency": "string"
},
"percent_off": {"percent": 0
},
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"bogo": {"buy_quantity": 0,
"get_quantity": 0,
"get_percent_off": 0,
"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"spend_x_get_y": {"spend_amount": 0,
"currency": "string",
"amount_off": 0,
"percent_off": 0,
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
}
}
},
"description": "string",
"expiration_time": "2019-08-24T14:15:22Z",
"applied_discount": {"amount": 0,
"currency": "string",
"allocations": [{"merchant_supplied_id": "string",
"amount": 0,
"options": [{ }
]
}
]
},
"loyalty_program_id": "string",
"points_cost": 0
}
],
"earn_preview": {"points": 0,
"program_status": "EARNING",
"points_after_order": 0
}
}

Order

id required	string Your order ID, and the idempotency key for apply, redeem and void. An order is applied once and redeemed once: retry with the same ID and body to get the original response. A different body is rejected with 409.
created_at required	string <date-time> When the order was created.
subtotal required	integer <int64> Item total in minor units, before discounts, tax and tip. Loyalty points are calculated on the subtotal minus discounts and minus the value of the rewards in `reward_ids`.
currency required	string ISO 4217 currency code (for example `USD`). Applies to every amount in the order.
required	Array of objects (Item) The items on the order.
	Array of objects (Discount) Discounts the merchant applied. Do not list loyalty rewards here: send them in `reward_ids`. Rewards are priced against subtotal minus these discounts.
tax	integer <int64> Total tax in minor units. It does not affect points.
tip	integer <int64> Tip in minor units. It does not affect points.
alcohol_subtotal	integer <int64> Portion of subtotal that is alcohol, in minor units. Excluded from the points calculation.

{"id": "string",
"created_at": "2019-08-24T14:15:22Z",
"subtotal": 0,
"currency": "string",
"items": [{"merchant_supplied_id": "string",
"name": "string",
"quantity": 0,
"price": 0,
"description": "string",
"line_total": 0,
"extras": [{"name": "string",
"merchant_supplied_id": "string",
"options": [{"name": "string",
"merchant_supplied_id": "string",
"quantity": 0,
"price": 0,
"extras": [{ }
]
}
]
}
]
}
],
"discounts": [{"amount": 0,
"discount_type": "MEMBER_SAVINGS"
}
],
"tax": 0,
"tip": 0,
"alcohol_subtotal": 0
}

Tender

tender_type required	string Enum: "CARD" "OTHER" `CARD`: a credit or debit card. `OTHER`: any other payment method.
amount required	integer Amount paid with this tender, in minor units of the order's currency.
required	object Card details used to match in-store rewards (ISR). Set when `tender_type` is `CARD`.

{"tender_type": "CARD",
"amount": 0,
"card_info": {"last4": "string",
"exp_month": 0,
"exp_year": 0
}
}

CardInfo

last4 required	string Last four digits of the card.
exp_month	integer Used only to match the card, never stored.
exp_year	integer Used only to match the card, never stored.

{"last4": "string",
"exp_month": 0,
"exp_year": 0
}

Reward

reward_id required	string ID of the reward. Send it in `reward_ids` to redeem or apply the reward.
reward_type required	string Enum: "LOYALTY_REWARD" "INSTORE_REWARD" "LOYALTY_PROMOTIONS" `LOYALTY_REWARD`: a reward the customer redeems with loyalty points. `INSTORE_REWARD`: an in-store reward (currently unavailable). `LOYALTY_PROMOTIONS`: a loyalty promotion. More reward types may be added.
name required	string Display name of the reward.
required	object What the reward is and how it works.
description	string A longer description of the reward, suitable for showing to the customer.
expiration_time	string <date-time> When the reward expires.
	object Discount this reward produces on the submitted order. Set only when `order` was sent and the reward applies to the cart. Apply this amount as returned; do not recompute it from `definition`.
loyalty_program_id	string The ID of the loyalty program. Set only for loyalty rewards. Matches the `loyalty_program_id` of the program from Get location configuration. Absent for non-loyalty rewards.
points_cost	integer <int64> Points the customer spends to redeem this reward.

{"reward_id": "string",
"reward_type": "LOYALTY_REWARD",
"name": "string",
"definition": {"category": "FLAT_AMOUNT_OFF",
"flat_amount_off": {"amount": 0,
"currency": "string"
},
"percent_off": {"percent": 0
},
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"bogo": {"buy_quantity": 0,
"get_quantity": 0,
"get_percent_off": 0,
"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"spend_x_get_y": {"spend_amount": 0,
"currency": "string",
"amount_off": 0,
"percent_off": 0,
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
}
}
},
"description": "string",
"expiration_time": "2019-08-24T14:15:22Z",
"applied_discount": {"amount": 0,
"currency": "string",
"allocations": [{"merchant_supplied_id": "string",
"amount": 0,
"options": [{ }
]
}
]
},
"loyalty_program_id": "string",
"points_cost": 0
}

RewardStructure

name required	string Display name of the reward.
required	object What the reward is and how it works.
points_cost required	integer <int64> Points the customer spends to redeem this reward.
description	string A longer description of the reward, suitable for showing to the customer.

{"name": "string",
"definition": {"category": "FLAT_AMOUNT_OFF",
"flat_amount_off": {"amount": 0,
"currency": "string"
},
"percent_off": {"percent": 0
},
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"bogo": {"buy_quantity": 0,
"get_quantity": 0,
"get_percent_off": 0,
"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"spend_x_get_y": {"spend_amount": 0,
"currency": "string",
"amount_off": 0,
"percent_off": 0,
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
}
}
},
"points_cost": 0,
"description": "string"
}

LoyaltyApplication

points_awarded required	integer <int64> Points the customer earned on this order.
current_points required	integer <int64> The customer's points balance after this order.

{"points_awarded": 0,
"current_points": 0
}

Item

merchant_supplied_id required	string Your menu ID for the item. Used to match item-based rewards.
name required	string Name of the item.
quantity required	integer Number of this item on the order.
price required	integer <int64> Unit price of the item in minor units, not including its extras.
description	string Description of the item.
line_total	integer <int64> Total for the line in minor units, including quantity and extras.
	Array of objects (ItemExtra) Groups of choices on the item, such as "Size" or "Add-ons".

{"merchant_supplied_id": "string",
"name": "string",
"quantity": 0,
"price": 0,
"description": "string",
"line_total": 0,
"extras": [{"name": "string",
"merchant_supplied_id": "string",
"options": [{"name": "string",
"merchant_supplied_id": "string",
"quantity": 0,
"price": 0,
"extras": [{ }
]
}
]
}
]
}

ItemExtra

name required	string Name of the extra, such as "Size" or "Add-ons".
merchant_supplied_id required	string Your menu ID for the extra.
	Array of objects (ItemOption) The choices in this extra, such as "Large" or "Bacon".

{"name": "string",
"merchant_supplied_id": "string",
"options": [{"name": "string",
"merchant_supplied_id": "string",
"quantity": 0,
"price": 0,
"extras": [{ }
]
}
]
}

ItemOption

name required	string Name of the option, such as "Large" or "Bacon".
merchant_supplied_id required	string Your menu ID for the option.
quantity required	integer Number of this option on the item.
price required	integer <int64> Unit price of the option in minor units.
	Array of objects (ItemExtra) Extras nested under this option.

{"name": "string",
"merchant_supplied_id": "string",
"quantity": 0,
"price": 0,
"extras": [{"name": "string",
"merchant_supplied_id": "string",
"options": [{ }
]
}
]
}

RewardDefinition

category required	string Enum: "FLAT_AMOUNT_OFF" "PERCENT_OFF" "FREE_ITEM" "BOGO" "SPEND_X_GET_Y" `FLAT_AMOUNT_OFF`: a fixed amount off. `PERCENT_OFF`: a percentage off. `FREE_ITEM`: one or more free items. `BOGO`: buy one, get one. `SPEND_X_GET_Y`: spend a set amount, get a reward. New categories may be added.
	object Set when the category is `FLAT_AMOUNT_OFF`.
	object Set when the category is `PERCENT_OFF`.
	object Set when the category is `FREE_ITEM`.
	object Set when the category is `BOGO`. Draft parameters, to be confirmed.
	object Set when the category is `SPEND_X_GET_Y`. Draft parameters, to be confirmed.

{"category": "FLAT_AMOUNT_OFF",
"flat_amount_off": {"amount": 0,
"currency": "string"
},
"percent_off": {"percent": 0
},
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"bogo": {"buy_quantity": 0,
"get_quantity": 0,
"get_percent_off": 0,
"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"spend_x_get_y": {"spend_amount": 0,
"currency": "string",
"amount_off": 0,
"percent_off": 0,
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
}
}
}

FlatAmountOff

amount required	integer <int64> Amount off, in minor units.
currency required	string ISO 4217 currency code.

{"amount": 0,
"currency": "string"
}

PercentOff

percent

required

number

Percentage off, for example 10 for 10%.

{"percent": 0
}

FreeItems

FreeItem

required

Array of objects (FreeItem)

The free items.

Array

reference_type required	string Enum: "ITEM" "OPTION" "EXTRA" What the id refers to on the menu. `ITEM`: an item. `OPTION`: an option. `EXTRA`: an extra, a group of options on an item.
merchant_supplied_id required	string ID of the item, option or extra as stored in your system.
name	string Name of the free item.
description	string Description of the free item.

{"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
}

FreeItem

reference_type required	string Enum: "ITEM" "OPTION" "EXTRA" What the id refers to on the menu. `ITEM`: an item. `OPTION`: an option. `EXTRA`: an extra, a group of options on an item.
merchant_supplied_id required	string ID of the item, option or extra as stored in your system.
name	string Name of the free item.
description	string Description of the free item.

{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}

Bogo

buy_quantity	integer Quantity the customer must buy.
get_quantity	integer Quantity the customer gets at the discount.
get_percent_off	number Percentage off the items the customer gets, for example `100` for free.
	Array of objects (FreeItem) The menu items the offer applies to.

{"buy_quantity": 0,
"get_quantity": 0,
"get_percent_off": 0,
"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
}

SpendXGetY

spend_amount	integer <int64> Amount to spend, in minor units.
currency	string ISO 4217 currency code.
amount_off	integer <int64> Amount off, in minor units.
percent_off	number Percentage off. Set instead of `amount_off` or `free_items`.
	object Items the customer gets for free. Set instead of `amount_off` or `percent_off`.

{"spend_amount": 0,
"currency": "string",
"amount_off": 0,
"percent_off": 0,
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
}
}

EarnPreview

points required	integer <int64> Points the order would earn.
program_status required	string Enum: "EARNING" "NOT_ACTIVE" "NOT_EARNING_NO_ELIGIBLE_ITEMS" "NOT_EARNING_BELOW_MINIMUM_SPEND" `EARNING`: the order would earn points. `NOT_ACTIVE`: the loyalty program is not active. `NOT_EARNING_NO_ELIGIBLE_ITEMS`: no item in the order is eligible to earn points. `NOT_EARNING_BELOW_MINIMUM_SPEND`: the order is below the minimum spend to earn points. More statuses may be added.
points_after_order	integer <int64> The customer's points balance once the order is applied.

{"points": 0,
"program_status": "EARNING",
"points_after_order": 0
}

LoyaltyRewards

current_points required	integer <int64> The customer's points balance after the call.
required	Array of objects (Reward) The loyalty rewards redeemed or voided. May be empty.

{"current_points": 0,
"rewards": [{"reward_id": "string",
"reward_type": "LOYALTY_REWARD",
"name": "string",
"definition": {"category": "FLAT_AMOUNT_OFF",
"flat_amount_off": {"amount": 0,
"currency": "string"
},
"percent_off": {"percent": 0
},
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"bogo": {"buy_quantity": 0,
"get_quantity": 0,
"get_percent_off": 0,
"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"spend_x_get_y": {"spend_amount": 0,
"currency": "string",
"amount_off": 0,
"percent_off": 0,
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
}
}
},
"description": "string",
"expiration_time": "2019-08-24T14:15:22Z",
"applied_discount": {"amount": 0,
"currency": "string",
"allocations": [{"merchant_supplied_id": "string",
"amount": 0,
"options": [{ }
]
}
]
},
"loyalty_program_id": "string",
"points_cost": 0
}
]
}

LocationConfiguration

	object The loyalty program and its reward structures. Absent if the merchant has no loyalty program.
in_store_rewards	boolean Whether in-store rewards are enabled (currently unavailable).

{"loyalty": {"loyalty_program_id": "string",
"is_enabled": true,
"reward_structures": [{"name": "string",
"definition": {"category": "FLAT_AMOUNT_OFF",
"flat_amount_off": {"amount": 0,
"currency": "string"
},
"percent_off": {"percent": 0
},
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"bogo": {"buy_quantity": 0,
"get_quantity": 0,
"get_percent_off": 0,
"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"spend_x_get_y": {"spend_amount": 0,
"currency": "string",
"amount_off": 0,
"percent_off": 0,
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
}
}
},
"points_cost": 0,
"description": "string"
}
],
"terms_and_conditions_url": "string"
},
"in_store_rewards": true
}

LoyaltyProgram

loyalty_program_id required	string The ID of the loyalty program.
is_enabled required	boolean Whether the program is currently turned on for the location.
required	Array of objects (RewardStructure) The rewards customers can redeem with points. May be empty.
terms_and_conditions_url	string Link to the terms and conditions of the loyalty program.

{"loyalty_program_id": "string",
"is_enabled": true,
"reward_structures": [{"name": "string",
"definition": {"category": "FLAT_AMOUNT_OFF",
"flat_amount_off": {"amount": 0,
"currency": "string"
},
"percent_off": {"percent": 0
},
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"bogo": {"buy_quantity": 0,
"get_quantity": 0,
"get_percent_off": 0,
"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"spend_x_get_y": {"spend_amount": 0,
"currency": "string",
"amount_off": 0,
"percent_off": 0,
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
}
}
},
"points_cost": 0,
"description": "string"
}
],
"terms_and_conditions_url": "string"
}

UnavailableReward

required	object The reward the customer has but cannot use yet.
reason required	string Enum: "ITEM_NOT_IN_CART" "SUBTOTAL_BELOW_MINIMUM" "NOT_ENOUGH_POINTS" `ITEM_NOT_IN_CART`: an item the reward needs is not in the cart. `SUBTOTAL_BELOW_MINIMUM`: the subtotal is below the reward's minimum spend. `NOT_ENOUGH_POINTS`: the customer does not have enough points. More reasons will be added, so handle values you do not recognize.

{"reward": {"reward_id": "string",
"reward_type": "LOYALTY_REWARD",
"name": "string",
"definition": {"category": "FLAT_AMOUNT_OFF",
"flat_amount_off": {"amount": 0,
"currency": "string"
},
"percent_off": {"percent": 0
},
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"bogo": {"buy_quantity": 0,
"get_quantity": 0,
"get_percent_off": 0,
"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"spend_x_get_y": {"spend_amount": 0,
"currency": "string",
"amount_off": 0,
"percent_off": 0,
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
}
}
},
"description": "string",
"expiration_time": "2019-08-24T14:15:22Z",
"applied_discount": {"amount": 0,
"currency": "string",
"allocations": [{"merchant_supplied_id": "string",
"amount": 0,
"options": [{ }
]
}
]
},
"loyalty_program_id": "string",
"points_cost": 0
},
"reason": "ITEM_NOT_IN_CART"
}

RedeemRewards

required	Array of objects (Reward) Non-loyalty rewards redeemed on this order. May be empty.
required	Array of objects (RedeemUnavailableReward) Rewards that could not be redeemed, each with a reason. May be empty.

{"applied_rewards": [{"reward_id": "string",
"reward_type": "LOYALTY_REWARD",
"name": "string",
"definition": {"category": "FLAT_AMOUNT_OFF",
"flat_amount_off": {"amount": 0,
"currency": "string"
},
"percent_off": {"percent": 0
},
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"bogo": {"buy_quantity": 0,
"get_quantity": 0,
"get_percent_off": 0,
"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"spend_x_get_y": {"spend_amount": 0,
"currency": "string",
"amount_off": 0,
"percent_off": 0,
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
}
}
},
"description": "string",
"expiration_time": "2019-08-24T14:15:22Z",
"applied_discount": {"amount": 0,
"currency": "string",
"allocations": [{"merchant_supplied_id": "string",
"amount": 0,
"options": [{ }
]
}
]
},
"loyalty_program_id": "string",
"points_cost": 0
}
],
"unavailable_rewards": [{"reward_id": "string",
"reason": "ITEM_NOT_IN_CART",
"reward": {"reward_id": "string",
"reward_type": "LOYALTY_REWARD",
"name": "string",
"definition": {"category": "FLAT_AMOUNT_OFF",
"flat_amount_off": {"amount": 0,
"currency": "string"
},
"percent_off": {"percent": 0
},
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"bogo": {"buy_quantity": 0,
"get_quantity": 0,
"get_percent_off": 0,
"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"spend_x_get_y": {"spend_amount": 0,
"currency": "string",
"amount_off": 0,
"percent_off": 0,
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
}
}
},
"description": "string",
"expiration_time": "2019-08-24T14:15:22Z",
"applied_discount": {"amount": 0,
"currency": "string",
"allocations": [{"merchant_supplied_id": "string",
"amount": 0,
"options": [{ }
]
}
]
},
"loyalty_program_id": "string",
"points_cost": 0
}
}
]
}

RedeemUnavailableReward

reward_id required	string ID of the reward. Send it in `reward_ids` to redeem or apply the reward.
reason required	string Enum: "ITEM_NOT_IN_CART" "SUBTOTAL_BELOW_MINIMUM" "NOT_ENOUGH_POINTS" "INVALID_REWARD_ID" `ITEM_NOT_IN_CART`: an item the reward needs is not in the cart. `SUBTOTAL_BELOW_MINIMUM`: the subtotal is below the reward's minimum spend. `NOT_ENOUGH_POINTS`: the customer does not have enough points. `INVALID_REWARD_ID`: the `reward_id` is not valid for the customer or the order. More reasons will be added, so handle values you do not recognize.
	object The reward, when it is known. Absent when the `reward_id` is not valid.

{"reward_id": "string",
"reason": "ITEM_NOT_IN_CART",
"reward": {"reward_id": "string",
"reward_type": "LOYALTY_REWARD",
"name": "string",
"definition": {"category": "FLAT_AMOUNT_OFF",
"flat_amount_off": {"amount": 0,
"currency": "string"
},
"percent_off": {"percent": 0
},
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"bogo": {"buy_quantity": 0,
"get_quantity": 0,
"get_percent_off": 0,
"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
},
"spend_x_get_y": {"spend_amount": 0,
"currency": "string",
"amount_off": 0,
"percent_off": 0,
"free_items": {"items": [{"reference_type": "ITEM",
"merchant_supplied_id": "string",
"name": "string",
"description": "string"
}
]
}
}
},
"description": "string",
"expiration_time": "2019-08-24T14:15:22Z",
"applied_discount": {"amount": 0,
"currency": "string",
"allocations": [{"merchant_supplied_id": "string",
"amount": 0,
"options": [{ }
]
}
]
},
"loyalty_program_id": "string",
"points_cost": 0
}
}

Discount

amount required	integer <int64> The discount in minor units.
discount_type required	string Enum: "MEMBER_SAVINGS" "MX_PROMO" "CPG_PROMO" "OTHER" `MEMBER_SAVINGS`: a member savings discount. `MX_PROMO`: a merchant promotion. `CPG_PROMO`: a consumer packaged goods (CPG) brand promotion. `OTHER`: any other discount.

{"amount": 0,
"discount_type": "MEMBER_SAVINGS"
}

AppliedDiscount

amount required	integer <int64> Discount in minor units, computed by the platform against subtotal minus the order's discounts.
currency required	string ISO 4217 currency code.
	Array of objects (LineAllocation) Per-line split of `amount`. The entries sum exactly to `amount`. Empty for order-level discounts.

{"amount": 0,
"currency": "string",
"allocations": [{"merchant_supplied_id": "string",
"amount": 0,
"options": [{ }
]
}
]
}

LineAllocation

merchant_supplied_id required	string Your menu ID for the item. Used to match item-based rewards.
amount required	integer <int64> Portion of the discount allocated to this line, in minor units.
options	Array of objects (LineAllocation) Split of `amount` across the options on the line.

{"merchant_supplied_id": "string",
"amount": 0,
"options": [{ }
]
}

Loyalty & Rewards Open API Specification (1.0.0)

Overview

Checkout flow

Caution

Authentication

APIs

Get customer rewards

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Sign up for loyalty

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get location configuration

path Parameters

Responses

Response samples

Apply rewards on order

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Redeem rewards on order

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Void rewards on order

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Models

CustomerDetails

Customer

Customer

LoyaltyAccount

Order

Tender

CardInfo

Reward

RewardStructure

LoyaltyApplication

Item

ItemExtra

ItemOption

RewardDefinition

FlatAmountOff

PercentOff

FreeItems

FreeItem

FreeItem

Bogo

SpendXGetY

EarnPreview

LoyaltyRewards

LocationConfiguration

LoyaltyProgram

UnavailableReward

RedeemRewards

RedeemUnavailableReward

Discount

AppliedDiscount

LineAllocation

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required