Easyship

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. **Required inputs:** origin country, destination country, weight, and box dimensions. **Accuracy:** Rates are only as accurate as the weight and dimensions supplied. They are estimates when based on generic postal codes or standard box dimensions. Exact rates can 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.

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.

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). **Required address details:** contact names, emails, and phones for both addresses, plus company name for the origin. **Saved addresses:** the origin, sender and return addresses can each be given as a full object (`origin_address`, `sender_address`, `return_address`) or as the UUID of an address saved in the user's Easyship account (`origin_address_id`, `sender_address_id`, `return_address_id`). When both forms of the same address are sent, the ID takes precedence and the object is not used. Saved-address IDs come from the user or an earlier tool result and cannot be derived from address details. The origin is required (object or ID). Sender (the address shown on the label, where the courier allows it to differ from the origin) and return are optional; when not set, the origin address is used. The destination is always a full `destination_address` object. The same rules apply to `update_shipment`. **Parcel line items:** Every object in `parcels[].items[]` needs at least one of `category` (Easyship product category slug) or `hs_code`. The Easyship API rejects the request if both are missing on any item. `category` / `hs_code` describe the actual goods; the API does not infer them. ## Buying a label vs creating a draft - **Label purchase:** `buy_label: true` and `buy_label_synchronous: true` in `shipping_settings` buy the label in the same call. With `format: "url"` in `printing_options`, the response includes HTTPS URLs under `shipping_documents`. This charges the account. - **Draft only:** with `buy_label` omitted or `false`, the shipment is created in draft state and the label can be bought later. ## Courier selection - **Automatic:** with `courier_settings.courier_service_id` omitted, the API selects a courier. - **Specific courier:** a `courier_service_id` (as returned by `get_rates`) in `courie

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. To change the origin, sender or return address, send either the full address object or the saved-address ID; the rules are the same as in the "Saved addresses" section of `create_shipment`. 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`.

Find and filter shipments, returning a summary of each one. Cancelled shipments are excluded by default (`shipment_state="created"`); `"cancelled"` returns only cancelled ones and `"all"` returns both. 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 in this summary; they are part of the single-shipment detail (`get_shipment`). Covers finding shipments by filter (state, courier, country, date range, order number), listing or counting matching shipments, and looking up a shipment's ID or current status. Aggregate counts over time are available from the analytics endpoints. 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: "created" (default, excludes cancelled), "cancelled", or "all". 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. Filte

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.

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.

Cancel a shipment that has been shipped. Required authorization scope: `public.shipment:write` > You can cancel your shipment after it has been shipped only if its label failed to be generated or if the label is already generated, but the shipment is not yet in transit. Args: easyship_shipment_id: The Easyship shipment ID, e.g. "ESSG10006001". Returns: Confirmation of the cancelled shipment, or an error.

Create a label for an existing shipment and retrieve it synchronously. Buys a label for a shipment that already exists. This is a dedicated endpoint that finalizes the shipment, books it with the courier, and returns the label and shipping documents in one synchronous call. `update_shipment` with `buy_label` performs the same purchase as part of a wider update. Required authorization scope: `public.label:write` **Typical use:** Buying or regenerating a label for an existing shipment ID where `label_state` is `not_created` or similar. Successful responses include `shipping_documents` with `category` values such as `label`, `packing_slip`, and `commercial_invoice`; with `format` `url`, entries include `url` fields. If the response includes `support_reply_hint`, `support_email`, or `support_email_link`, the API is noting verification limits on labels—those fields contain Easyship-provided support guidance. Args: easyship_shipment_id: The Easyship shipment ID, e.g. "ESUS323672208". courier_service_id: UUID of the courier service to use. Omit to keep the shipment's current courier or let Easyship select a courier automatically. format: Document format. One of: "url", "pdf", "png", "zpl". Default "url" (returns clickable links). label: Label page size. One of: "4x6", "A4", "A5". Default "4x6". commercial_invoice: Commercial invoice page size. One of: "4x6", "A4". Default "A4". packing_slip: Packing slip page size. One of: "4x6", "A4", "none". Default "4x6". remarks: Custom commercial invoice remarks (max 70 chars). Overrides company-level remarks. Returns: The full shipment object with `shipping_documents` containing label/invoice/packing slip URLs. If identity verification affects label purchase, the payload may include `support_email`, `support_email_link`, and `support_reply_hint`.

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".

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.

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.

Cancel a pickup. Required authorization scope: `public.pickup:write` Args: easyship_pickup_id: The Easyship pickup ID. Returns: Confirmation of the cancelled pickup, or an error.

Retrieve available pickup time slots for a courier. Returns the dates and time windows a courier can collect from the origin address. Each window's `time_slot_id` is accepted by `create_pickup`. Required authorization scope: `public.pickup:read` Args: courier_service_id: UUID of the shipment's courier service (`courier_service.id` on the 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`.

