Sign in

v1

latestOpenAPI 3.0.02026-07-2475182625.5 KB
Coupons

Retrieve a coupon

Returns full details for a specific coupon by its path identifier.

get/coupons/{coupon_id}

Path parameters

coupon_idstring required

The unique path identifier for the coupon.

Query parameters

expandboolean

When true, expands product path identifiers to full product objects in the products array of the response.

Response

Successful response.

couponstring

Unique coupon path identifier.

discountPeriodCountinteger nullable

Number of billing periods the discount applies to. null means unlimited.

applyDiscountImmediatelyboolean

Indicates the discount applies starting in the first billing period.

Note: Only present in the response when true. Absence of this field indicates false.

combineboolean

Indicates whether this discount stacks with other active discounts.

orderLevelDiscountboolean

(Beta) Indicates the discount applies to the entire order subtotal. Only returned for coupons created by accounts enrolled in the closed Order-Level Coupons beta.

Note: Only present in the response when true. Absence of this field indicates false.

reasonobject

Localized discount description. Returns {} when no reason is configured.

limitstring

Maximum number of times this discount can be applied. Returns as a string. "" means unlimited.

Note: Sending limit: 0 on create or update is stored and returned as "".

codesstring[]

Coupon codes associated with this coupon.

Code handling

  • Case: Codes are normalized to uppercase on storage. A code submitted as summer10 is stored and returned as SUMMER10. Case is not preserved — treat the uppercased form as canonical.
  • Pagination: Limited to 1,000 items on this endpoint. Use GET /coupons/{coupon_id}/codes to retrieve the full list for coupons with more than 1,000 codes.

Example response

{
  "coupon": "summer-sale-2026",
  "discount": {
    "type": "percent",
    "percent": 25,
    "amount": {
      "USD": 10,
      "EUR": 9,
      "GBP": 8
    },
    "discounts": []
  },
  "discountPeriodCount": 3,
  "applyDiscountImmediately": true,
  "orderLevelDiscount": true,
  "reason": {
    "en": "50% off for your first 3 months"
  },
  "limit": "500",
  "available": {
    "start": "2026-06-01",
    "end": "2026-08-31"
  },
  "codes": [
    "SUMMER10",
    "SUMMER20"
  ],
  "products": [
    "pro-plan-monthly",
    "pro-plan-annual"
  ]
}