Easyship - Shipping MCP

Create a new shipment and optionally buy a label in one call. Required authorization scope: `public.shipment:write` (and `public.label:write` if buying a label). **Before calling:** collect complete address details from the user — contact names, emails, phones, and company name (required for origin). **Parcel line items:** For every object in `parcels[].items[]`, provide at least one of `category` (Easyship product category slug) or `hs_code`. The Easyship API will reject the request if both are missing on any item — do not assume a default; ask the user which category applies or for the HS code. ## When to buy a label vs just create a shipment - **"Ship this" / "Buy a label" / "Create a shipping label"** → Set `buy_label: true` and `buy_label_synchronous: true` in `shipping_settings`. With `format: "url"` in `printing_options`, responses include HTTPS URLs under `shipping_documents`. - **"Create a shipment, don't buy the label yet"** → Omit `buy_label` or set it to `false`. The shipment is created in draft state; the user can buy the label later. ## Choosing a courier - **No courier specified** → Omit `courier_settings.courier_service_id`. The API selects a courier automatically (no separate rates call required). - **User names a specific courier** (e.g. "buy a label with <courier> <service>") → Use `get_rates` to resolve the matching `courier_service_id`, then pass it as `courier_settings.courier_service_id` with `allow_fallback: false`. ## Reading the label from the response When `buy_label: true` and `buy_label_synchronous: true`, the response includes a `shipping_documents` array. Entries use `category` (e.g. `label`, `packing_slip`, `commercial_invoice`) and, when `format` is `url`, an `url` field. Example: ```json "shipping_documents": [ { "category": "label", "format": "url", "url": "https://...", "page_size": "4x6" }, { "category": "packing_slip", "format": "url", "url": "https://...", "page_size": "4x6" }, { "category": "commercial_invoice", ... } ] ``` ## Identity / KYC and labels If the response includes `support_email`, `support_email_link`, or `support_reply_hint`, the payload is noting account or identity verification limits on labels; those fields carry suggested end-user wording from Easyship. ## Payload schema `shipment_data` is a JSON dict with this structure (fields marked * are required): ```json { "destination_address": { "contact_name": "string *", "contact_email": "string *", "contact_phone": "string * (nullable)", "line_1": "string * (max 35)", "city": "string *", "country_alpha2": "string * (ISO 3166-1)", "state": "string (required for AU,CA,CN,ID,MX,MY,TH,US,VN)", "postal_code": "string (required for most countries, null for HK)", "line_2": "string", "company_name": "string" }, "origin_address": { "company_name": "string * (max 27)", "contact_name": "string * (max 22)", "contact_email": "string *", "contact_phone": "string *", "line_1": "string * (max 35)", "city": "string *", "state": "string (required for AU,CA,CN,ID,MX,MY,TH,US,VN)", "postal_code": "string (required for most countries)", "country_alpha2": "string (ISO 3166-1)" }, "parcels": [ { "total_actual_weight": 1.5, "box": { "length": 30, "width": 20, "height": 15 }, "items": [ { "description": "string * (max 200)", "quantity": 1, "actual_weight": 1.5, "dimensions": { "length": 10, "width": 10, "height": 10 }, "declared_currency": "USD", "declared_customs_value": 50.0, "category": "<slug from user — required unless hs_code set>", "sku": "string", "hs_code": "<from user — required unless category set>", "contains_battery_pi966": false, "contains_battery_pi967": false, "contains_liquids": false, "origin_country_alpha2": "US" } ] } ], "incoterms": "DDU or DDP", "insurance": { "is_insured": false }, "courier_settings": { "courier_service_id": "uuid (omit to select a courier automatically)", "apply_shipping_rules": true, "allow_fallback": false }, "shipping_settings": { "buy_label": true, "buy_label_synchronous": true, "units": { "weight": "kg | g | lb | oz", "dimensions": "cm | in" }, "printing_options": { "format": "url", "label": "4x6 | A4 | A5", "commercial_invoice": "4x6 | A4", "packing_slip": "4x6 | A4 | none" } }, "order_data": { "platform_name": "string", "platform_order_number": "string", "buyer_notes": "string", "seller_notes": "string" }, "set_as_residential": true, "metadata": {} } ``` ## Weight and dimensions — three ways 1. Provide `total_actual_weight` + `box` at parcel level. 2. Provide `actual_weight` + `dimensions` per item — total weight and box auto-calculated. 3. Provide `sku` per item — weight and dimensions taken from product catalog. Args: shipment_data: The full shipment payload as a JSON dict. See schema above. At minimum: `destination_address`, `origin_address` (or `origin_address_id`), and `parcels` with at least one item. Returns: The created shipment object including selected courier, rates, and — if `buy_label` was true — `shipping_documents` array with label/packing slip/invoice URLs. If identity verification affects label purchase, the payload may include `support_email`, `support_email_link`, and `support_reply_hint`.

