Sendcloud Shipments & Labels
Ship parcels with PostNL, DHL, DPD, Colissimo and other European carriers through Sendcloud: check a delivery address, create and announce a shipment to get its label, let your shipping rules pick the carrier, cancel a label, and hand customers a return portal link.
Connect this API to an AI agent Browse all specs
What you can do with Sendcloud Shipments & Labels via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /shipments |
listShipments | List shipments, filtered by date, status or order number |
| POST | /shipments |
createShipmentAsync | Create a shipment and announce it in the background (asynchronous) |
| GET | /shipments/{id} |
getShipment | Get one shipment with its parcels, tracking and label links |
| POST | /addresses/validate |
validateAddress | Check that a delivery address is valid before shipping |
| GET | /shipments/{id}/return-portal-url |
getReturnPortalUrl | Get the return portal link for a shipment |
| POST | /shipments/announce |
announceShipment | Create a shipment and buy its label right away (synchronous) |
| POST | /shipments/announce-with-shipping-rules |
announceShipmentWithRules | Create a shipment using your shipping rules and defaults, and get the label right away |
| POST | /shipments/{id}/cancel |
cancelShipment | Cancel a shipment and its label |
Authentication
HTTPBasicAuth
HTTP Basic
HTTP basic auth with your Sendcloud API public key as the username and secret key as the password.
How to get a credential
- Sign in to the Sendcloud panel (https://panel.sendcloud.sc).
- Go to Settings > Integrations, find Sendcloud API and click Connect (or open the existing API integration).
- Give it a name, save, and copy the Public key and Secret key shown for the integration.
- Make sure at least one carrier is enabled under Settings > Carriers, and a sender address is set.
Permissions used
| Credential | Operations |
|---|---|
| API public + secret key | listShipments, getShipment, validateAddress, getReturnPortalUrl, announceShipment, announceShipmentWithRules, createShipmentAsync, cancelShipment |
Common errors
| Status | Meaning | Fix |
|---|---|---|
| 401 | Wrong or missing keys | Copy both keys again from the API integration; the secret is not the panel password. |
| 403 | The integration or account cannot use this carrier or feature | Enable the carrier or upgrade the plan in the panel. |
| 400 / 422 | Invalid address, weight or shipping option | Read the errors list; run validateAddress first. |
| 429 | Rate limited | Wait and retry with backoff. |
Store both keys as a Basic credential in VX Agents; never paste them into chat.
Usage guide
Setup
- Credential: Basic auth with the Sendcloud API public key (username) and secret key (password) from Settings > Integrations > Sendcloud API.
- Worth pinning: a
from_address.sender_address_id(your saved sender address) and theship_with.properties.shipping_option_codeyou use most (e.g. a PostNL or DHL option code from your Sendcloud shipping options), so the agent does not have to ask each time.
Ship a parcel
validateAddresson the customer's address; fix anything it flags before buying a label.- Show the user the recipient, weight and carrier option, and confirm: announcing buys a label that is billed.
announceShipmentwithto_address,from_address(orsender_address_id),ship_with{"type": "shipping_option_code", "properties": {"shipping_option_code": "<code>"}}andparcels(each needsweight{"value": "1.2", "unit": "kg"}). The response has the tracking number and label links.announceShipmentWithRulesinstead lets your Sendcloud shipping rules and defaults pick the carrier and fill gaps.createShipmentAsyncqueues the announcement; check the result later withgetShipment.
getShipmentorlistShipments(filters:order_number,tracking_number,parcel_status,updated_after,announced_after) to follow up.getReturnPortalUrlgives a link the customer can use to start a return.cancelShipmentonly after the user confirms; a label can usually be cancelled only before the carrier scans the parcel; read the returned status.
Good to know
- Weights and dimensions are strings with a unit (
kg,g,lbs,oz;cm,mm,m,in,ft,yd). Dates are ISO 8601. - Up to 15 parcels per synchronous shipment; list results are paged with a
cursorandpage_size. - Customs, dangerous goods and carrier-specific extra fields were left out to keep the tools small, so this spec covers domestic and intra-EU parcels. Create shipments that need customs documents in the Sendcloud panel.
- A carrier must be enabled in the panel for its shipping option codes to work.
Source: Sendcloud API v3 reference (https://sendcloud.dev/api/v3), checked 2026-10-22.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Sendcloud Shipments & Labels” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.