Purpose

Validate one or more coupon codes for an order in a single request.

Format

To validate coupon eligibility and discount amounts, these are computed against the order content provided in the request, any changed content can be re-validated to confirm eligibility.

Each coupon code is validated independently, so any invalid or ineligible codes will not fail the whole request

There are two scenarios where validating coupons is reccomended;

• When a customer enters a coupon code - check for eligibility and confirm the discount to apply to the order.
• Whenever an order changes - with items added, removed, quantities updated, coupons need revalidated with the updated content.

Path Parameters

Revalidating after the order changes

Whenever the customer's order mutates, re-validate by sending all the codes relevant to the order in codes — both any code the customer just entered and any code(s) already applied to the order from a previous validation — in a single call against the current order state. Then, for each result:

• applicable: false → the code is no longer eligible for the current order (e.g. a PLU-scoped discount whose matching item was removed, or a minimum-spend coupon that no longer qualifies after items were removed). Un-apply it from the order and surface validationErrors to the customer.
• applicable: true → re-apply the returned discounts as-is, replacing whatever was previously applied for that code. Don't reuse a previously computed amount: a percent_off discount's effective amount depends on the order total and an item-scoped discount's depend on which basket items are currently present — both can change even when the code itself remains valid.

Reconcile the order's totals using the fresh discount amounts from the latest call, not the amounts from any earlier validation. This keeps the customer from checking out with a stale discount amount, or one that no longer applies at all, after the order has changed since it was last validated.

Request body

Order object

Item object

Example request

{
  "sessionId": "session-123",
  "order": {
    "orderType": "delivery",
    "items": [
      {
        "id": "64f1a2b3c4d5e6f7a8b9c0d3",
        "plu": "SKU-001",
        "price": 1500
      },
      {
        "id": "64f1a2b3c4d5e6f7a8b9c0d4",
        "plu": "SKU-002",
        "price": 800
      }
    ]
  },
  "codes": [
    "SUMMER25",
    "INVALIDCODE"
  ]
}

Response

Returns a list with one result entry per requested code.

Discount object

Offer types

Discriminated by offer.type:

Scope types

Discriminated by scope.type:

ValidationError object

Example response

[
  {
    "code": "SUMMER25",
    "applicable": true,
    "discounts": [
      {
        "offer": {
          "type": "percent_off",
          "value": 2500,
          "maxAmount": 3000
        },
        "scope": {
          "type": "order"
        },
        "provider": "coupon",
        "externalId": "SUMMER25",
        "name": "Summer 25% off"
      }
    ],
    "description": "25% off your order, up to $30",
    "validationErrors": []
  },
  {
    "code": "INVALIDCODE",
    "applicable": false,
    "discounts": [],
    "description": "",
    "validationErrors": [
      {
        "code": "coupon_not_found",
        "message": "coupon not found"
      }
    ]
  }
]

Notes

• This endpoint does not redeem the coupon — it only validates and returns the
  applicable discount(s). Redemption happens separately at checkout.