Promotions. 5 operations.
5 of them work. Each needs a bearer token with its scope. All operations.
Operations
POST/api/v1/promotionspromotions.createpromotions.write
POST/api/v1/promotions/{id}/endpromotions.endpromotions.write
GET/api/v1/promotionspromotions.listpromotions.read
Read a page at a time: give limit (1 to 500; 100 when none is given) and after, the Next-Cursor of the page before. Follow the Link, rel next, to the rest.
Parameters
limitquery | integerThe most promotions in the page: 1 to 500; 100 when the call gives no limit. The Next-Cursor and Link headers name the next page. |
afterquery | stringSee common parameters |
Answer
array of Promotion
Errors: 400, 401, 403, 405, 422, 429
curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/promotions
POST/api/v1/promotions/{id}promotions.updatepromotions.write
Schemas 10
Builder
Builder is a combo builder as the owner sees it: the page it has at /builders/{slug}, what it counts, and its tiers in order.
categoryrequired | string |
descriptionrequired | string |
kindrequired | string |
slugrequired | string |
tiersrequired | array of BuilderTier |
titlerequired | string |
BuilderRequest
BuilderRequest is a combo builder as the owner creates it: the slug of its page, its title and description, what it counts (Kind, count or value), its set (Category, or the request's Products), and its tiers, each from a higher Min and a higher discount than the tier before, all of one kind of discount.
category | string |
description | string |
kindrequired | string |
slugrequired | string |
tiersrequired | array of BuilderTierRequest |
titlerequired | string |
BuilderTier
BuilderTier is a tier of a combo builder: from Min, text as the owner entered it (a whole number of items, or a price for a builder by value), it takes Percent off, or Amount.
amount | Money |
minrequired | string |
percent | string |
BuilderTierRequest
BuilderTierRequest is a tier of a combo builder as the owner enters it: Min, a whole number of items (or a price with exactly two decimals for a builder by value), and Percent or Amount, one of them.
amount | string |
minrequired | string |
percent | string |
Money
Money is an amount: in minor units of its ISO 4217 currency, and as the store displays it.
currencyrequired | string |
displayrequired | string |
minorrequired | integer |
Promotion
Promotion is a promotion as the owner sees it: a rule with conditions and one effect.
amount | Money |
builder | Builder |
code | string |
created_atrequired | string (date-time) |
effectrequired | string |
ended_at | string (date-time) |
ends | string (date-time) |
idrequired | integer |
labelrequired | string |
min_total | Money |
namerequired | string |
per_email_limitrequired | integer |
percent | string |
productsrequired | array of string |
rolesrequired | array of string |
showrequired | boolean |
shownrequired | boolean |
starts | string (date-time) |
textrequired | string |
text_shownrequired | string |
total_limitrequired | integer |
usesrequired | integer |
PromotionChange
PromotionChange is a promotion as an operation left it, and whether the operation changed it.
changedrequired | boolean |
promotionrequired | Promotion |
PromotionRequest
PromotionRequest is a promotion the owner creates, every value as text: the effect, one of percent_off, amount_off and free_shipping, with its percent or its amount (text with exactly two decimals); and its conditions, each optional: the cart total it needs, the products it is for by slug, the roles it is for (owner, buyer, guest), and when it starts and ends, each a date such as 2026-10-01 or a date and time such as 2026-10-01T08:00 in store.timezone.
amount | string |
builder | BuilderRequest |
code | string |
effectrequired | string |
ends | string |
label | string |
min_total | string |
namerequired | string |
per_email_limit | string |
percent | string |
products | array of string |
roles | array of string |
show | boolean |
starts | string |
text | string |
total_limit | string |
PromotionUse
PromotionUse is one use of a coupon: the number of the order that took it, the email it was taken by (an erased order's keeps none of its buyer's), when, and when it was released, absent while it is held (from version 6).
emailrequired | string |
orderrequired | integer |
released_at | string (date-time) |
taken_atrequired | string (date-time) |
PromotionUseList
PromotionUseList is a page of a coupon's uses, newest first, how many it has in all, and whether more follow.
morerequired | boolean |
ofrequired | integer |
usesrequired | array of PromotionUse |
Made from engine/internal/openapi/openapi.json at commit 6c4cbd921. The contract-only operations come from the engine’s stub file, engine/internal/ops.