> ## Documentation Index
> Fetch the complete documentation index at: https://docs.consile.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference: Webshipper

> All 15 tools in the Webshipper connector: 12 read tools across orders, shipments and tracking, shipping costs, rate and carrier quotes, drop points, setup and returns; 3 guardrailed write tools that book shipments, update orders and create manual orders. Covers ids, pagination, date ranges, the preview-first confirm gate with expectedState, access levels, errors and data minimisation.

Webshipper is a read and guardrailed-write connector for the Webshipper shipping
platform, called via `tools/call` over `POST /webshipper/mcp`. The connector is
connected with the account name and an API token from Webshipper (see
[Connect Webshipper](https://docs.consile.ai/en/connect/connect-webshipper.md)). Your organization needs
access to Webshipper (a subscription, or a plan that covers it, see
[What decides access](https://docs.consile.ai/developers/authentication.md#what-decides-access)), and your
user must hold a seat or plan licence (assigned under **Team** in the portal, see
[Team](https://docs.consile.ai/en/portal/team.md)).

> [!NOTE]
>
> Endpoint: `https://mcp.consile.ai/webshipper/mcp`. Webshipper is its own named
> connector with only its own tools. Each tool is exposed as `webshipper__<tool>`
> (e.g. `webshipper__search_orders`); the bare names are used here for
> readability. A bare name in a request returns `Unknown tool.`
>
> The connector is multi-instance: one connection reaches exactly one Webshipper
> account. Each additional account (an agreement, **aftale**, in the portal) is
> served on its own endpoint, e.g. `https://mcp.consile.ai/webshipper-2/mcp`, with
> tools named `webshipper-2__<tool>`. Agreements are added in the portal by an
> administrator.
>
> Besides the connector tools, `tools/list` on every Webshipper endpoint includes
> the unprefixed system tool `connect_account` (no arguments). It returns
> `{ connect_url, instructions }`: a link, valid for 10 minutes, that the user
> opens in the browser to connect (or reconnect) that endpoint's account.

For an account with access to Webshipper, `tools/list` on this endpoint returns the
15 `webshipper__*` tools plus `connect_account`. Without access only
`connect_account` is listed. A user without a seat still sees the tools, but every
call is refused. Read tools are annotated `readOnlyHint: true`,
`destructiveHint: false`, `openWorldHint: false`. Write tools carry
`readOnlyHint: false` and `destructiveHint: true`; `openWorldHint` is `true` on
`create_shipment` (it reaches the carrier and can notify the recipient) and
`false` on the other two; `idempotentHint` is `true` on `update_order` and `false`
on `create_shipment` and `create_order`.

> [!WARNING]
>
> API access requires Webshipper Pro or Advanced. Webshipper's API tokens are
> scoped: a token that lacks a scope (for example for shipments or rates) is still
> accepted when the connection is made, but the tools that need that scope fail
> with a permission error, never as a dead connection (see
> [Errors](#errors-and-timeouts)).

## Shared conventions

### One account per connection

A Webshipper connection reaches exactly one account: the one named by the account
name given when the connection was made (`<account>.webshipper.io`). Every
request goes to that account's own API host. No tool takes an account argument,
and no argument can point a request at another host.

### Ids

Every Webshipper id (order, shipment, shipping rate, order channel, carrier) is a
positive integer within the account. The shop's own order number is **not** the
order id: it is `visibleRef`, which `search_orders` can filter on. Find ids with
the search and list tools.

### Pagination

`search_orders`, `search_shipments` and `search_returns` are paged by Webshipper's
fixed 30 records per page:

**page** `integer` (default: 1)

Page number, `1` to `1000`.

```json theme={null}
{ "orders": [ ... ], "page": 1, "nextPage": 2 }
```

Webshipper does not say whether more records exist, so a full page of 30 returns
`nextPage`, and a shorter page omits it. The last page can therefore be empty.

The setup lists (`list_shipping_rates`, `list_carriers`, `list_order_channels`)
are not paged. They read every page up to a cap and return `truncated: true` when
records were left out.

### Dates and countries

* **Dates** are `YYYY-MM-DD`. `createdFrom` and `createdTo` filter on the record's
  creation time and are both **inclusive**. `createdFrom` must not be after
  `createdTo`.
* **Countries** are ISO 3166-1 alpha-2 codes (`DK`, `SE`, `NO`). **Currencies**
  are ISO 4217 codes (`DKK`, `EUR`).
* **Weights** take a `weightUnit` of `g` or `kg`.

### Data minimisation

* Order channels and carriers hold the shop's access tokens and the carrier
  agreements' credentials. Those are never returned; the list tools return a
  short set of named fields only.
* Documents (packing slips, labels, return slips) and return images are never
  returned.
* Delivery and billing addresses belong to the shop's own customers. Lists return
  the recipient's name, company, postal code, city and country. `get_order` and
  `get_shipment` add phone and e-mail.
* Tracking events are capped at the 20 most recent per tracking number.

Nothing is stored at Consile; every call is a live request to Webshipper.

***

## Orders

| Tool | Description | Key arguments |
| - | - | - |
| `search_orders` | Orders with `id`, `visibleRef` (the shop's order number), `status`, `createdAt`, `orderChannelId`, `shippingRateId`, `recipient`, `lineCount`, `itemCount`, `tags`, `lockState` and Webshipper's `errorClass` / `errorMessage`. | `status?` (array of `pending`, `dispatched`, `partly_dispatched`, `cancelled`, `error`, `missing_rate`, `on_hold`), `visibleRef?` (exact), `freeText?`, `createdFrom?`, `createdTo?`, `orderChannelId?`, `countryCode?` (delivery country), `tag?`, `page` |
| `get_order` | One order: everything in the list plus `currency`, `source`, `deliveryAddress` and `billingAddress` (with phone and e-mail), `senderAddress`, `dropPoint`, `originalShipping` (the shop's own shipping choice: code, name, price), `lines` (sku, description, quantity, unit and discounted unit price, VAT %, weight), and the `slipPrinted`, `labelPrinted` and `createShipmentAutomatically` flags. | `orderId` (required) |

Orders with status `error` or `missing_rate` are the ones Webshipper could not
ship; `errorMessage` says why.

## Shipments & tracking

| Tool | Description | Key arguments |
| - | - | - |
| `search_shipments` | Shipments (parcels booked with a carrier) with `id`, `reference`, `status`, `createdAt`, `carrier`, `carrierId`, `serviceCode`, `isReturn`, `recipient`, `tracking` (number, link, latest event, delivered flag), `packageCount`, `costPrice`, `salesPrice` and `currency`. | `orderId?`, `trackingNumber?`, `reference?` (usually the shop's order number), `freeText?`, `isReturn?`, `createdFrom?`, `createdTo?`, `countryCode?`, `page` |
| `get_shipment` | One shipment: everything in the list plus the tracking events (status, time, description, location; at most 20 per tracking number), `carrierReference`, `sendTime`, `testMode`, `deliveryAddress` (with phone and e-mail), `senderAddress`, `dropPoint`, `addOns` and `packages` (weight and dimensions). | `shipmentId` (required) |

`costPrice` is what the carrier charges (from the carrier or the account's cost
sheet); `salesPrice` is what the customer paid.

## Shipping rates & costs

### summarize\_shipping\_costs

Adds up the shipments created in a period per carrier and currency. Reads at most
1,500 shipments.

**createdFrom** `string` *required*

First day, `YYYY-MM-DD`.

**createdTo** `string` *required*

Last day, included. The period may be at most 92 days.

**isReturn** `boolean`

`true` for return shipments only, `false` for outbound only; omit for both.

**shipments** `integer`

How many shipments were read.

**truncated** `boolean`

`true` when the 1,500 cap was reached. Ask for a shorter period rather than reading the totals as complete.

**byCarrier** `array`

One row per carrier and currency, most shipments first: `carrier`, `currency`, `shipments`, `costPrice`, `salesPrice` and `withoutCostPrice` (shipments with no cost price, left out of `costPrice`).

### Quotes and the rate list

| Tool | Description | Key arguments |
| - | - | - |
| `quote_shipping_rates` | Which of an order channel's configured shipping rates match a parcel, and what each costs the customer, as the checkout would show it: `shippingRateId`, `name`, `carrierName`, `carrierId`, `serviceCode`, `price`, `currency`. Nothing is stored. | `orderChannelId`, `countryCode`, `zip`, `weight`, `weightUnit` (all required); `city?`, `address1?`, `orderValue?`, `currency?`, `isReturn?`, `includeHidden?` |
| `quote_carrier_services` | Asks one connected carrier which of its services can take the packages from the sender to the recipient: service `code` and `name`, `costPrice`, `currency`, `vatPercent`, estimated delivery dates, `requiresDropPoint`, `isReturn` and `addOns`. Nothing is booked. The carrier is asked live, so the call can take up to 30 seconds. | `carrierId`, `packages` (1 to 20, each `weight`, `weightUnit`, optional `lengthCm`, `widthCm`, `heightCm`), `deliveryAddress` and `senderAddress` (each `countryCode`, `zip`, `city`, optional `address1`) (all required); `sendDate?`, `isReturn?` |
| `list_shipping_rates` | The shipping rates set up in Webshipper: `id`, `name`, `carrierId`, `serviceCode`, `orderChannelId`, `requireDropPoint`, `isReturn`, `isHidden`, `visibleFor`, `clickCollect`. | `orderChannelId?`, `isReturn?` |

Package dimensions are used only when all three of `lengthCm`, `widthCm` and
`heightCm` are given.

## Drop points

### find\_drop\_points

The parcel shops and lockers closest to an address, for a shipping rate or for a
carrier's service. Give **either** `shippingRateId`, **or** `carrierId` together
with `serviceCode`.

**shippingRateId** `integer`

A shipping rate that delivers to a drop point (see `list_shipping_rates`).

**carrierId** `integer`

The carrier's id (see `list_carriers`), together with `serviceCode`.

**serviceCode** `string`

The carrier's service code, e.g. `PARCELSHOP`, together with `carrierId`.

**countryCode** `string` *required*

ISO alpha-2.

**zip** `string` *required*

Postal code.

**city** `string`

City.

**address1** `string`

Street address, for the nearest results.

**dropPoints** `array`

At most 20, nearest first: `dropPointId`, `name`, address fields, `carrierCode`, `latitude`, `longitude` and `openingHours`.

**truncated** `boolean`

`true` when Webshipper found more than 20.

## Setup & returns

| Tool | Description | Key arguments |
| - | - | - |
| `list_carriers` | The carrier agreements connected to the account: `id`, `alias` (the account's name for it), `testMode`, `isApproved` and `services` (code and name). The agreement's credentials are never returned. | (none) |
| `list_order_channels` | The order channels (webshops and systems orders come from): `id`, `label`, `syncStatus`, `failedSyncCount`, `autoOrderImport`, `createShipmentAutomatically` and `fulfillAutomatically`. The shop's access credentials are never returned. | (none) |
| `search_returns` | Return orders from the return portal: `id`, `status`, `createdAt`, `orderChannelId`, `errorMessage` and `lines` (order line id, quantity and the customer's stated cause). Return slips, images and the return's access secret are never returned. | `status?` (array of `pending`, `sent`, `arrived`, `processed`, `error`, `approved`), `freeText?`, `page` |

***

## Write safety: guardrail model

The 3 write tools share one confirmation model.

1. **Every write is preview-first.** A call without `confirm: true` never changes
   anything. `create_shipment` and `update_order` read the order first, so a
   dry-run can already fail with a read error (e.g. a not-found for a wrong id) or
   with one of the order checks below. Otherwise you get a
   [preview](#preview-shape) of the exact request and nothing is written.
2. **`confirm: true` is required to apply,** with no exceptions. Re-run the
   identical call with `confirm: true`. See
   [The `confirm` argument](https://docs.consile.ai/developers/write-tools-and-guardrails#the-confirm-argument).
3. **Bookings and order updates are bound to the preview.** `create_shipment` and
   `update_order` also require `expectedState` from the preview on the confirming
   call. The binding is recomputed from a fresh read of the order; if the order
   changed in Webshipper, or the arguments differ from the previewed call, the
   write is refused and nothing is written.
4. **Only orders that can ship.** An order that is locked, dispatched, partly
   dispatched or cancelled can be neither booked nor updated. `create_shipment`
   also refuses an order on hold (release it with `update_order`, status
   `pending`, first) and books only orders with status `pending`, `error` or
   `missing_rate`. An order with no shipping rate needs `shippingRateId`.
5. **Nothing is deleted or cancelled.** There is no tool that deletes or cancels
   an order or a shipment, fetches or prints labels and documents, books a pickup,
   creates a return or changes the account's setup.
6. **Unknown outcomes are reported.** A write that gets no answer says the outcome
   is unknown; a write Webshipper accepted whose answer could not be read says so.
   Both ask you to check with a search or get tool before repeating.

| Tool | `expectedState` on the confirming call |
| - | - |
| `create_shipment` | Always |
| `update_order` | Always |
| `create_order` | Not used |

**confirm** `boolean`

Set `true` to apply the change in Webshipper. Omit (or `false`) to get a dry-run
preview. Accepted by every write tool.

**expectedState** `string`

The 16-character hex value from `preview.state.expectedState`. Treat it as
opaque. Required with `confirm: true` on `create_shipment` and `update_order`.

These are safety defaults built into the Webshipper tools. See
[Actions & guardrails](https://docs.consile.ai/en/essentials/actions-and-guardrails.md) for the policy across
connectors. An [approval rule](https://docs.consile.ai/en/portal/approvals.md) on a Webshipper write tool
applies per call, so both the preview and the confirming call need approval.

> [!WARNING]
>
> `create_shipment` buys postage from the carrier, and the shipping rate's carrier
> notifications or the shop's own fulfilment message can reach the recipient.
> Deleting a shipment in Webshipper afterwards does not reliably cancel it with
> the carrier. Account automations set up in Webshipper may also react to an order
> that is created or changed.

### Preview shape

When a write is not confirmed, the tool returns this as a normal (non-error) tool
result instead of writing to Webshipper:

```json theme={null}
{
  "preview": {
    "action": "create_shipment",
    "summary": "<human-readable summary of the change>",
    "request": { "method": "POST", "path": "<Webshipper path>", "body": { "...": "..." } },
    "current": { "...": "..." },
    "state": { "expectedState": "3f9c2a7b1e0d4c58" },
    "confirmHint": "Re-run the same call with confirm: true AND expectedState set to preview.state.expectedState. The write is refused if anything in this preview has changed by then."
  }
}
```

**preview\.request** `object`

The exact write: `method` (`POST` or `PATCH`), `path` and `body`.

**preview\.current** `object`

Only on `create_shipment` and `update_order`: the order as it is in Webshipper now (id, `visibleRef`, `status`, `lockState`, order channel, shipping rate, recipient, drop point, line and item counts and the stored delivery address).

**preview\.state** `object`

Only on the bound writes: `{ expectedState }`.

**preview\.confirmHint** `string`

How to apply the change.

***

## Write tools

### create\_shipment

Books one order with its carrier, using the order's own shipping rate or the one
given. This buys postage and can notify the recipient.

**orderId** `integer` *required*

The order to book (see `search_orders`).

**shippingRateId** `integer`

Book with this shipping rate instead of the order's own. Required when the order has none (typically `missing_rate`).

**expectedState** `string`

Required with `confirm: true`.

**confirm** `boolean`

Returns `{ booked: true, shipment }` with the shipment as `search_shipments`
shows it, including tracking numbers when the carrier has assigned them.

### update\_order

Changes one order before it ships. Give at least one of `deliveryAddress`,
`shippingRateId` and `status`.

**orderId** `integer` *required*

The order (see `search_orders`).

**deliveryAddress** `object`

The delivery address fields to change; every field left out keeps its current
value. Fields: `attContact`, `companyName`, `address1`, `address2`, `zip`,
`city`, `state`, `countryCode`, `phone`, `email`. At least one field.

**shippingRateId** `integer`

The shipping rate to use from now on (see `list_shipping_rates`).

**status** `string`

`on_hold` to hold the order back, `pending` to release it for shipping.

**expectedState** `string`

Required with `confirm: true`.

**confirm** `boolean`

Order lines, tags and the drop point cannot be changed, and a field cannot be
cleared. Returns `{ updated: true, order }`.

### create\_order

Creates a manual order in one order channel, e.g. a replacement or a B2B parcel.
The order is created with automatic shipment creation switched off, so nothing is
booked; book it with `create_shipment`.

**orderChannelId** `integer` *required*

The order channel the order belongs to (see `list_order_channels`).

**currency** `string` *required*

ISO 4217, e.g. `DKK`.

**deliveryAddress** `object` *required*

The address fields as on `update_order`, with `address1`, `zip`, `city` and
`countryCode` required, and `attContact` or `companyName` required.

**orderLines** `array` *required*

1 to 100 lines, each with `description` and `quantity` (required) and optional
`sku`, `unitPrice`, `vatPercent`, and `weight` with `weightUnit` (given
together).

**shippingRateId** `integer`

The shipping rate to ship it with.

**visibleRef** `string`

The order number people see.

**status** `string` (default: pending)

`pending` to ship it, `on_hold` to keep it back.

**confirm** `boolean`

Returns `{ created: true, order }`. A drop point, billing address or sender
address cannot be set.

***

## Errors and timeouts

Tool failures come back as a normal tool result with `isError: true` and one text
block. Webshipper's own error text is never quoted (an order's `errorMessage` is
data, returned only by the read tools).

| Situation | What the tool returns |
| - | - |
| Token rejected or deleted (401) | `Webshipper rejected the connection's credential. Reconnect Webshipper in the Consile portal, then try again.` |
| Token valid but missing a scope (403) | `Webshipper refused this request: the connected account does not have the permission or the licence it needs. Reconnecting will not fix it; the account needs that access in Webshipper.` Give the token the scope in Webshipper, or connect again with a token that has it. |
| Record not found (404) | `Webshipper could not find what was asked for. Check the id with a list tool and try again.` |
| Rate limit still hit after one automatic retry (429) | `Webshipper is limiting how fast this connection may call it. Wait a moment before trying again, and ask for less at a time.` On a write, followed by `Nothing was written.` The limit (about 2 calls per second) is per token, so it is shared by every user of the connection. |
| Webshipper refuses a value (400, 422 and other 4xx) | `Webshipper rejected the request: a value in it was not accepted.` On a write, followed by `Nothing was written.` |
| A read got no answer, or Webshipper answered 5xx | `Webshipper did not answer or is having problems. Try again in a moment.` |
| An answer that could not be read | `Webshipper returned an answer that could not be read. Ask for less at a time, or try again in a moment.` |
| Order check on a write fails (locked, already dispatched or cancelled, on hold, wrong status, no shipping rate) | A fixed message naming the reason, ending with `Nothing was booked.` or `Nothing was written.` |
| Confirm without `expectedState` on a bound write | `This write needs expectedState: run the tool WITHOUT confirm first, review the preview, then re-run the same call with confirm:true and expectedState set to preview.state.expectedState. Nothing was written.` |
| Order or arguments changed since the preview | `What would be written no longer matches the preview: the record changed in the connected system, or the arguments differ from the previewed call. Run the tool without confirm again to review the current state. Nothing was written.` |
| A write got no answer | `The request was sent to Webshipper, but no usable answer came back, so it is unknown whether the change was made. Check in Webshipper before trying again: repeating the call may make a duplicate.` |
| A write was accepted but its answer could not be read | `The change was made in Webshipper, but its answer could not be read. Do not repeat the call; read the record back to see the result.` |
| Arguments that break the input schema (wrong type, a period over 92 days, `createdFrom` after `createdTo`, a missing pair such as `carrierId` without `serviceCode`) | `The arguments were not accepted: <argument>: <rule>.` |
| Webshipper not connected yet | `webshipper is not connected yet. Connect it here: <link>` (link valid 10 minutes) |
| The user has no seat on Webshipper | A seat message; an administrator assigns access under Team. |
| Tool not enabled for the user (switched off for the organization, or excluded by the access level or custom list) | `This tool is not enabled for your user on webshipper, so it cannot be used in this session. Nothing was changed. ...` |
| Anything else | `Tool invocation failed.` |

Each request to Webshipper times out after 20 seconds, except
`quote_carrier_services`, which waits up to 30 seconds for the carrier. See
[Errors & limits](https://docs.consile.ai/developers/errors-and-limits.md) for the protocol-level errors and
rate limits shared by all connectors.

***

## Code examples

```json Request: search_orders (failed orders) theme={null}
{
  "name": "webshipper__search_orders",
  "arguments": { "status": ["error", "missing_rate"] }
}
```

```json Request: search_shipments (by order) theme={null}
{
  "name": "webshipper__search_shipments",
  "arguments": { "orderId": 48213 }
}
```

```json Request: summarize_shipping_costs theme={null}
{
  "name": "webshipper__summarize_shipping_costs",
  "arguments": { "createdFrom": "2026-10-01", "createdTo": "2026-10-31" }
}
```

```json Request: create_shipment (dry-run preview) theme={null}
{
  "name": "webshipper__create_shipment",
  "arguments": { "orderId": 48213 }
}
```

```json Request: create_shipment (apply with confirm) theme={null}
{
  "name": "webshipper__create_shipment",
  "arguments": {
    "orderId": 48213,
    "expectedState": "<preview.state.expectedState>",
    "confirm": true
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.