Tillwire Read the guide
API reference

Promotions. 5 operations.

5 of them work. Each needs a bearer token with its scope. All operations.

Operations

POST/api/v1/promotionspromotions.createpromotions.write

Parameters

Idempotency-KeyheaderstringSee common parameters

Request body

PromotionRequest

Answer

Promotion

Errors: 401, 403, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/promotions

POST/api/v1/promotions/{id}/endpromotions.endpromotions.write

Parameters

idpathstring
idpathstring
Idempotency-KeyheaderstringSee common parameters

Errors: 401, 403, 404, 405, 409, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/promotions/{id}/end

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

limitqueryintegerThe 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.
afterquerystringSee 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

Parameters

idpathstring
idpathstring
Idempotency-KeyheaderstringSee common parameters

Request body

PromotionRequest

Errors: 401, 403, 404, 405, 409, 413, 422, 429

curl -X POST -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/promotions/{id}

GET/api/v1/promotions/{id}/usespromotions.usespromotions.read

Parameters

idpathstring
idpathstring
pagequeryintegerSee common parameters

Errors: 401, 403, 404, 405, 422, 429

curl -X GET -H "Authorization: Bearer $TOKEN" https://yourshop.example/api/v1/promotions/{id}/uses

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.

categoryrequiredstring
descriptionrequiredstring
kindrequiredstring
slugrequiredstring
tiersrequiredarray of BuilderTier
titlerequiredstring
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.

categorystring
descriptionstring
kindrequiredstring
slugrequiredstring
tiersrequiredarray of BuilderTierRequest
titlerequiredstring
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.

amountMoney
minrequiredstring
percentstring
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.

amountstring
minrequiredstring
percentstring
Money

Money is an amount: in minor units of its ISO 4217 currency, and as the store displays it.

currencyrequiredstring
displayrequiredstring
minorrequiredinteger
Promotion

Promotion is a promotion as the owner sees it: a rule with conditions and one effect.

amountMoney
builderBuilder
codestring
created_atrequiredstring (date-time)
effectrequiredstring
ended_atstring (date-time)
endsstring (date-time)
idrequiredinteger
labelrequiredstring
min_totalMoney
namerequiredstring
per_email_limitrequiredinteger
percentstring
productsrequiredarray of string
rolesrequiredarray of string
showrequiredboolean
shownrequiredboolean
startsstring (date-time)
textrequiredstring
text_shownrequiredstring
total_limitrequiredinteger
usesrequiredinteger
PromotionChange

PromotionChange is a promotion as an operation left it, and whether the operation changed it.

changedrequiredboolean
promotionrequiredPromotion
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.

amountstring
builderBuilderRequest
codestring
effectrequiredstring
endsstring
labelstring
min_totalstring
namerequiredstring
per_email_limitstring
percentstring
productsarray of string
rolesarray of string
showboolean
startsstring
textstring
total_limitstring
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).

emailrequiredstring
orderrequiredinteger
released_atstring (date-time)
taken_atrequiredstring (date-time)
PromotionUseList

PromotionUseList is a page of a coupon's uses, newest first, how many it has in all, and whether more follow.

morerequiredboolean
ofrequiredinteger
usesrequiredarray 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.