> For the complete documentation index, see [llms.txt](https://docs.shipide.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shipide.com/orders-and-shipments.md).

# Orders and shipments

An **order** records the shipping request from your order system. A **shipment** records a packed parcel. You may create shipments directly without creating orders first.

## Create

`POST /orders` and `POST /shipments` accept the same shipping fields. Only shipments accept `order_id`, which optionally links to an existing order in the same account and environment.

| Field       | Required | Meaning                                                     |
| ----------- | -------- | ----------------------------------------------------------- |
| `reference` | Yes      | Your order or warehouse reference, up to 200 characters     |
| `from`      | Yes      | Sender address                                              |
| `to`        | Yes      | Recipient address                                           |
| `parcel`    | Yes      | Packed parcel's weight and dimensions                       |
| `order_id`  | No       | Existing order ID, for shipment creation only               |
| `metadata`  | No       | Custom JSON object, at most 4096 characters when serialized |

Each address requires `name`, `street1`, `city`, `postal_code`, and `country`. Optional fields: `company`, `street2`, `state`, `email`, `phone`. Address values are strings up to 200 characters; `country` must be a two-letter code, for example `BE`, `NL`, or `FR`.

The parcel requires numeric `weight_kg`, `length_cm`, `width_cm`, and `height_cm`, all greater than zero and at most 1000. These are input limits, not a guarantee of carrier acceptance. Unknown fields are rejected to catch mapping mistakes.

Orders begin in `received` state. Shipments begin in `draft`, become `label_created` when a label is issued, and become `voided` when that label is voided. Each shipment can have one label. Create a new shipment to replace a voided label.

The API currently accepts one parcel per shipment. For an order with several parcels, create a shipment per parcel with the same order ID and distinct idempotency keys. Customs documents, multi-parcel carrier bookings, manifests, pickups, and returns are not yet available through this version.

## Retrieve and list

```http
GET /orders/{id}
GET /shipments/{id}
GET /orders?limit=25
GET /shipments?limit=25&after=shp_PREVIOUS_CURSOR
```

List responses contain `data` and `next_cursor`. Pass `next_cursor` as `after` until it is `null`. `limit` defaults to 25 and supports 1 to 100. Results are ordered by opaque ID, not chronologically. This is not a snapshot: concurrent inserts can appear before your cursor. Use webhooks for ongoing intake events rather than relying on list polling to discover every new record.

Records created through this API are retrieved through the API. They do not yet appear in the portal's legacy label-generation history or monthly billing, because live label booking has not been activated.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.shipide.com/orders-and-shipments.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.