Skip to main content
A promotion code is another code buyers can type for an existing coupon. It gives the coupon’s discount. The coupon only limits its expiry and total uses; buyer restrictions are set on each promotion code. Use promotion codes for an influencer, a campaign channel, or a batch of single-use codes. Promotion codes only exist for active coupons, in the coupon’s store and environment. Creating promotion codes does not change the coupon’s discount.

​
Promotion Code Status Values

​
Restrictions

Each promotion code has its own buyer restrictions. The coupon’s redeemBy and maxRedemptions apply to every code as well: Create promotion codes together with the coupon (Create Coupon, up to 20) or one by one and in bulk with the endpoints below. The coupon’s own code is not one of its promotion codes: it has no restrictions of its own, is not returned by promotionCodes, and can only be deactivated together with the coupon.

​
Codes

Promotion codes follow the same code format as coupons: 3–32 letters, digits or -, case-insensitive, stored in uppercase, unique among the store’s active codes in the same environment, and released when deactivated. When you omit code, or generate codes in bulk, the random part uses uppercase letters and digits without the look-alike characters 0, O, 1, I and L.

​
Safe Retries

Send an X-Idempotency-Key header (SDK: the idempotencyKey option) and reuse it when you retry. This matters most for Generate Promotion Codes: codes are random, so a retry without the key generates a second batch. See Errors for the key requirements.

​
Reading Promotion Codes

These endpoints only write. List a coupon’s promotion codes with GraphQL: promotionCodes and promotionCodesCount. Filter by batchId to read back a generated batch.

​
Endpoints

Create Promotion Code

Add one promotion code to a coupon.

Generate Promotion Codes

Generate 1–500 random promotion codes in one call.

Deactivate Promotion Code

Permanently deactivate a promotion code and release its code.