create_shipment

Delete a shipment that has not yet been shipped. Required authorization scope: `public.shipment:write` Args: easyship_shipment_id: The Easyship shipment ID, e.g. "ESSG10006001". Returns: Confirmation of the deleted shipment, or an error.

delete_shipment

Retrieve details of a specific pickup. Required authorization scope: `public.pickup:write` (note: the API requires write scope even for this read operation). Args: easyship_pickup_id: The Easyship pickup ID. include_contact_details: Set to true only when the user explicitly asked for the recipient's contact email or phone. Defaults to false, which omits them. Returns: Full pickup details, or an error.

get_pickup

Retrieve available pickup time slots for a courier. Call this before `create_pickup` to show the user available dates and time windows. **Typical workflow:** 1. User wants a pickup for a shipment → call `get_shipment` to get the `courier_service_id` 2. Call this tool with that `courier_service_id` to get available slots 3. Present the dates and time windows to the user (or pick the earliest if they want the closest) 4. Call `create_pickup` with the chosen `time_slot_id` or `selected_from_time`/`selected_to_time` Required authorization scope: `public.pickup:read` Args: courier_service_id: UUID of the courier service. Get this from the shipment's courier details via `get_shipment`. origin_address_id: Origin address ID to check pickup availability for. Optional — defaults to the account's primary address. Returns: Available pickup slots grouped by date, each with time windows containing `time_slot_id`, `from_time`, and `to_time`.

get_pickup_slots

Get available shipping rates (courier options with prices and delivery times) for a parcel. Returns the courier options available for a parcel between two countries, each with its price, estimated delivery time, and ranking fields the caller can sort by. **Before calling:** You must have at minimum the origin country, destination country, and weight. If any of these are missing, ask the user first. **If you use assumed or estimated data** (e.g. generic postal codes, standard dimensions), you MUST tell the user: "These are estimated rates based on standard package dimensions. Exact rates may change with a full address and precise box measurements." Each item should include either `item_category` or `item_hs_code` for accurate customs and duty estimates.

get_rates

Fetch a single shipment by Easyship ID, including parcel data and, on request, its documents. Returns the shipment's state, dates, courier, addresses, and parcel contents. Documents are **not** included by default — set `include_documents: true` when the user asked for the label, commercial invoice, or packing slip. The remaining parameters below only shape those documents and have no effect unless `include_documents` is set. Required authorization scope: `public.shipment:read` > All shipment documents are customisable. You can set: > > - Document format: URL, PDF or PNG > - Label page size: A4, A5 or 4x6 > - Commercial invoice page size: A4 or 4x6 > - Packing slip page size: A4 or 4x6 Args: easyship_shipment_id: The Easyship shipment ID, e.g. "ESSG10006001". label: Label page size: A4, A5, or 4x6. format: Document format: URL, PDF, or PNG. packing_slip: Packing slip page size: none, A4, or 4x6. commercial_invoice: Commercial invoice page size: A4 or 4x6. include_contact_details: Set to true only when the user explicitly asked for the recipient's contact email or phone. Defaults to false, which omits them. include_documents: Set to true only when the user asked for a label or document. Defaults to false, which omits the download links. Returns: Shipment details, including `shipping_documents` when `include_documents` is true.

get_shipment

Request a commercial invoice document for a shipment from the API. The MCP transport cannot return raw PDF bytes; the implementation responds with content-type and size metadata only. Downloadable HTTPS URLs for documents are available via `get_shipment` when document `format` is `url`. Required authorization scope: `public.shipment_document:read` Args: easyship_shipment_id: The Easyship shipment ID, e.g. "ESSG10006001". page_size: Page size for the document: "4x6" or "A4". Default: "A4". Returns: Metadata only (content type and size). For downloadable URLs, use `get_shipment` with format="URL".

get_shipment_documents