Schedule a courier pickup for one or more shipments. **Requirements:** - All shipments use the **same courier** and have labels that are pending or generated. - `courier_service_id` is that courier's `courier_service.id` on the shipments. - Either `time_slot_id` (from `get_pickup_slots`) or both `selected_from_time` and `selected_to_time`. Books a real courier collection. Required authorization scope: `public.pickup:write` Args: courier_service_id: UUID of the shipments' courier service (`courier_service.id` on the shipment). selected_date: Pickup date in YYYY-MM-DD format. easyship_shipment_ids: List of Easyship shipment IDs to include, e.g. ["ESSG10006001", "ESSG10006002"]. All must use the same courier. time_slot_id: UUID of a time slot from `get_pickup_slots`. Provide this OR `selected_from_time`/`selected_to_time`. selected_from_time: Pickup window start time (e.g. "09:00"). Required if `time_slot_id` is not provided. selected_to_time: Pickup window end time (e.g. "17:00"). Required if `time_slot_id` is not provided. Returns: The created pickup object with confirmation details, or an error.

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_

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.

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.

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.

Retrieves the account's shipping destinations ordered by shipment volume. Use for any question about where shipments are going or which destination countries are most common. Returns `total_shipments_count`, `shipments_count_by_zone` (zone name + count), and `shipments_count_by_country` (country name, alpha2 code, count, percentage). **Date range:** Both dates are required; a common window is the 90 days ending today. Required authorization scope: `public.analytics:read` Args: from_date: Start date in YYYY-MM-DD format. to_date: End date in YYYY-MM-DD format. Returns: Shipping destinations with shipment counts by zone and by country, ordered by volume.

Retrieve shipment volume overview: total shipment count and daily shipment counts over time. Returns `total_shipments_count` and `shipments_count_by_date` (a time series with daily totals and a `max` peak value). Covers total shipment counts for a period and daily volume trends. It does not break volume down by destination, status, courier, or sales channel. **Date range:** Both dates are required; a common window is the 90 days ending today. Required authorization scope: `public.analytics:read` Args: from_date: Start date in YYYY-MM-DD format. to_date: End date in YYYY-MM-DD format. Returns: Total shipment count and daily shipment count time series for the date range.

Retrieves data for shipments that have already been shipped (labels generated) within a date range. Returns `has_ever_shipped` (boolean) and `currency` info: whether the account has shipped anything (e.g. "Have I ever shipped anything?", "Did I ship anything last month?"). It does not return counts or individual shipments. **Date range:** Both dates are required; a common window is the 90 days ending today. Required authorization scope: `public.analytics:read` Args: from_date: Start date in YYYY-MM-DD format. to_date: End date in YYYY-MM-DD format. Returns: Shipped shipment data including whether the account has ever shipped and currency info.

Retrieve shipment status distribution: how many shipments are in each status. Returns `in_progress_shipments_count`, `completed_shipments_count`, and `in_progress_shipments` array (each with `status` and `count`). Possible statuses: Label Pending, Label Rejected, Label Ready, Pickup/Drop-off in Progress, In Transit to Customer, Failed Delivery Attempt, Exception. **Date range:** Both dates are required; a common window is the 90 days ending today. Required authorization scope: `public.analytics:read` Args: from_date: Start date in YYYY-MM-DD format. to_date: End date in YYYY-MM-DD format. Returns: Shipment counts by status (in-progress breakdown + completed total).

Retrieves the couriers the account has shipped with, ordered by shipment volume. Returns `total_shipments_count` and `couriers` array (each with `name`, `shipments_count`, `percentage`). Use for: "Which courier do I use most?", "Show courier breakdown", courier usage analysis. **Date range:** Both dates are required; a common window is the 90 days ending today. Required authorization scope: `public.analytics:read` Args: from_date: Start date in YYYY-MM-DD format. to_date: End date in YYYY-MM-DD format. Returns: Couriers with shipment counts and percentage of total volume, ordered by volume.

Retrieve shipment volume by sales channel (e.g. Shopify, WooCommerce, API, manual). Returns `total_shipments_count` and `channels` array (each with `name`, `shipments_count`, `percentage`). Use for: "Which sales channel has the most shipments?", "Show me channel breakdown." **Date range:** Both dates are required; a common window is the 90 days ending today. Required authorization scope: `public.analytics:read` Args: from_date: Start date in YYYY-MM-DD format. to_date: End date in YYYY-MM-DD format. Returns: Sales channels with shipment counts and percentage of total volume.