Common tasks
Recipes for the things merchants and integrations do most. All calls use the X-Auth-Token header; see Getting Started.
Find existing preorder offers
List the shop's selling-plan offers (filter by status, paginate):
curl "https://app.stoqapp.com/api/v2/external/preorders/offers?status=enabled" \
-H "X-Auth-Token: $STOQ_API_KEY"Grab an offer's id from the list, then read one:
curl https://app.stoqapp.com/api/v2/external/preorders/offers/{id} \
-H "X-Auth-Token: $STOQ_API_KEY"Enable or disable an offer
State changes are named actions — not a settings PATCH:
curl -X POST https://app.stoqapp.com/api/v2/external/preorders/offers/{id}/enable \
-H "X-Auth-Token: $STOQ_API_KEY"Attach variants to an offer
curl -X POST https://app.stoqapp.com/api/v2/external/preorders/offers/{id}/products/add_variants \
-H "X-Auth-Token: $STOQ_API_KEY" -H "Content-Type: application/json" \
-d '{ "variant_ids": [43900910010503, 43900910043271] }'Release held preorder orders
Preorder orders sit on hold until you release them (e.g. when stock lands). Release is a named action; it returns 409 if the balance hasn't been collected — pass force: true to override.
curl -X POST https://app.stoqapp.com/api/v2/external/preorders/orders/{order_id}/release \
-H "X-Auth-Token: $STOQ_API_KEY"Charge a remaining balance
For partial/deposit preorders, collect the rest:
curl -X POST https://app.stoqapp.com/api/v2/external/preorders/orders/{order_id}/payments/charge_balance \
-H "X-Auth-Token: $STOQ_API_KEY"Bulk + async
Bulk operations return 202 Accepted with { job_id, status_url }. Poll the status URL until a terminal status — see Bulk & async jobs.
Not sure of an action's exact path or body? GET /api/v2/external/help?prefix=/preorders returns the manifest for everything under preorders, with each action's schema and aliases. The full action list is in the API v2 Reference.
