Skip to main content
POST
Create Discount

Create Discount

Creates a new discount code in the store. Requires the write_discounts scope.

Request

Body Parameters

code
string
required
Unique discount code. A discount with an existing code is rejected.
type
string
required
Discount type. One of percentage, fixed_amount, free_shipping, buy_x_get_y.
value
number
required
Discount value. For percentage, enter 20 for 20%. For fixed_amount, enter the amount in the store’s currency (e.g. 20 for 20.00). Ignored for free_shipping.
minimum_amount
number
Minimum order total required for the discount to apply.
usage_limit
integer
Maximum number of times the discount can be used across all customers. Defaults to 0 (unlimited) when omitted.
once_per_customer
boolean
default:"false"
When true, limits the discount to one use per customer.
product_ids
array
Array of product IDs the discount is restricted to. Omit to apply the discount store-wide.
starts_at
string
Start date (ISO 8601). Omit for no start constraint.
ends_at
string
End date (ISO 8601). Omit for no expiration.
The merchant dashboard supports additional discount capabilities — minimum quantity, buy-X-get-Y quantities and free-item rewards, and new-customer eligibility. These are configured through the merchant surface and are not part of the OAuth App-API create body; any extra fields sent here are ignored.

Response

The created discount is returned under data.discount in the standard response envelope.

Errors

StatusstateMessage
400errorcode is required (missing code)
400errorDiscount with this code already exists
400errorValidation error (invalid type, negative value, etc.)
401errorInvalid or missing access token
403errorApp is missing the write_discounts scope