Spring til hovedindhold
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). Your organization needs access to Webshipper (a subscription, or a plan that covers it, see What decides access), and your user must hold a seat or plan licence (assigned under Team in the portal, see Team).
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.
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).

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:
integer
standard:"1"
Page number, 1 to 1000.
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

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

Shipments & tracking

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.
string
påkrævet
First day, YYYY-MM-DD.
string
påkrævet
Last day, included. The period may be at most 92 days.
boolean
true for return shipments only, false for outbound only; omit for both.
integer
How many shipments were read.
boolean
true when the 1,500 cap was reached. Ask for a shorter period rather than reading the totals as complete.
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

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.
integer
A shipping rate that delivers to a drop point (see list_shipping_rates).
integer
The carrier’s id (see list_carriers), together with serviceCode.
string
The carrier’s service code, e.g. PARCELSHOP, together with carrierId.
string
påkrævet
ISO alpha-2.
string
påkrævet
Postal code.
string
City.
string
Street address, for the nearest results.
array
At most 20, nearest first: dropPointId, name, address fields, carrierCode, latitude, longitude and openingHours.
boolean
true when Webshipper found more than 20.

Setup & returns


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 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.
  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.
boolean
Set true to apply the change in Webshipper. Omit (or false) to get a dry-run preview. Accepted by every write tool.
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 for the policy across connectors. An approval rule on a Webshipper write tool applies per call, so both the preview and the confirming call need approval.
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:
object
The exact write: method (POST or PATCH), path and body.
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).
object
Only on the bound writes: { expectedState }.
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.
integer
påkrævet
The order to book (see search_orders).
integer
Book with this shipping rate instead of the order’s own. Required when the order has none (typically missing_rate).
string
Required with confirm: true.
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.
integer
påkrævet
The order (see search_orders).
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.
integer
The shipping rate to use from now on (see list_shipping_rates).
string
on_hold to hold the order back, pending to release it for shipping.
string
Required with confirm: true.
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.
integer
påkrævet
The order channel the order belongs to (see list_order_channels).
string
påkrævet
ISO 4217, e.g. DKK.
object
påkrævet
The address fields as on update_order, with address1, zip, city and countryCode required, and attContact or companyName required.
array
påkrævet
1 to 100 lines, each with description and quantity (required) and optional sku, unitPrice, vatPercent, and weight with weightUnit (given together).
integer
The shipping rate to ship it with.
string
The order number people see.
string
standard:"pending"
pending to ship it, on_hold to keep it back.
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). 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 for the protocol-level errors and rate limits shared by all connectors.

Code examples