Sign in

v2

latestOpenAPI 3.0.0Commercial2026-07-2649110209.4 KB
Discounts

Create a discount.

Create promotional discount codes for products. Set percentage or fixed amount discounts with expiration dates.

post/v1/discounts

Request body

namestring required

The name of the discount.

codestring

Optional discount code. If left empty, a code will be generated.

type'percentage' | 'fixed' required

The type of the discount, either "percentage" or "fixed".

amountnumber

The fixed value for the discount. Only applicable if the type is "fixed".

currencystring

The currency of the discount. Only required if type is "fixed".

percentagenumber

The percentage value for the discount. Only applicable if the type is "percentage".

expiry_datestring date-time

The expiry date of the discount.

max_redemptionsnumber

The maximum number of redemptions for the discount.

duration'forever' | 'once' | 'repeating' required

The duration type for the discount.

duration_in_monthsnumber

The number of months the discount is valid for. Only applicable if the duration is "repeating" and the product is a subscription.

applies_to_productsstring[] required

The list of product IDs to which this discount applies.

Example request

{
  "name": "Holiday Sale",
  "code": "HOLIDAY2024",
  "amount": 20,
  "currency": "USD",
  "percentage": 15,
  "expiry_date": "2024-12-31T23:59:59Z",
  "max_redemptions": 100,
  "duration_in_months": 6,
  "applies_to_products": [
    "prod_123",
    "prod_456"
  ]
}

Response

Successfully created a discount

idstring required

Unique identifier for the object.

mode'test' | 'prod' | 'sandbox' required

String representing the environment.

objectstring required

A string representing the object’s type. Objects of the same type share the same value.

status'deleted' | 'active' | 'draft' | 'expired' | 'scheduled' required

The status of the discount (e.g., active, inactive).

namestring required

The name of the discount.

codestring required

The discount code. A unique identifier for the discount.

type'percentage' | 'fixed' required

The type of the discount, either "percentage" or "fixed".

amountnumber

The amount of the discount. Can be a percentage or a fixed amount.

currencystring

The currency of the discount. Only required if type is "fixed".

percentagenumber

The percentage of the discount. Only applicable if type is "percentage".

expiry_datestring date-time

The expiry date of the discount.

max_redemptionsnumber

The maximum number of redemptions allowed for the discount.

duration'forever' | 'once' | 'repeating'

The duration type for the discount.

duration_in_monthsnumber

The number of months the discount is valid for. Only applicable if the duration is "repeating" and the product is a subscription.

applies_to_productsstring[]

The list of product IDs to which this discount applies.

redeem_countnumber

The number of times this discount has been redeemed.

Example response

{
  "object": "discount",
  "status": "active",
  "name": "Holiday Sale",
  "code": "HOLIDAY2024",
  "type": "percentage",
  "amount": 20,
  "currency": "USD",
  "percentage": 15,
  "expiry_date": "2024-12-31T23:59:59Z",
  "max_redemptions": 100,
  "duration": "repeating",
  "duration_in_months": 6,
  "applies_to_products": [
    "prod_123",
    "prod_456"
  ],
  "redeem_count": 15
}