Skip to main content
CouponsVersion: v3

Create Coupon

POST/payments/coupon

The "Create Coupon" API allows you to create a new promotional coupon with customizable parameters such as discount amount, validity period, usage limits, and applicable products. Use this endpoint to set up promotional offers and special discounts for your customers.

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your access token.

Scope:payments/coupons.write
Auth methods:OAuthPrivate Integration
Token type:Sub-Account Token

Request​

Headers

Versionstringrequired

API Version

Available optionsv3

Body

altIdstringrequired

Location Id

Example:BQdAwxa0ky1iK2sstLGJ
altTypestringrequired

Alt Type

Available optionslocation
Example:location
namestringrequired

Coupon Name

Example:New Year Sale
codestringrequired

Coupon Code

Example:LEVELUPDAY2022
discountTypestringrequired

Discount Type

Available optionspercentageamount
Example:amount
discountValuenumberrequired

Discount Value

Example:10
startDatestringrequired

Start date in YYYY-MM-DDTHH:mm:ssZ format

Example:2023-01-01T22:45:00.000Z
endDatestring

End date in YYYY-MM-DDTHH:mm:ssZ format

Example:2023-01-31T22:45:00.000Z
usageLimitnumber

Max number of times coupon can be used

Example:10
productIdsstring[]

Product Ids

Example:["6241712be68f7a98102ba272"]
priceIdsstring[]

Price Ids

Example:["6241712be68f7a98102ba272"]
variantIdsstring[]

Variant Ids

Example:["6241712be68f7a98102ba272"]
applyToFuturePaymentsboolean

Is Coupon applicable on upcoming subscription transactions

Default:true
Example:true
applyToFuturePaymentsConfigobject

If coupon is applicable on upcoming subscription transactions, how many months should it be applicable for a subscription

Default:{"type":"forever"}
limitPerCustomerboolean

Limits whether a coupon can be redeemed only once per customer.

Default:false
Example:true

Response

Successful response

_idstringrequired

Unique MongoDB identifier for the coupon

Example:67f6c132d9485f9dacd5f123
usageCountnumberrequired

Number of times the coupon has been used

Example:12
limitPerCustomernumberrequired

Maximum number of times a customer can use this coupon (0 for unlimited)

Example:5
altIdstringrequired

Location Id

Example:79t07PzK8Tvf73d12312
altTypestringrequired

Type of entity

Example:location
namestringrequired

Display name of the coupon

Example:NEWT6
codestringrequired

Redemption code for the coupon

Example:NEWT6
discountTypestringrequired

Type of discount (percentage or amount)

Available optionspercentageamount
Example:percentage
discountValuenumberrequired

Value of the discount (percentage or fixed amount)

Example:25
statusstringrequired

Current status of the coupon

Available optionsscheduledactiveexpired
Example:scheduled
startDatestringrequired

Date when the coupon becomes active

Example:2025-04-30T18:30:00.000Z
endDatestring

End date when the coupon expires

Example:2025-05-30T18:30:00.000Z
applyToFuturePaymentsbooleanrequired

Indicates if the coupon applies to future recurring payments

Example:true
applyToFuturePaymentsConfigobjectrequired

Configuration for how the coupon applies to future payments

userIdstring

User ID associated with the coupon (if applicable)

Example:q0m15dTLGeiGOXG123123
createdAtstringrequired

Creation timestamp

Example:2025-04-09T18:49:22.026Z
updatedAtstringrequired

Last update timestamp

Example:2025-04-09T18:49:22.026Z
traceIdstringrequired

Unique identifier for tracing this API request

Example:c667b18d-8f5e-44cf-a914