---
title: "Get shipping"
description: "Read the shipping settings of 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/get-shipping/
api: "API v2 reference"
method: GET
path: "/preorders/offers/{id}/shipping"
---

# Get shipping

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

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

**Note:** `shipping_text` is the line under the Preorder button, shown while `show_shipping_text` is true. With `timeline.scope` `per_variant` each variant's own `shipping_text` ([`GET /preorders/offers/:id/products/variants`](https://docs.stoqapp.com/v2-reference/preorders-offers/list-an-offers-variants/)) is used, falling back to `variant_shipping_text`. `delivery_timing` `exact_time` has either `ships_at` or `days_after_checkout`; `asap` and `unknown` have neither. `separate_orders` applies only while `fulfillment.handling` is `separate_orders`, and `on_hold.release_at` only while `release_schedule` is `scheduled`. Edit with [`PATCH /preorders/offers/:id/shipping`](https://docs.stoqapp.com/v2-reference/preorders-offers/update-shipping/).

## Path parameters

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

## Query parameters

- `locale` (string): Language for translated text, such as fr or pt-BR. Omit for the shop's default language.

## 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` (null): Ship date, ISO 8601 in UTC. Null unless delivery_timing is exact_time with a fixed date.
- `days_after_checkout` (null): 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` (null): Tag on the original order while it is being split, removed once the split finishes. Null when none is set.
    - `original_order_split_tag` (null): 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` (null): When held fulfillments are released, ISO 8601 in UTC. Null when not set.
  - `require_payment` (boolean): Only release once the balance is paid.

Rate limit: this call costs 1 point ([rate limits](https://docs.stoqapp.com/docs/rate-limits/)).

## Examples

### Get shipping

```sh
curl "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/shipping" \
  -H "X-Auth-Token: $STOQ_API_KEY"
```

### Get shipping filtered by locale

```sh
curl "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/shipping?locale=fr" \
  -H "X-Auth-Token: $STOQ_API_KEY"
```

## 200

Success: example response shown.

```json
{
  "timeline": {
    "scope": "same",
    "show_shipping_text": true,
    "shipping_text": "Ships by {{ date }}",
    "variant_shipping_text": "15 Aug 2026"
  },
  "delivery_timing": "exact_time",
  "ships_at": "2026-08-15T04:00:00Z",
  "days_after_checkout": null,
  "fulfillment": {
    "handling": "none",
    "hold_reason": "Order contains a preorder product. All fulfillments are on hold, as configured in STOQ > Preorders.",
    "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
    }
  ]
}
```

## 422

The request failed validation.

```json
{
  "errors": [
    "name is required"
  ],
  "code": "validation_failed",
  "details": [
    {
      "code": "validation_failed",
      "message": "name is required",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

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

