--- title: "Update a countdown on an offer" description: "Update any subset of the countdown timer settings on a preorder offer." url: https://docs.stoqapp.com/v2-reference/preorders-offers/update-a-countdown-on-an-offer/ api: "API v2 reference" method: PATCH path: "/preorders/offers/{id}/countdown" --- # Update a countdown on an offer `PATCH https://app.stoqapp.com/api/v2/external/preorders/offers/{id}/countdown` Update any subset of the countdown timer settings on a preorder offer. **Note:** Deep partial: absent fields are unchanged; current is read-only. ## Path parameters - `id` (string, required) ## Headers - `Idempotency-Key` (string): A fresh unique key for every write (a new UUID, say); reuse it only to retry that write. Keys are remembered for 1 hour: the same key and the same request within that hour returns the first result, with `Idempotent-Replayed: true`, without running again; the same key with a different method, path or body is refused (422 `idempotency_key_reused`); a retry while the first is still running gets 409 `idempotency_key_in_progress`. Keys are per store. Server errors and rate limits are not kept, so their retry runs. ## Request body - `show_when` (string): disabled hides the timer; before_launch counts down to the start, during_preorder to the end, both to the start and then the end. It is read back from the dates: both switches date_source to schedule unless date_source is sent, and with custom dates before_launch clears ends_at and during_preorder clears starts_at. One of: `disabled`, `before_launch`, `during_preorder`, `both`. - `date_source` (string): schedule uses the offer schedule start and end dates; custom uses starts_at and ends_at. One of: `schedule`, `custom`. - `starts_at` (string): Custom launch date and time. Without Z or an offset it is the shop's local time (2026-09-30T18:00). null clears it. Used when date_source is custom. - `ends_at` (string): Custom deadline date and time. Without Z or an offset it is the shop's local time (2026-09-30T18:00). null clears it. Used when date_source is custom. - `starts_text` (string): Heading shown before launch. - `ends_text` (string): Heading shown during the preorder. - `labels` (object) - `days` (string): Days label. - `hours` (string): Hours label. - `minutes` (string): Minutes label. - `seconds` (string): Seconds label. - `text_color` (string): Timer text color. Hex. - `background_color` (string): Timer background color. Hex. - `border_radius` (integer): Corner radius in pixels. - `units` (array of anys): Time units to display, any of days, hours, minutes, seconds. - `locale` (string): Language the translated fields are written in, such as 'fr' or 'pt-BR'. Omitted: the shop's default language. Untranslated fields ignore it. ## Returns - `show_when` (string): e.g. `during_preorder` - `date_source` (string): e.g. `custom` - `starts_at` (any) - `ends_at` (string): e.g. `2026-09-30T18:00:00Z` - `starts_text` (any) - `ends_text` (any) - `labels` (object) - `days` (string): e.g. `Days` - `hours` (string): e.g. `Hours` - `minutes` (string): e.g. `Mins` - `seconds` (string): e.g. `Secs` - `text_color` (string): e.g. `#000000` - `background_color` (string): e.g. `#f5f5f5` - `border_radius` (integer): e.g. `8` - `units` (array of strings) - `current` (object) - `visible_phase` (string): e.g. `during_preorder` - `target_at` (string): e.g. `2026-09-30T18:00:00Z` - `heading_text` (any) Rate limit: this call costs 2 points ([rate limits](https://docs.stoqapp.com/docs/rate-limits/)). ## Example request ```sh curl -X PATCH "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/countdown" \ -H "X-Auth-Token: $STOQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "show_when": "during_preorder", "date_source": "custom", "ends_at": "2026-09-30T18:00:00Z" }' ``` ## 200 Success: example response shown. ```json { "show_when": "during_preorder", "date_source": "custom", "starts_at": null, "ends_at": "2026-09-30T18:00:00Z", "starts_text": null, "ends_text": null, "labels": { "days": "Days", "hours": "Hours", "minutes": "Mins", "seconds": "Secs" }, "text_color": "#000000", "background_color": "#f5f5f5", "border_radius": 8, "units": [ "days", "hours", "minutes", "seconds" ], "current": { "visible_phase": "during_preorder", "target_at": "2026-09-30T18:00:00Z", "heading_text": null } } ``` ## 202 Saved. Returns the updated section, with also_changed for cascades. ## 401 Missing or invalid `X-Auth-Token`. ```json { "errors": [ "Invalid API key" ], "code": "auth_invalid", "details": [ { "code": "auth_invalid", "message": "Invalid API key", "path": null, "value": null, "expected": null } ] } ``` ## 404 The resource does not exist for this shop, or the action path is not registered. ```json { "errors": [ "Offer not found" ], "code": "not_found", "details": [ { "code": "not_found", "message": "Offer not found", "path": null, "value": null, "expected": null } ] } ``` ## 409 An earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key. ```json { "errors": [ "A request with this Idempotency-Key is still running" ], "code": "idempotency_key_in_progress", "details": [ { "code": "idempotency_key_in_progress", "message": "A request with this Idempotency-Key is still running", "path": null, "value": null, "expected": null } ] } ``` ## 422 Invalid fields: one `details` entry per field error, its `path` the canonical section path. Nothing was saved. ```json { "errors": [ "widget.button.text_color must be a hex color" ], "code": "invalid_params", "details": [ { "code": "invalid_params", "message": "must be a hex color", "path": "widget.button.text_color", "value": "blue", "expected": { "type": "string" } } ] } ``` ## 429 Rate limited: cost-weighted per token (read 1, write 2; 360 points / 60s). Check `Retry-After`. ```json { "errors": [ "Rate limit exceeded" ], "code": "rate_limited", "details": [ { "code": "rate_limited", "message": "Rate limit exceeded", "path": null, "value": null, "expected": null } ] } ```