API Changelog

Changes to the STOQ API and MCP server that can affect an integration. Newest first. Each entry says what changed, who it affects, and what to send instead.

The API v2 Reference is generated from the code on every deploy, so it always shows the current request fields.

2026-09-22 — Discount value no longer clears the discount

What changed: PATCH /preorders/offers/{id}/payments with { "discount": { "value": 25 } } and no type now keeps the offer's current discount type and changes the amount. Before, it removed the discount and still returned 202.
Who it affects: callers that change the discount amount without sending type.
What to send: nothing new. To remove a discount, send { "discount": { "type": "no_discount" } }.
Source: #3955

2026-09-21 — `display.show_shipping_timeline` removed from preorder shipping

What changed: display.show_shipping_timeline is gone from PATCH /preorders/offers/{id}/shipping and from the shipping.display block in offer and shipping reads. The setting has done nothing since the simplified shipping text was retired (#3308). Every offer shows the detailed shipping timeline.
Who it affects: callers that send or read display.show_shipping_timeline.
What to send instead: drop the field. To change the text shoppers see, use POST /preorders/offers/{id}/shipping/set_shipping_text or display.shipping_text.
Source: commit 7038fe23a

2026-09-21 — Writes with no known setting now fail

What changed: a v2 write where none of the sent keys is a setting the action can change now returns 422 with code unmapped_settings. The error lists the keys the action accepts. Before, it returned 202 and changed nothing.
Who it affects: callers that send misspelled or removed field names, for example display.show_shipping_timeline.
What to send instead: the keys named in the error, or the fields in the action's request schema.
Source: commit 7038fe23a

2026-09-19 — `email_template_enabled` on back-in-stock templates

What changed: PATCH /back_in_stock/templates/{stage}/{locale} accepts email_template_enabled. false goes back to the standard STOQ email. true uses the custom HTML email template.
Who it affects: callers that manage custom HTML alert emails.
Source: commit 298f0f5fa

2026-09-18 — Back-in-stock templates: `stage` path segment and new fields

What changed: the template path is now /back_in_stock/templates/{stage}/{locale}. stage is initial, reminder or signup_thank_you. The old values 0 and 1 still work for initial and reminder. The update action adds enabled (turns the reminder or the signup thank-you on or off), flat colour fields (email_background_color, email_text_color, email_button_background_color, email_button_text_color, email_social_icon_color) and social link fields (email_facebook_link, email_instagram_link, email_pinterest_link, email_twitter_link, email_tiktok_link, email_whatsapp_link, email_youtube_link).
Who it affects: callers of the back-in-stock template actions. Existing 0/1 calls keep working.
What to send instead: use the stage names in new code.
Source: #3894

2026-09-16 — Hold back-in-stock alerts while the store is password protected

What changed: PATCH /back_in_stock/settings/delivery accepts send_while_password_protected. The default is false: alerts are held while the storefront password is on, and signups stay pending for the next restock.
Who it affects: stores with a storefront password. Alerts that used to send during a password period are now held unless you set send_while_password_protected: true.
Source: #3858

2026-09-16 — Progress bar box background colour

What changed: POST /preorders/offers/{id}/limits/set_progress_bar accepts box_background_color. When it is not set, the box keeps using the disclaimer background colour.
Who it affects: callers that style the preorder progress bar.
Source: #3874

2026-09-16 — Default-locale writes update the main text

What changed: a template or translation write for the store's default locale now updates the main text. Before, it was saved as a translation for that locale and the shopper-facing text did not change.
Who it affects: callers that pass the store's own default locale to template, notification, offer translation or signup widget writes.
Source: #3861

2026-09-08 — "In-stock" preorder mode only on Specific-products offers

What changed: POST /preorders/offers/{id}/inventory/set_provider with shopify (show Preorder for in-stock products) now returns 422 on All-products and Collection offers. Before, it silently turned the offer into a Specific-products offer.
Who it affects: callers that set the provider on All-products or Collection offers.
What to send instead: switch the offer to Specific products first, or keep the stoq provider.
Source: #3709

2026-09-02 — Split orders need an explicit `split.type`

What changed: PATCH /preorders/offers/{id}/shipping with fulfillment.split.enabled: true and no fulfillment.split.type now returns 422. enabled: false still turns splitting off. On PATCH /preorders/offers/{id}/payments, sending remaining_balance.auto_collect and remaining_balance.auto_collect_on_fulfillment both as true now returns 422.
Who it affects: callers that turn on splitting with enabled alone, or that set both auto-collect options.
What to send instead: { "fulfillment": { "split": { "enabled": true, "type": "orders" } } } (or "fulfillments"). Pick one auto-collect option.
Source: #3628

2026-09-01 — `fulfillment.split.type` on preorder shipping

What changed: shipping reads and writes carry fulfillment.split.type (fulfillments, orders or null). Split fulfillments and split orders are two separate settings. Before, reads reported one combined enabled flag.
Who it affects: callers that read or write order splitting.
Source: #3588

2026-09-01 — New filters and read actions

What changed:
- GET /preorders/offers takes search, status, market_ids and sort (#3571).
- GET /preorders/orders takes search (#3576). GET /back_in_stock/signups takes query (#3494).
- Back-in-stock reports (summary, signups, conversions, products_in_demand) and GET /preorders/reports/by_date take market_id (#3557).
- New reads: GET /back_in_stock/orders (#3576), GET /back_in_stock/products/{variant_id}/notification_status (#3577), GET /preorders/offer_lookup (#3566), GET /account/settings/{section_id} (#3573), GET /account/templates/{campaign_type}/translations (#3597), GET /account/translations (#3598).
- GET /preorders/offers/{id}/translations also returns each field's default-locale source text and the store's published locales (#3596).
Who it affects: nobody has to change anything. These are additions.

2026-08-31 — OAuth for the MCP server

What changed: the MCP server at /api/v2/external/mcp supports OAuth 2.1, so MCP clients such as Claude and ChatGPT connectors can connect without pasting an API key (#3551). Clients can register themselves automatically (#3641). OAuth grants now expire, can be revoked, and are bound to the client that got them (#3731).
Who it affects: MCP clients. The X-Auth-Token header still works.
Source: #3551, #3641, #3731

2026-08-28 — New read actions

What changed: new reads: GET /back_in_stock/reports/wait_duration (#3493), GET /account/markets and GET /account/products (#3494), GET /preorders/orders/{id}/timeline (#3497), GET /account/plan_usage (#3498), GET /back_in_stock/reports/engagement and GET /preorders/reports/engagement (#3501), GET /preorders/products/inventory_status (#3502), GET /account/help_docs (#3503).
Who it affects: nobody has to change anything. These are additions.

2026-08-25 — Paid-plan features enforced on the server

What changed: v2 and MCP writes now check the store's plan. On a free plan, a write that changes a paid-only setting fails with 422 and an error that names the paid feature. Nothing in that write is saved.
Who it affects: integrations on free-plan stores that change paid-only settings.
What to send instead: leave the paid-only fields out, or upgrade the plan.
Source: #3372