analytics_couriers_by_volume
ChatGPTRetrieves 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.
analytics_destinations_by_volume
ChatGPTRetrieves 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.
analytics_sale_channels
ChatGPTRetrieve 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.
analytics_shipment_status
ChatGPTRetrieve 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).
analytics_shipments
ChatGPTRetrieve 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.
analytics_shipped
ChatGPTRetrieves 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_pickup
ChatGPTCancel 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_shipment
ChatGPTCancel 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_label
ChatGPTCreate 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.
create_pickup
ChatGPTSchedule 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_shipment
ChatGPTCreate 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 | …
delete_shipment
ChatGPTDelete 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.
get_pickup
ChatGPTRetrieve 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_slots
ChatGPTRetrieve 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_rates
ChatGPTGet 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_shipment
ChatGPTFetch 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_documents
ChatGPTRequest 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".
list_billing_transactions
ChatGPTRetrieve 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_pickup_shipments
ChatGPTRetrieve 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_pickups
ChatGPTRetrieve 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_shipments
ChatGPTFind 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_transactions
ChatGPTRetrieve 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_shipment
ChatGPTTrack 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_shipment
ChatGPTUpdate 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_address
ChatGPTValidate 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.