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=live" \
  -H "X-Auth-Token: $STOQ_API_KEY"

The list has names and ids but no product titles. To find which offer a product is in, search the variants instead; each result carries an offers array with the offer ids:

curl "https://app.stoqapp.com/api/v2/external/preorders/products?search=snowboard" \
  -H "X-Auth-Token: $STOQ_API_KEY"

GET /preorders/offers/:id/products only returns the selection rules and a variant_count; the product and variant titles of one offer are at GET /preorders/offers/:id/products/variants.

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 '{ "shopify_variant_ids": ["gid://shopify/ProductVariant/43900910010503", "gid://shopify/ProductVariant/43900910043271"] }'

If another offer already has the variants, a sales channel can’t sell preorders, or “Continue selling” is off where STOQ won’t turn it on, nothing is added and the answer is 409 with code: "preflight_issues" and the issues under preflight. unresolved lists the fixes needed. Resend with resolve: { remove_from_conflicting_offers: true, enable_continue_selling: true, skip_sales_channel_products: true } (the keys you need) to fix them as the dashboard’s pre-flight modal does, or skip_preflight: true to add anyway. The 202 lists what was fixed under resolved.

That check is the offer’s Products page pre-flight. The store-wide Preorders > Products tab’s “Add to offer” has none, and neither does its API path:

curl -X POST https://app.stoqapp.com/api/v2/external/preorders/products/add_to_offer \
  -H "X-Auth-Token: $STOQ_API_KEY" -H "Content-Type: application/json" \
  -d '{ "offer_id": "{id}", "shopify_variant_ids": ["gid://shopify/ProductVariant/43900910010503"], "inventory_policy": "CONTINUE" }'

It adds the variants even when another offer has them, “Continue selling” is off or a sales channel can’t sell preorders, leaves out variants a market-specific offer owns (skipped_market_variant_count), and with inventory_policy: "CONTINUE" turns “Continue selling” on for them on an out-of-stock offer. Up to 100 variants, finished before the response.

Release held preorder orders

Preorder orders sit on hold until you release them (e.g. when stock lands). Release is a named action, like the dashboard’s Release. It releases every hold on the order’s held fulfillments, applies no tags and doesn’t check payment. It returns 409 on a cancelled or fulfilled order. {order_id} is STOQ’s order id or the Shopify order id or gid.

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}/collect_payment \
  -H "X-Auth-Token: $STOQ_API_KEY"

Show the Preorder button on collection, home and search pages

Product pages always show the Preorder button. Other pages are shop-wide settings (the dashboard’s Preorders > Settings > Pages), read with GET /preorders/settings/pages and changed with a deep-partial PATCH:

curl -X PATCH https://app.stoqapp.com/api/v2/external/preorders/settings/pages \
  -H "X-Auth-Token: $STOQ_API_KEY" -H "Content-Type: application/json" \
  -d '{ "collection": { "enabled": true, "show_badge_if_any_variant_is_preorder": true }, "search": { "enabled": true } }'

The fields are home.enabled, collection.enabled, collection.show_badge_if_any_variant_is_preorder and search.enabled. The page’s CSS selectors (Dev mode) are PATCH /preorders/settings/developer. Each insert_type there is beforebegin, afterbegin, beforeend or afterend (where the element goes relative to the selector’s element); any other value returns 422.

Send a test email

Send a template to yourself before customers see it. The body’s email defaults to the shop’s reply-to address, and the email renders in the body’s locale (default: the shop’s default language):

curl -X POST https://app.stoqapp.com/api/v2/external/back_in_stock/templates/restock_alert/send_test \
  -H "X-Auth-Token: $STOQ_API_KEY" -H "Content-Type: application/json" \
  -d '{ "email": "me@example.com", "locale": "en" }'

The preorder confirmation email is POST /preorders/templates/confirmation/send_test, with an optional locale in the body. It shows one of your own preorder products: pass offer_id and shopify_variant_id (a variant gid) to pick it, or leave them out for the first product of your first enabled offer. Both take one address and return 422 when email sending is turned off for the shop.

Bulk + async

Bulk operations return 202 Accepted with { job_id, status_url }. Poll the status URL until a terminal status — see Bulk & async jobs.

Note

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.