---
title: "Update shipping"
description: "Update any subset of the shipping settings on a preorder offer: the shipping timeline text, delivery timing, fulfillment handling (hold, split or separate orders) and hold release."
url: https://docs.stoqapp.com/v2-reference/preorders-offers/update-shipping/
api: "API v2 reference"
method: PATCH
path: "/preorders/offers/{id}/shipping"
---

# Update shipping

`PATCH https://app.stoqapp.com/api/v2/external/preorders/offers/{id}/shipping`

Update any subset of the shipping settings on a preorder offer: the shipping timeline text, delivery timing, fulfillment handling (hold, split or separate orders) and hold release.

**Note:** Deep partial: absent fields are unchanged, null clears. Settings the save changes on its own (the purchase option and payments when separate orders turns on, split fulfillments when delivery leaves asap) are listed in also_changed. reschedule_existing_orders: true is the editor's &quot;Reschedule existing orders to this date&quot; checkbox: after the save, every unfulfilled, uncancelled preorder on the offer has its scheduled fulfillments moved to the offer's ship date (ships_at), or to its own order date plus days_after_checkout, in the background. It needs delivery_timing exact_time after the save, can be sent alone to re-apply the current date, and does not email customers (send a shipping update from the orders endpoints for that). When sent, the response has rescheduled_orders_queued.

## Path parameters

- `id` (string, required): The offer's ID, from [`GET /preorders/offers`](https://docs.stoqapp.com/v2-reference/preorders-offers/list-offers/).

## 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

- `timeline` (object): The shipping timeline text shown with the preorder button.
  - `scope` (string): same shows one shipping text for every product; per_variant uses each variant's own shipping text (set per variant). One of: `same`, `per_variant`.
  - `show_shipping_text` (boolean): Show shipping timeline on the widget. Also turns the cart line-item property (advanced.cart_attributes.show_shipping) on or off when it changes, as the editor does; sending the current value changes nothing.
  - `shipping_text` (string): The line under the preorder button. Required while show_shipping_text is true.
- `delivery_timing` (string): Fulfillment status of preorder items: asap is Unfulfilled (ship now), exact_time is Scheduled (needs ships_at or days_after_checkout and the Shopify purchase option), unknown is On hold (no date promised). asap and unknown clear ships_at and days_after_checkout. One of: `asap`, `exact_time`, `unknown`.
- `ships_at` (string): Ship date: a date (2026-11-05), read as midnight in the shop time zone, or an ISO 8601 datetime (kept as that exact moment). Returned as the UTC datetime. Sending it alone makes delivery_timing exact_time on that date. Also sets timeline.variant_shipping_text (the {{ date }} value) to the date in the shop time zone, as the editor does: &quot;05 Nov 2026&quot;.
- `days_after_checkout` (integer): Ship N days after checkout. Sending it alone makes delivery_timing exact_time with that delay; ships_at is then null. Also sets timeline.variant_shipping_text to &quot;N days after checkout&quot;, as the editor does.
- `fulfillment` (object): How preorder items are fulfilled - held, split, or moved to a separate order.
  - `handling` (string): none; hold_all holds every fulfillment; split_fulfillments ships in-stock items first (needs delivery_timing asap); separate_orders moves preorder items to their own order, which switches the Shopify purchase option off and resets partial payment, the discount and a Scheduled status (listed in also_changed). One of: `none`, `hold_all`, `split_fulfillments`, `separate_orders`.
  - `hold_reason` (string): The hold reason shown in Shopify.
  - `separate_orders` (object)
    - `grouping` (string): offer creates one separate order per offer; variant one per variant; ship_date one per ship date (batch or shipping text), which needs timeline.scope per_variant or batches on. One of: `variant`, `offer`, `ship_date`.
    - `number_format` (string): sequential gives each separate order its own order number; suffix appends suffix to the original order name. One of: `sequential`, `suffix`.
    - `suffix` (string): Suffix appended to the separate order name.
    - `hold_fulfillments` (boolean): Hold fulfillments on the separate order until they're released.
    - `tag` (string): Tag applied to the separate preorder order.
    - `transaction_gateway` (string): Payment gateway recorded on the separate order transaction.
    - `original_order_hold_tag` (string): Tag on the original order while it is being split. Removed once the split finishes.
    - `original_order_split_tag` (string): Tag on the original order after the preorder items move to a separate order.
- `on_hold` (object): When held fulfillments are released.
  - `release_schedule` (string): scheduled releases held fulfillments on release_at; manual leaves them held. One of: `scheduled`, `manual`.
  - `release_at` (string): ISO 8601. Required while release_schedule is scheduled.
  - `require_payment` (boolean): Only release once the balance is paid.
