Skip to main content
Create a coupon with its own code — buyers can type it at checkout — optionally together with up to 20 promotion codes. Everything is created in one request: the coupon, its code and all its promotion codes become usable together, or none of them is created. A coupon limits redemptions only by its expiry (redeemBy) and total uses (maxRedemptions); put buyer restrictions (buyer emails, uses per buyer, minimum amount) on promotion codes. The coupon can also be applied with couponId on a checkout session; add promotion codes later with Create Promotion Code.
Authentication: API Key (store owner or admin)

Request Body

Discount Object

Promotion Code Object

Each entry of promotionCodes takes the same fields as Create Promotion Code, without couponId:

Example Request

Success Response (200)

Response Fields

The response is wrapped in data.coupon.
Creation either succeeds or fails within the request. A 200 response always carries an active coupon. If the payment provider rejects the coupon or does not confirm the creation, the response is a 502, the coupon is recorded as failed and every code of the request is released — create it again, with the same codes if you like. If a request is interrupted before it finishes, its coupon can stay pending and hold its codes; such a coupon is cleaned up on the spot — recorded as failed, codes released — by the next Create Coupon, Create Promotion Code or Generate Promotion Codes request in the same store and environment once it is more than 10 minutes old.

Response With Warnings

Once the coupon is active its codes are usable, and the request no longer fails. If Pancake cannot convert the amounts to display format at that point, it still returns 200 with the active coupon: amountOff and every promotionCodes[].restrictions.minimumAmount are null — the response shape does not change — and a top-level warnings array says the amounts were not converted. All other fields are filled in as usual.
The coupon has been created as requested — do not create it again. Read it with GraphQL coupon(id) to get its amounts.

Errors

Retry policy: Never retry 4xx — fix the request and resubmit. Retry 5xx with exponential backoff (start 5s, max 3 attempts). Always retry with the same X-Idempotency-Key.