Loyalty API

Required scope: loyalty:read

If the store's plan does not include loyalty, these endpoints return 403 with Loyalty is not included in your plan (code: feature_not_enabled). The endpoints are read-only; loyalty points cannot be earned, redeemed or adjusted with an API key.

Decimal fields are strings

Money, percentage and multiplier fields on tiers and rewards (such as minimum_lifetime_spend, discount_percentage, points_multiplier, discount_amount) are sent as decimal strings like "1000.0". Integer fields such as level and points_required are numbers.

---

List Loyalty Tiers

GET /api/v1/loyalty_tiers

Returns all active loyalty tiers ordered by level (up to 500). Not paginated.

Response

{
  "data": [
    {
      "id": 1,
      "name": "Bronze",
      "level": 1,
      "description": null,
      "color": "#CD7F32",
      "minimum_lifetime_spend": "0.0",
      "minimum_visits": 0,
      "discount_percentage": "0.0",
      "points_multiplier": "1.0",
      "free_delivery": false,
      "early_access_sales": false,
      "benefits_description": null,
      "benefits_list": []
    },
    {
      "id": 2,
      "name": "Gold",
      "level": 3,
      "description": "Our best customers",
      "color": "#FFD700",
      "minimum_lifetime_spend": "1000.0",
      "minimum_visits": 0,
      "discount_percentage": "5.0",
      "points_multiplier": "1.5",
      "free_delivery": true,
      "early_access_sales": false,
      "benefits_description": null,
      "benefits_list": ["5.0% discount on all purchases", "1.5x points multiplier", "Free delivery"]
    }
  ],
  "meta": { ... }
}

---

List Loyalty Rewards

GET /api/v1/loyalty_rewards

Returns currently available rewards that customers can redeem with points, ordered by points required (up to 500). Not paginated.

Query Parameters

Parameter	Type	Description
customer_id	integer	Only rewards this customer can currently redeem. An unknown ID returns 404.

Reward Fields

id, name, description, reward_type, points_required, discount_amount, discount_percentage, store_credit_amount, product_id, product_name, minimum_tier_level, redemption_limit, valid_from, valid_until, reward_description, validity_status, active.

---

Available Rewards for a Customer

GET /api/v1/loyalty_rewards/available?customer_id=:id

Returns rewards the specified customer can currently redeem, along with their current points and tier. An unknown customer returns 404 with Customer not found.

Response

{
  "data": {
    "customer_id": 1,
    "customer_name": "Jane Smith",
    "loyalty_points": 2450,
    "loyalty_tier": "Gold",
    "available_rewards": [ ... ]
  }
}

Each entry in available_rewards has the same fields as List Loyalty Rewards.

---

Customer Loyalty Info

Customer loyalty data is included in the Customers API response fields: loyalty_tier, loyalty_points, lifetime_spend, visit_count.