Easyship

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:** Unless the user specifies otherwise, default to `to_date` = today and `from_date` = 90 days prior. Required authorization scope: `public.analytics:read` Args: from_date: Start date in YYYY-MM-DD format. Default to 90 days before to_date if user doesn't specify. to_date: End date in YYYY-MM-DD format. Default to today if user doesn't specify. Returns: Couriers with shipment counts and percentage of total volume, ordered by volume.

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:** Unless the user specifies otherwise, default to `to_date` = today and `from_date` = 90 days prior. Required authorization scope: `public.analytics:read` Args: from_date: Start date in YYYY-MM-DD format. Default to 90 days before to_date if user doesn't specify. to_date: End date in YYYY-MM-DD format. Default to today if user doesn't specify. Returns: Shipping destinations with shipment counts by zone and by country, 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:** Unless the user specifies otherwise, default to `to_date` = today and `from_date` = 90 days prior. Required authorization scope: `public.analytics:read` Args: from_date: Start date in YYYY-MM-DD format. Default to 90 days before to_date if user doesn't specify. to_date: End date in YYYY-MM-DD format. Default to today if user doesn't specify. Returns: Sales channels with shipment counts and percentage of total volume.

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:** Unless the user specifies otherwise, default to `to_date` = today and `from_date` = 90 days prior. Required authorization scope: `public.analytics:read` Args: from_date: Start date in YYYY-MM-DD format. Default to 90 days before to_date if user doesn't specify. to_date: End date in YYYY-MM-DD format. Default to today if user doesn't specify. Returns: Shipment counts by status (in-progress breakdown + completed total).

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). **Use this tool for:** - "How many shipments did I create?" — total count for a period - "Show me my shipment volume trend" — daily time series - Overall shipment volume and trends over time **Do NOT use this tool for:** - Destination-specific analytics → Use `analytics_destinations_by_volume` - Shipped/label-generated counts → Use `analytics_shipped` - Shipment status breakdown → Use `analytics_shipment_status` - Courier usage breakdown → Use `analytics_couriers_by_volume` - Sales channel analytics → Use `analytics_sale_channels` **Date range:** Unless the user specifies otherwise, default to `to_date` = today and `from_date` = 90 days prior. Required authorization scope: `public.analytics:read` Args: from_date: Start date in YYYY-MM-DD format. Default to 90 days before to_date if user doesn't specify. to_date: End date in YYYY-MM-DD format. Default to today if user doesn't specify. 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. Use this for questions about past shipping activity. **USE THIS TOOL FOR:** - "Did I ship anything yesterday?", "How many shipments last week?" - "Show me shipments from last month", "Have I ever shipped anything?" - Historical shipping activity confirmation **Do NOT use for:** destination analytics, status breakdowns, or courier performance — use the specific analytics tools instead. Use `list_shipments` to find or filter individual shipments, not for date-based analytics. **Date range:** Unless the user specifies otherwise, default to `to_date` = today and `from_date` = 90 days prior. Required authorization scope: `public.analytics:read` Args: from_date: Start date in YYYY-MM-DD format. Default to 90 days before to_date if user doesn't specify. to_date: End date in YYYY-MM-DD format. Default to today if user doesn't specify. Returns: Shipped shipment data including whether the account has ever shipped and currency info.

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.

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

Schedule a courier pickup for one or more shipments. **Before calling this tool:** 1. Get the `courier_service_id` from the shipment via `get_shipment` 2. Call `get_pickup_slots` to find available dates/times — present options to user unless they want the closest available 3. All shipments must use the **same courier** and have labels that are pending or generated You must provide either `time_slot_id` (from `get_pickup_slots`) OR both `selected_from_time` and `selected_to_time`. Required authorization scope: `public.pickup:write` Args: courier_service_id: UUID of the courier service (from shipment details). 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.

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

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.

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.

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

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.

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

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.

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.

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.

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.

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.

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

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.