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.

Request

Version stringrequired

API Version

Available optionsv3

application/json

application/json

Body

Bodyrequired

altIdstringrequired

Location Id

altTypestringrequired
Alt Type
Available optionslocation
namestringrequired

Coupon Name

codestringrequired

Coupon Code

discountTypestringrequired
Discount Type
Available optionspercentageamount
discountValuenumberrequired

Discount Value

startDatestringrequired

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

endDatestring

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

usageLimitnumber

Max number of times coupon can be used

productIdsstring[]

Product Ids

priceIdsstring[]

Price Ids

variantIdsstring[]

Variant Ids

applyToFuturePaymentsboolean
Is Coupon applicable on upcoming subscription transactions
Default value: true
applyToFuturePaymentsConfigobject
If coupon is applicable on upcoming subscription transactions, how many months should it be applicable for a subscription
Default value: {"type":"forever"}
limitPerCustomerboolean
Limits whether a coupon can be redeemed only once per customer.
Default value: false

Example (auto)

{
  "altId": "BQdAwxa0ky1iK2sstLGJ",
  "altType": "location",
  "name": "New Year Sale",
  "code": "LEVELUPDAY2022",
  "discountType": "amount",
  "discountValue": 10,
  "startDate": "2023-01-01T22:45:00.000Z",
  "endDate": "2023-01-31T22:45:00.000Z",
  "usageLimit": 10,
  "productIds": [
    "6241712be68f7a98102ba272"
  ],
  "priceIds": [
    "6241712be68f7a98102ba272"
  ],
  "variantIds": [
    "6241712be68f7a98102ba272"
  ],
  "applyToFuturePayments": true,
  "applyToFuturePaymentsConfig": [
    {
      "type": "fixed",
      "duration": 5,
      "durationType": "months"
    },
    {
      "type": "forever"
    }
  ],
  "limitPerCustomer": true
}

application/json

Successful response

application/json

Schema

Schema

_idstringrequired

Unique MongoDB identifier for the coupon

usageCountnumberrequired

Number of times the coupon has been used

limitPerCustomernumberrequired

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

altIdstringrequired

Location Id

altTypestringrequired

Type of entity

namestringrequired

Display name of the coupon

codestringrequired

Redemption code for the coupon

discountTypestringrequired
Type of discount (percentage or amount)
Available optionspercentageamount
discountValuenumberrequired

Value of the discount (percentage or fixed amount)

statusstringrequired
Current status of the coupon
Available optionsscheduledactiveexpired
startDatestringrequired

Date when the coupon becomes active

endDatestring

End date when the coupon expires

applyToFuturePaymentsbooleanrequired

Indicates if the coupon applies to future recurring payments

applyToFuturePaymentsConfigobjectrequired

Configuration for how the coupon applies to future payments

userIdstring

User ID associated with the coupon (if applicable)

createdAtstringrequired

Creation timestamp

updatedAtstringrequired

Last update timestamp

traceIdstringrequired

Unique identifier for tracing this API request

Example (auto)

{
  "_id": "67f6c132d9485f9dacd5f123",
  "usageCount": 12,
  "limitPerCustomer": 5,
  "altId": "79t07PzK8Tvf73d12312",
  "altType": "location",
  "name": "NEWT6",
  "code": "NEWT6",
  "discountType": "percentage",
  "discountValue": 25,
  "status": "scheduled",
  "startDate": "2025-04-30T18:30:00.000Z",
  "endDate": "2025-05-30T18:30:00.000Z",
  "applyToFuturePayments": true,
  "applyToFuturePaymentsConfig": {
    "type": "fixed",
    "duration": 3,
    "durationType": "months"
  },
  "userId": "q0m15dTLGeiGOXG123123",
  "createdAt": "2025-04-09T18:49:22.026Z",
  "updatedAt": "2025-04-09T18:49:22.026Z",
  "traceId": "c667b18d-8f5e-44cf-a914"
}