- `reschedule_existing_orders` (boolean): true also moves the scheduled fulfillments of existing unfulfilled preorders on this offer to the ship date (ships_at, or each order date plus days_after_checkout), as the editor's &quot;Reschedule existing orders to this date&quot; checkbox does. Needs delivery_timing exact_time. No customer email.
- `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

- `timeline` (object): The shipping timeline text shown with the preorder button.
  - `scope` (string): same shows one shipping text for every product; per_variant uses each variant's own shipping text. One of: `same`, `per_variant`.
  - `show_shipping_text` (boolean): Whether the shipping timeline shows on the widget.
  - `shipping_text` (string): The line under the preorder button. A {{ date }} placeholder is filled with variant_shipping_text.
  - `variant_shipping_text` (string): Ship date text for a variant that has no shipping text of its own, and for every variant when scope is same.
- `delivery_timing` (string): Fulfillment status of preorder items: asap is Unfulfilled (ship now), exact_time is Scheduled (on ships_at or days_after_checkout), unknown is On hold (no date promised). One of: `asap`, `exact_time`, `unknown`.
- `ships_at` (string, nullable): Ship date, ISO 8601 in UTC. Null unless delivery_timing is exact_time with a fixed date.
- `days_after_checkout` (integer, nullable): Days after checkout that items ship. Null unless delivery_timing is exact_time with a delay instead of a date.
- `fulfillment` (object): How preorder items are fulfilled: held, split, or moved to a separate order.
  - `handling` (string): none; hold_all holds every fulfillment; split_fulfillments ships in-stock items first; separate_orders moves preorder items to their own order. One of: `none`, `hold_all`, `split_fulfillments`, `separate_orders`.
  - `hold_reason` (string): Hold reason shown in Shopify on held fulfillments.
  - `separate_orders` (object): Settings for separate orders, used when handling is separate_orders.
    - `grouping` (string): offer creates one separate order per offer, variant one per variant, ship_date one per ship date. One of: `offer`, `variant`, `ship_date`.
    - `number_format` (string): sequential gives each separate order its own order number; suffix appends suffix to the original order name. One of: `sequential`, `suffix`.
    - `suffix` (string): Suffix appended to the separate order name.
    - `hold_fulfillments` (boolean): Whether fulfillments on the separate order are held until released.
    - `tag` (string): Tag applied to the separate preorder order.
    - `transaction_gateway` (string): Payment gateway recorded on the separate order's transaction. Default &quot;Prepaid&quot;.
    - `original_order_hold_tag` (string, nullable): Tag on the original order while it is being split, removed once the split finishes. Null when none is set.
    - `original_order_split_tag` (string, nullable): Tag on the original order after its preorder items move to a separate order. Null when none is set.
- `on_hold` (object): When held fulfillments are released.
  - `release_schedule` (string): scheduled releases held fulfillments on release_at; manual leaves them held. One of: `scheduled`, `manual`.
  - `release_at` (string, nullable): When held fulfillments are released, ISO 8601 in UTC. Null when not set.
  - `require_payment` (boolean): Only release once the balance is paid.
- `also_changed` (array of objects): Settings this write changed on its own because they depend on what you changed (turning one option off can reset another). Absent when nothing else changed.
  - `setting` (string): The setting that changed, as the dashboard names it.
  - `from` (string): Its value before the write.
  - `to` (string, nullable): Its value after the write.
  - `reason` (string): Why it changed.
  - `field_path` (string): Dotted path of the changed field in this response, when it is one.
- `rescheduled_orders_queued` (boolean): true when existing orders' fulfillments are being moved to the new ship date in the background. Only when reschedule_existing_orders was sent.

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/shipping" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "days_after_checkout": 30,
    "fulfillment": {
      "handling": "hold_all",
      "hold_reason": "Waiting on stock"
    }
  }'
```

## 202

Success: example response shown.

```json
{
  "timeline": {
    "scope": "same",
    "show_shipping_text": true,
    "shipping_text": "Shipping: {{ date }}",
    "variant_shipping_text": "ASAP"
  },
  "delivery_timing": "exact_time",
  "ships_at": null,
  "days_after_checkout": 30,
  "fulfillment": {
    "handling": "hold_all",
    "hold_reason": "Waiting on stock",
    "separate_orders": {
      "grouping": "offer",
      "number_format": "suffix",
      "suffix": "SPLIT",
      "hold_fulfillments": false,
      "tag": "STOQ-split-order",
      "transaction_gateway": "Prepaid",
      "original_order_hold_tag": null,
      "original_order_split_tag": null
    }
  },
  "on_hold": {
    "release_schedule": "manual",
    "release_at": null,
    "require_payment": false
  }
}
```

## 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
    }
  ]
}
```

