Discount
The Discount object represents a price reduction that can be applied to purchases.
A Discount object represents a price reduction that can be applied to customer purchases. Discounts can be either coupon codes that customers enter at checkout, or automatic sales that apply based on configured rules.
Discounts support both fixed amounts and percentage-based reductions, with optional validity periods and usage limits. You can target discounts to specific Offers or apply them store-wide. Applied discounts are visible on Payment objects.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /v0/discounts/list | List and filter discounts |
POST | /v0/discounts/create | Create a new discount |
GET | /v0/discounts/{discountId} | Retrieve a discount |
PATCH | /v0/discounts/{discountId}/update | Update a discount |
PATCH | /v0/discounts/{discountId}/archive | Archive a discount |
The Discount object
objectstringObject type identifier. Always "discount" for Discount objects.
idstringrequiredUnique identifier (UUID) for this discount.
typestringrequiredDiscount type. Possible values: code (coupon code), sale (automatic discount)
namestring | nullDisplay name of the discount (e.g., "Summer Sale", "10% Off").
amountnumberrequiredDiscount amount. For fixed: amount in currency units (e.g., 10.00 for $10). For percentage: percentage value (e.g., 15 for 15% off).
amountTypestringrequiredHow the amount is applied. Possible values: fixed, percentage
discountCodestring | nullThe coupon code customers enter. Only set when type is "code".
currencystringrequiredThree-letter ISO 4217 currency code. Required for fixed-amount discounts.
statusstringrequiredCurrent discount status. Possible values: active, inactive
validFrominteger | nullUnix timestamp (milliseconds) when the discount becomes valid. null means immediately valid.
validUntilinteger | nullUnix timestamp (milliseconds) when the discount expires. null means no expiration.
purchaseLimitinteger | nullMaximum number of times this discount can be used. null means unlimited.
timesUsedintegerNumber of times this discount has been used. Defaults to 0.
includesAllOffersbooleanWhether this discount applies to all Offers. Defaults to false.
excludedOffersarrayArray of Offer IDs that are excluded from this discount when includesAllOffers is true.
Discount types
Coupon codes
Coupon codes require customers to enter a code at checkout. They're ideal for:
- Marketing campaigns
- Influencer partnerships
- Customer retention offers
- Limited-time promotions
Automatic sales
Sales apply automatically without customer action. They're ideal for:
- Site-wide promotions
- Product launches
- Holiday sales
- Flash sales
Example response
{
"status": "success",
"data": {
"discount": {
"object": "discount",
"id": "880e8400-e29b-41d4-a716-446655440003",
"type": "code",
"name": "Summer Sale 2024",
"amount": 15,
"amountType": "percentage",
"discountCode": "SUMMER15",
"currency": "USD",
"status": "active",
"validFrom": 1717200000000,
"validUntil": 1725148800000,
"purchaseLimit": 1000,
"timesUsed": 247,
"includesAllOffers": true,
"excludedOffers": []
}
}
}Related resources
Last updated