Schemas

The ID you would see on a POS export from the restaurant. Treat as opaque unless you have explicitly agreed on item-to-ID mapping.

How many of this item are in the cart.

Per-unit price of this item, in cents.

The voucher code the guest entered at checkout. Take this as the user-facing value; your system decides how to match (exact, canonicalized, case-insensitive, etc.).

The voucher identifier in your system. May equal the input code or a canonicalized form. Karma stores this as the reservation's voucher number.

How much Karma should discount the cart, in cents. Return a value no greater than cart.totalCents.

When this reservation expires. If omitted, Karma applies a 2-hour default.

Opaque string Karma echoes back on commit/reactivate. Use to correlate to your internal record.

The reserved amount Karma is committing. Equals the discountAmountCents you returned from check.

Karma-generated reservation identifier in the format res_<32 hex chars>. The same value is used for both commit and reactivate of a given reservation. Your endpoint MUST dedupe by this value.

The value you returned from the check response (if any). Echoed back so you can look up the original reservation by your own identifier.

Karma location ID where the lookup is happening. Use to scope the search if your program is multi-tenant.

Karma loyalty program ID this lookup is for.

The value the guest presented. Format depends on identifierType.

Tells you how to interpret identifier.

Your stable identifier for this member. Karma stores this and uses it in subsequent requests for the same guest. Treat as opaque on Karma's side; you choose the format and length.

The Karma user ID, if you have already linked this member to one. Omit if the member is anonymous in your system.

Karma user ID of the guest being enrolled. Store this so you can link your member back to Karma.

Karma loyalty program ID being joined.

Location where enrollment is happening. Useful for source attribution.

Your stable identifier for the new member.

Signup bonus points credited as part of enrollment. Return 0 if your program does not give a signup bonus.

Karma user ID who made the purchase.

Karma loyalty program ID to credit.

Karma purchase ID this award is for. Useful for reconciliation.

Total amount paid, in cents. Apply your accrual rules to this value.

Inventory item IDs included in the purchase. Use these if your program awards bonus points for specific products.

Karma-generated identifier in the format loy_<32 hex chars>. Your endpoint MUST dedupe by this value.

Points credited for this purchase. May be 0 if the purchase didn't qualify.

Member's total spendable point balance after this award.

Whether this award caused the member to move up or down a tier. Karma uses this to refresh tier-related UI.

Karma user ID to fetch.

Loyalty program to fetch the account for.

Member's spendable point balance right now.

Total points the member has ever earned. Return currentBalance if your program does not track lifetime separately.

Human-readable tier name (e.g. "Silver"). Return null if the program has no tiers or the member has not reached one.

Your stable identifier for the tier. Return null whenever tierName is null.

The loyalty program whose catalog to return.

Your stable identifier for the reward. Karma echoes this back on redeem.

Headline label shown to the guest.

Longer human-readable description.

Points the member must spend to redeem this reward.

Free-form bucket for client-side filtering (e.g. drink, food, discount, merchandise). Karma displays this verbatim if present.

Absolute HTTPS URL of a preview image. Return null if you don't host artwork.

How many of this reward are still available globally. Return null if the reward has no stock cap.

Zero or more reward objects. Return an empty array if no rewards are currently active.

Karma user ID redeeming the reward.

Loyalty program the reward belongs to.

Reward being redeemed (one of the IDs you returned from rewards).

Karma-generated identifier in the format loy_<32 hex chars>. Your endpoint MUST dedupe by this value.

Your stable identifier for this redemption. Karma stores this for receipts and refund flows.

Redemption code the guest can present to staff (printed on a receipt or shown in-app). Return null if the reward applies automatically and no code is needed.

Member's point balance after this redemption.

Unique webhook delivery ID

Event type, e.g. "inventory.created"

Resource group, e.g. "inventory"

String ID of the affected resource

ISO 8601 timestamp when the event was emitted