Skip to main content
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

MethodEndpointDescription
GET/v0/discounts/listList and filter discounts
POST/v0/discounts/createCreate a new discount
GET/v0/discounts/{discountId}Retrieve a discount
PATCH/v0/discounts/{discountId}/updateUpdate a discount
PATCH/v0/discounts/{discountId}/archiveArchive a discount

​
The Discount object

​
object
string
Object type identifier. Always "discount" for Discount objects.
​
id
string
required
Unique identifier (UUID) for this discount.
​
type
string
required
Discount type. Possible values: code (coupon code), sale (automatic discount)
​
name
string | null
Display name of the discount (e.g., “Summer Sale”, “10% Off”).
​
amount
number
required
Discount amount. For fixed: amount in currency units (e.g., 10.00 for $10). For percentage: percentage value (e.g., 15 for 15% off).
​
amountType
string
required
How the amount is applied. Possible values: fixed, percentage
​
discountCode
string | null
The coupon code customers enter. Only set when type is "code".
​
currency
string
required
Three-letter ISO 4217 currency code. Required for fixed-amount discounts.
​
status
string
required
Current discount status. Possible values: active, inactive
​
validFrom
integer | null
Unix timestamp (milliseconds) when the discount becomes valid. null means immediately valid.
​
validUntil
integer | null
Unix timestamp (milliseconds) when the discount expires. null means no expiration.
​
purchaseLimit
integer | null
Maximum number of times this discount can be used. null means unlimited.
​
timesUsed
integer
Number of times this discount has been used. Defaults to 0.
​
includesAllOffers
boolean
Whether this discount applies to all Offers. Defaults to false.
​
excludedOffers
array
Array 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": []
    }
  }
}

Offers

Offers that discounts apply to

Payments

Payments with discounts applied

Products

Products discounted via offers

Orders

Orders with discounts