Retrieve a list of all billing document's transactions. Pagination of this endpoint is not indexed. `count` on the response body will always be `null`. Required authorization scope: `public.transaction_record:read` Args: billing_document_id: The billing document ID. page: Page number to fetch, minimum: 1. to_date: Filter transactions before this date in YYYY-MM-DD format. per_page: Number of records per page to fetch, minimum: 1, maximum: 100. from_date: Filter transactions since this date in YYYY-MM-DD format. Returns: A paginated list of transaction objects for the specified billing document.

list_billing_transactions

Retrieve a list of pickup's shipments. Required authorization scope: `public.shipment:read` Args: pickup_id: The pickup ID to retrieve shipments for. page: Page number to fetch, minimum: 1. per_page: Number of records per page to fetch, minimum: 1, maximum: 100. return_shipment: Search by whether the shipment is a return shipment or not. label_state: Filter by label status (e.g. "pending", "generated", "failed"). Pass values exactly as returned by the API; the set may change as the platform evolves. pickup_state: Filter by pickup status (e.g. "requested", "completed", "cancelled"). Pass values exactly as returned by the API; the set may change as the platform evolves. created_at_to: Search for shipments created before this date: ISO8601 date format. updated_at_to: Search for shipments updated before this date: ISO8601 date format. delivery_state: Filter by delivery status (e.g. "in_transit_to_customer", "delivered", "exception"). Pass values exactly as returned by the API; the set may change as the platform evolves. shipment_state: Filter by shipment lifecycle state (e.g. "created", "cancelled"). created_at_from: Search for shipments created since this date: ISO8601 date format. updated_at_from: Search for shipments updated since this date: ISO8601 date format. warehouse_state: For eFulfilment only. Filter by warehouse state (e.g. "pending", "packed", "shipped"). Pass values exactly as returned by the API. label_paid_at_to: Search for shipments where the labels were paid for before this date: ISO8601 date format. label_paid_at_from: Search for shipments where the labels were paid for since this date: ISO8601 date format. label_generated_at_to: Search for labels generated before this date: ISO8601 date format. origin_country_alpha2: Search by the shipment origin country code: Alpha-2 format (ISO 3166-1). platform_order_number: Order number on the sales platform. label_generated_at_from: Search for labels generated since this date: ISO8601 date format. destination_country_alpha2: Search by shipment destination country code: Alpha-2 format (ISO 3166-1). include_contact_details: Set to true only when the user explicitly asked for the recipient's contact email or phone. Defaults to false, which omits them. Returns: A paginated list of shipment summaries for the specified pickup.

list_pickup_shipments

Retrieve a list of pickups. Required authorization scope: `public.pickup:read` Args: page: Page number to fetch, minimum: 1. per_page: Number of records per page to fetch, minimum: 1, maximum: 100. courier: Filter by courier name (e.g. "DHL Express", "USPS"). Pass the courier name exactly as returned by the API; the available set changes as couriers are added or removed. pickup_date: Filter by pickup date in YYYY-MM-DD format. shipment_id: Filter by shipment ID. pickup_state: Filter by pickup state (e.g. "requested", "completed", "cancelled"). Pass the state string exactly as returned by the API. include_contact_details: Set to true only when the user explicitly asked for the recipient's contact email or phone. Defaults to false, which omits them. Returns: A paginated list of pickup objects matching the filter criteria.

list_pickups

