Loyalty

Loyalty rules & rewards

Rules describe trigger → reward mappings (visit count, spend threshold, birthday, win-back). When a rule fires, Tablezio creates a loyalty_reward attached to the customer.

List loyalty rules

GET

/v1/loyalty_rules Scope: loyalty:read

Rules that automatically issue rewards based on customer activity.

Request

curl https://api.tablezio.com/v1/loyalty_rules -H 'X-API-Key: tbz_…'

Response

application/json

{ "object": "list", "data": [ /* loyalty_rule */ ], "has_more": false, "next_cursor": null, "previous_cursor": null, "url": "/v1/loyalty_rules" }

Create a loyalty rule

POST

/v1/loyalty_rules Scope: loyalty:write

Defines a trigger → reward mapping. When the trigger fires for a customer, a loyalty_reward is created automatically.

Body parameters

namestringRequired

Display name in the dashboard.

trigger_typestringRequired

What event awards the reward.

visit_milestonespend_milestonebirthdayanniversarypoints_thresholdwin_back

trigger_valuenumberOptional

Threshold (visits, cents spent, points). Required for milestone triggers.

win_back_daysintegerOptional

For win_back triggers: number of days of inactivity before firing.

reward_typestringRequired

Kind of reward.

pointsdiscount_percentagediscount_fixedfree_item

reward_valuenumberRequired

Amount of points, percentage (0..100), or fixed cents.

reward_descriptionstringOptional

Guest-facing description.

is_activebooleanOptional

Default true.

Request

curl -X POST https://api.tablezio.com/v1/loyalty_rules \
  -H 'X-API-Key: tbz_…' -H 'Content-Type: application/json' \
  -d '{
    "name": "Welcome bonus",
    "trigger_type": "visit_milestone",
    "trigger_value": 1,
    "reward_type": "points",
    "reward_value": 100
  }'

Response

application/json

{
  "id": "loy_8b2c3d4e5f6a7b8c9d0e1f20",
  "object": "loyalty_rule",
  "created": 1716730000,
  "updated": 1716730000,
  "name": "Welcome bonus",
  "trigger_type": "visit_milestone",
  "trigger_value": 1,
  "win_back_days": null,
  "reward_type": "points",
  "reward_value": 100,
  "reward_description": "100 points on first visit",
  "is_active": true,
  "times_triggered": 42
}

List loyalty rewards

GET

/v1/loyalty_rewards Scope: loyalty:read

Rewards that have been issued (not yet redeemed, redeemed, or expired).

Query parameters

customerstringOptional

Filter to a single customer (cus_…).

statusstringOptional

Filter by status.

pendingredeemedexpired

expandstring[]Optional

customer.

Request

curl 'https://api.tablezio.com/v1/loyalty_rewards?status=pending' -H 'X-API-Key: tbz_…'

Response

application/json

{ "object": "list", "data": [ /* loyalty_reward */ ], "has_more": false, "next_cursor": null, "previous_cursor": null, "url": "/v1/loyalty_rewards" }

Retrieve a loyalty reward

GET

/v1/loyalty_rewards/{id} Scope: loyalty:read

Fetch a single reward.

Path parameters

idstringRequired

Reward ID (loytx_…).

Query parameters

expandstring[]Optional

customer.

Request

curl https://api.tablezio.com/v1/loyalty_rewards/loytx_… -H 'X-API-Key: tbz_…'

Response

application/json

{
  "id": "loytx_8b2c3d4e5f6a7b8c9d0e1f20",
  "object": "loyalty_reward",
  "created": 1716730000,
  "updated": 1716730000,
  "customer": "cus_…",
  "rule": "loy_…",
  "reward_type": "discount_percentage",
  "reward_value": 10,
  "description": "10% off next visit",
  "status": "pending",
  "redeemed_at": null,
  "expires_at": null
}

Redeem a loyalty reward

POST

/v1/loyalty_rewards/{id}/redeem Scope: loyalty:write

Marks a pending reward as redeemed. Returns the updated reward.

Path parameters

idstringRequired

Reward ID.

Request

curl -X POST https://api.tablezio.com/v1/loyalty_rewards/loytx_…/redeem -H 'X-API-Key: tbz_…'

Response

application/json

{
  "id": "loytx_8b2c3d4e5f6a7b8c9d0e1f20",
  "object": "loyalty_reward",
  "created": 1716730000,
  "updated": 1716730000,
  "customer": "cus_…",
  "rule": "loy_…",
  "reward_type": "discount_percentage",
  "reward_value": 10,
  "description": "10% off next visit",
  "status": "pending",
  "redeemed_at": null,
  "expires_at": null
}