Sign in
Ecommerce: Discounts

Create a discount

Create a discount for a store. Fixed discounts take an amount in the smallest currency unit (e.g. $10 is 1000); percentage discounts take a whole-number value between 1 and 100. Free-shipping discounts ignore value. Returns the created discount.

post/api/ecommerce/v1/stores/{store_id}/discounts

Path parameters

store_idstring required
Example:store_01J8Z5F8W9K8M4A7B3C2D1E0FG

The ID of the store to create the discount for.

Request body

codestring required

The discount code customers enter at checkout.

namestring

A human-friendly discount name.

type'percentage' | 'fixed' | 'free_shipping' required

The discount type.

valueinteger required

For percentage discounts a whole number 1-100; for fixed discounts an amount in the smallest currency unit (e.g. $10 is 1000). Ignored for free_shipping.

allocation'total' | 'item'

Whether the discount applies to the cart total or to each eligible item.

starts_atstring date-time

When the discount becomes active. A bare date (2026-11-27) anchors to time_zone. Defaults to now when omitted.

ends_atstring date-time

When the discount expires. A bare date runs to the end of that day in time_zone. Never expires when omitted.

usage_limitinteger

Maximum number of times the discount can be redeemed.

min_cart_valueinteger

Minimum cart value in the smallest currency unit required for the discount to apply.

time_zonestring

IANA time zone used to interpret starts_at and ends_at.

Example request

{
  "code": "BLACKFRIDAY",
  "name": "Black Friday",
  "type": "percentage",
  "value": 20,
  "allocation": "total",
  "starts_at": "2026-01-21T07:35:04.000000Z",
  "ends_at": "2026-02-21T07:35:04.000000Z",
  "usage_limit": 100,
  "min_cart_value": 5000,
  "time_zone": "Europe/Vilnius"
}

Response

Created response

Example response

{
  "data": {
    "id": "disc_01J8Z5F8W9K8M4A7B3C2D1E0FG",
    "code": "BLACKFRIDAY",
    "name": "Black Friday",
    "type": "percentage",
    "value": 20,
    "allocation": "total",
    "starts_at": "2026-01-21T07:35:04.000000Z"
  }
}

Changes

Changed in 1 of the 88 revisions of this API.1