Find and filter shipments, returning a summary of each one. Unless the user explicitly asks for cancelled shipments, exclude them by passing `shipment_state`. Each result carries the shipment ID, lifecycle states, dates, weight, courier, order reference, and tracking numbers, plus origin and destination country. Street addresses, parcel contents, documents, and rates are not included — call `get_shipment` with an ID for those. **USE THIS TOOL FOR:** - Finding shipments by filter (state, courier, country, date range, order number) - Listing or counting shipments that match criteria - Looking up a shipment's ID or current status before calling a detail tool **DO NOT USE THIS TOOL FOR:** - Full detail on a single shipment -> use `get_shipment` - Analytics queries -> use the analytics tools Required authorization scope: `public.shipment:read` Args: page: Page number to fetch, default: `1` per_page: Number of records per page to fetch, default: `20` label_state: Filter by label status (e.g. "pending", "generated", "failed"). Pass values exactly as returned by the API; the set may change as the platform evolves. pickup_state: Filter by pickup status (e.g. "requested", "completed", "cancelled"). Pass values exactly as returned by the API; the set may change as the platform evolves. created_at_to: Search for shipments created before this date: ISO8601 date format. updated_at_to: Search for shipments updated before this date: ISO8601 date format. delivery_state: Filter by delivery status (e.g. "in_transit_to_customer", "delivered", "exception"). Pass values exactly as returned by the API; the set may change as the platform evolves. shipment_state: Filter by shipment lifecycle state (e.g. "created", "cancelled"). created_at_from: Search for shipments created since this date: ISO8601 date format. updated_at_from: Search for shipments updated since this date: ISO8601 date format. warehouse_state: For eFulfilment only. Filter by warehouse state (e.g. "pending", "packed", "shipped"). Pass values exactly as returned by the API. label_paid_at_to: Search for shipments where the labels were paid for before this date: ISO8601 date format. label_paid_at_from: Search for shipments where the labels were paid for since this date: ISO8601 date format. easyship_shipment_id: Easyship Shipment ID provided when creating the shipment. label_generated_at_to: Search for labels generated before this date: ISO8601 date format. origin_country_alpha2: Search by the shipment origin country code: Alpha-2 format (ISO 3166-1). platform_order_number: Order number on the sales platform. label_generated_at_from: Search for labels generated since this date: ISO8601 date format. destination_country_alpha2: Search by shipment destination country code: Alpha-2 format (ISO 3166-1). return_shipment: Search by shipment whether the shipment is return shipment or not. include_contact_details: Set to true only when the user explicitly asked for the recipient's contact email or phone. Defaults to false, which omits them. Returns: A paginated list of shipment summaries matching the filter criteria.

list_shipments

Retrieve a list of all transactions within range. Pagination of this endpoint is not indexed. `count` on the response body will always be `null`. Required authorization scope: `public.transaction_record:read` Args: page: Page number to fetch, minimum: 1. transaction_type: Filter by transaction type (e.g. "shipment", "pickup", "payment"). to_date: Filter transactions before this date in YYYY-MM-DD format. per_page: Number of records per page to fetch, minimum: 1, maximum: 100. from_date: Filter transactions since this date in YYYY-MM-DD format. adjustment: Filter by adjustment transactions. days_from_now: Filter transactions from this many days ago, minimum: 1. easyship_shipment_id: Filter by Easyship shipment ID, e.g. "ESSG10006001". Must match pattern ^ES\w{2}\d{7,}$. Returns: A paginated list of transaction objects matching the filter criteria.

list_transactions

Track a shipment and get its current status plus checkpoint history. At least one of `easyship_shipment_id` or `platform_order_number` is required; omitting both returns an error from this tool. Returns the latest status, estimated delivery date, and a list of tracking checkpoints showing the shipment's journey.

track_shipment

Update an existing shipment's details. Required authorization scope: `public.shipment:write`. The `shipment_data` dict follows the same schema as `create_shipment` — include only the fields you want to change. See `create_shipment` docstring for the full payload schema. If you include **`parcels`**, each line item should still have `category` or `hs_code` — the Easyship API requires at least one per item. Args: easyship_shipment_id: Easyship Shipment ID, e.g. "ESSG10006001". shipment_data: Partial shipment payload — same schema as create_shipment, include only fields to update. Common updates: destination_address, parcels, courier_settings, shipping_settings, incoterms. Returns: The updated shipment object from the Easyship API. If identity verification affects label purchase, the payload may include `support_email`, `support_email_link`, and `support_reply_hint`.

update_shipment

Validate a shipping address and save it to the Easyship address book. Works for both US domestic and international addresses. If `country_alpha2` is "US" or omitted, uses the domestic validation endpoint. Otherwise, uses the international validation endpoint. Required authorization scope: - `public.address_validation_domestic:write` for US addresses. - `public.address_validation:write` for international addresses. > This API requires an updated contract with Easyship. Contact your account manager or Easyship Support Team. Args: line_1: Address line 1 (street address). city: City name. country_alpha2: Country code in Alpha-2 format (ISO 3166-1). Omit or use "US" for US domestic validation. state: State or province. Required for AU, CA, CN, ID, MX, MY, TH, US, VN. line_2: Address line 2 (apartment, suite, etc.). postal_code: Postal or ZIP code. company_name: Company name. replace_with_validation_result: Whether to replace the address with the validation result. Default: false. Returns: Address validation result with suggested corrections, or an error.

validate_address