Shippo

List all addresses from your Shippo account with pagination. Returns a paginated list of saved addresses. Args: - results: Number of addresses to return (default: 20) - page: Page number (1-indexed) - format: Response format ('json' or 'markdown') Returns: Paginated list of addresses with name, street, city, state, zip, and country.

Get a single address by ID. Args: - id: The address object ID - format: Response format ('json' or 'markdown') Returns: The address record with all available fields including validation results.

Create a new address in Shippo. Args: - name: Recipient name (required) - street1: Street address line 1 (required) - city: City (required) - state: State/province code (required) - zip: Postal/ZIP code (required) - country: ISO 2-letter country code (required) - company: Company name - street2: Street address line 2 - street3: Street address line 3 - phone: Phone number - email: Email address - is_residential: Whether address is residential - validate: Whether to validate the address on creation - metadata: Custom metadata string Returns: The created address record with object_id for future reference.

Validate an existing address by ID. Validates the address and returns validation results including any errors or suggestions. Args: - id: The address object ID to validate Returns: The address with validation_results containing is_valid status and any messages.

Get a batch by ID. Args: - id: The batch object ID - format: Response format ('json' or 'markdown') Returns: The batch with status, shipments, and label URLs.

Get a single customs item by ID. Args: - id: The customs item object ID - format: Response format ('json' or 'markdown') Returns: The customs item with description, quantity, value, and origin country.

Create a batch for processing multiple shipments at once. Batches allow you to create multiple shipping labels efficiently. Args: - default_carrier_account: Default carrier account ID for all shipments - default_servicelevel_token: Default service level token (e.g., 'usps_priority') - label_file_type: Label format (default: 'PDF_4x6') - batch_shipments: Array of shipment objects (see below) - metadata: Custom metadata Each batch_shipment should include: - shipment: { address_from, address_to, parcels } - carrier_account: Override default carrier (optional) - servicelevel_token: Override default service (optional) - metadata: Per-shipment metadata (optional) Returns: The created batch with status. Poll until status is VALID.

Add shipments to an existing batch. Can only add to batches with status VALIDATING or VALID. Args: - batch_id: The batch object ID (required) - shipments: Array of shipment objects to add Returns: The updated batch.

Remove shipments from an existing batch. Can only remove from batches with status VALIDATING or VALID. Args: - batch_id: The batch object ID (required) - shipment_ids: Array of batch shipment object IDs to remove Returns: The updated batch.

Purchase all labels in a batch. Purchases shipping labels for all valid shipments in the batch. Batch must have status VALID before purchasing. Args: - batch_id: The batch object ID (required) Returns: The batch with status PURCHASING. Poll until PURCHASED for label URLs.

List all carrier accounts connected to your Shippo account. Returns a paginated list of carrier accounts including Shippo's pre-configured accounts and your own connected carrier accounts. Args: - results: Number of accounts to return (default: 20) - page: Page number (1-indexed) - format: Response format ('json' or 'markdown') Returns: Paginated list of carrier accounts with carrier name, account ID, and status.

Get a single carrier account by ID. Args: - id: The carrier account object ID - format: Response format ('json' or 'markdown') Returns: The carrier account with carrier name, credentials, and status.

Connect a new carrier account to Shippo. Connects your own carrier account (e.g., your UPS or FedEx account) to Shippo to get negotiated rates. Args: - carrier: Carrier name/token (e.g., 'ups', 'fedex', 'dhl_express') - account_id: Your account ID with the carrier - parameters: Carrier-specific authentication parameters (JSON object) - active: Whether the account should be active (default: true) - metadata: Custom metadata string Returns: The created carrier account.

Update an existing carrier account. Args: - id: The carrier account object ID (required) - account_id: New account ID with the carrier - parameters: New carrier-specific parameters - active: Enable or disable the account - metadata: New custom metadata Returns: The updated carrier account.

List all customs items from your Shippo account. Customs items represent individual items in a customs declaration for international shipments. Args: - results: Number of items to return (default: 20) - page: Page number (1-indexed) - format: Response format ('json' or 'markdown') Returns: Paginated list of customs items with description, quantity, value, and origin.

Create a new customs item for international shipping. Customs items describe individual products being shipped internationally. Args: - description: Item description (required) - quantity: Number of units (required) - net_weight: Net weight per unit (required) - mass_unit: Weight unit - 'g', 'oz', 'lb', 'kg' (default: 'lb') - value_amount: Value per unit (required) - value_currency: ISO currency code (required, e.g., 'USD') - origin_country: ISO country code where item was manufactured (required) - tariff_number: HS tariff code (optional) - sku_code: SKU code (optional) - eccn_ear99: Export control classification (optional) - metadata: Custom metadata Returns: The created customs item with object_id.

List all customs declarations from your Shippo account. Customs declarations are required for international shipments. Args: - results: Number of declarations to return (default: 20) - page: Page number (1-indexed) - format: Response format ('json' or 'markdown') Returns: Paginated list of customs declarations.

Get a single customs declaration by ID. Args: - id: The customs declaration object ID - format: Response format ('json' or 'markdown') Returns: The customs declaration with all details.

Create a customs declaration for international shipping. Required for all international shipments. Must include customs items. Args: - certify: Certify the declaration is accurate (required, must be true) - certify_signer: Name of person certifying (required) - contents_type: Type of contents (required) Options: DOCUMENTS, GIFT, SAMPLE, MERCHANDISE, HUMANITARIAN_DONATION, RETURN_MERCHANDISE, OTHER - non_delivery_option: What to do if undeliverable (required) Options: ABANDON, RETURN - items: Array of customs item objects OR existing item IDs (required) - contents_explanation: Explanation if contents_type is OTHER - exporter_reference: Exporter reference number - importer_reference: Importer reference number - invoice: Invoice number - commercial_invoice: Whether this is a commercial shipment - license: Export license number - certificate: Certificate number - notes: Additional notes - eel_pfc: EEL/PFC code for US exports - aes_itn: AES ITN for US exports - incoterm: Incoterm for duties/taxes Options: DDP, DDU, CPT, CIP, DAP, DAT, EXW, FCA, FAS, FOB, CFR, CIF - b13a_filing_option: B13A filing option for Canada - b13a_number: B13A number - metadata: Custom metadata Returns: The created customs declaration with object_id.

Get live shipping rates for checkout. Returns real-time shipping rates based on service groups you've configured. Use this to show shipping options to customers at checkout. Args: - address_from: Sender address object OR address ID (required) - address_to: Recipient address object OR address ID (required) - line_items: Array of line items being shipped (required) - parcel: Parcel dimensions object OR parcel ID (optional - uses default template if not provided) Each line_item should include: - title: Product title (required) - quantity: Quantity (required) - weight: Item weight (optional) - weight_unit: Weight unit (optional) Returns: Array of available rates with carrier, service, price, and estimated days.

Get the default parcel template for live rates. The default template is used when no parcel is specified in live rate requests. Args: - format: Response format ('json' or 'markdown') Returns: The default parcel template, or null if not set.

Set the default parcel template for live rates. Args: - object_id: User parcel template object ID to use as default (required) Returns: The updated default parcel template.

Clear the default parcel template for live rates. After clearing, live rate requests will require a parcel to be specified. Returns: Confirmation of deletion.

Get a single rate by ID. Args: - id: The rate object ID - format: Response format ('json' or 'markdown') Returns: The rate record with carrier, service level, price, and estimated delivery.

List all manifests (end-of-day forms) from your Shippo account. Manifests are used to close out shipments with carriers at the end of the day. Args: - results: Number of manifests to return (default: 20) - page: Page number (1-indexed) - format: Response format ('json' or 'markdown') Returns: Paginated list of manifests with status and transaction counts.

Get a single manifest by ID. Args: - id: The manifest object ID - format: Response format ('json' or 'markdown') Returns: The manifest with status, transactions, and document URLs.

Create a manifest (end-of-day form) for a carrier. Manifests close out all shipments for a carrier on a given date. Required by some carriers before pickup. Args: - carrier_account: Carrier account object ID (required) - shipment_date: Date for the manifest (ISO 8601, required) - address_from: Origin address object ID (required) - transactions: Array of transaction object IDs to include (required) - async: If true, manifest is created asynchronously Returns: The created manifest with status and document URLs.

List all orders from your Shippo account. Orders represent e-commerce orders that need to be shipped. Args: - results: Number of orders to return (default: 20) - page: Page number (1-indexed) - format: Response format ('json' or 'markdown') Returns: Paginated list of orders with order number, status, and line items.

Get a single order by ID. Args: - id: The order object ID - format: Response format ('json' or 'markdown') Returns: The order with addresses, line items, and fulfillment status.

Create a new order in Shippo. Orders represent e-commerce orders that need fulfillment. Args: - to_address: Recipient address object OR address ID (required) - from_address: Sender address object OR address ID (optional) - line_items: Array of line items (required) - placed_at: Order placement date/time (ISO 8601, required) - order_number: Your order number (optional) - order_status: Order status (optional) Options: UNKNOWN, AWAITPAY, PAID, REFUNDED, CANCELLED, PARTIALLY_FULFILLED, SHIPPED - shipping_cost: Shipping cost charged to customer - shipping_cost_currency: Currency for shipping cost - shipping_method: Shipping method name - subtotal_price: Order subtotal - total_price: Order total - total_tax: Total tax amount - currency: Default currency for prices - weight: Total order weight - weight_unit: Weight unit - notes: Order notes Each line_item should include: - title: Product title (required) - quantity: Quantity (required) - variant_title: Variant (optional) - sku: SKU code (optional) - total_price: Line total (optional) - currency: Currency (optional) - weight: Item weight (optional) - weight_unit: Weight unit (optional) - manufacture_country: Country of origin (optional) Returns: The created order with object_id.

List carrier-provided parcel templates. Carrier templates are predefined box sizes (e.g., USPS Flat Rate boxes). Using templates can simplify parcel creation. Args: - carrier: Filter by carrier (e.g., 'usps', 'ups', 'fedex') - include: Include specific carriers (comma-separated) - results: Number of templates to return (default: 20) - page: Page number - format: Response format ('json' or 'markdown') Returns: Paginated list of carrier parcel templates.

Get a single carrier parcel template by token. Args: - token: The template token (e.g., 'USPS_FlatRatePaddedEnvelope') - format: Response format ('json' or 'markdown') Returns: The template with dimensions and carrier information.

List your custom parcel templates. User templates are your own saved parcel dimensions for quick reuse. Args: - results: Number of templates to return (default: 20) - page: Page number - format: Response format ('json' or 'markdown') Returns: Paginated list of your parcel templates.

Get a single user parcel template by ID. Args: - id: The user parcel template object ID - format: Response format ('json' or 'markdown') Returns: The template with name and dimensions.

Create a custom parcel template. Save frequently used parcel dimensions for quick reuse. Args: - name: Template name (required) - length: Length (required) - width: Width (required) - height: Height (required) - distance_unit: Unit - 'cm', 'in', 'ft', 'mm', 'm', 'yd' (default: 'in') - weight: Default weight (optional) - weight_unit: Weight unit - 'g', 'oz', 'lb', 'kg' (optional) - template: Base template token to reference (optional) Returns: The created user parcel template.

Delete a user parcel template. Args: - id: User parcel template object ID (required) Returns: Confirmation of deletion.

List all parcels from your Shippo account with pagination. Returns a paginated list of saved parcels. Args: - results: Number of parcels to return (default: 20) - page: Page number (1-indexed) - format: Response format ('json' or 'markdown') Returns: Paginated list of parcels with dimensions and weight.

Get a single parcel by ID. Args: - id: The parcel object ID - format: Response format ('json' or 'markdown') Returns: The parcel record with dimensions and weight.

Create a new parcel in Shippo. Args: - length: Parcel length (required) - width: Parcel width (required) - height: Parcel height (required) - distance_unit: Unit for dimensions - 'cm', 'in', 'ft', 'mm', 'm', 'yd' (default: 'in') - weight: Parcel weight (required) - mass_unit: Unit for weight - 'g', 'oz', 'lb', 'kg' (default: 'lb') - template: Carrier parcel template token (optional) - metadata: Custom metadata string Returns: The created parcel record with object_id for future reference.

Schedule a pickup with a carrier. Schedules a carrier pickup for one or more shipments. Args: - carrier_account: Carrier account object ID (required) - transactions: Array of transaction (label) IDs to pick up (required) - requested_start_time: Earliest pickup time (ISO 8601, required) - requested_end_time: Latest pickup time (ISO 8601, required) - location: Pickup location details (required) - building_location_type: Where to find packages (required) Options: Front Door, Back Door, Side Door, Knock on Door, Ring Bell, Mail Room, Office, Reception, In/At Mailbox, Security Deck, Shipping/Receiving, Other - address: Pickup address object OR address ID (required) - building_type: Type of building (optional) - instructions: Special instructions (optional) - is_test: Whether this is a test pickup - metadata: Custom metadata Returns: The created pickup with confirmation code and scheduled times.

List all rates for a shipment. Gets available shipping rates for an existing shipment. Optionally filter by currency. Args: - shipment_id: The shipment object ID (required) - currency: ISO currency code to filter rates (e.g., 'USD') - format: Response format ('json' or 'markdown') Returns: Paginated list of rates with carrier, service, price, and estimated days.

Request a refund for an unused shipping label. Creates a refund request for a transaction (label purchase). Not all carriers support refunds; check carrier policies. Args: - transaction: The transaction object ID to refund (required) - async: If true, refund is processed asynchronously (default: false) Returns: The refund object with status (QUEUED, PENDING, SUCCESS, or ERROR).

Get the status of a refund request. Args: - id: The refund object ID - format: Response format ('json' or 'markdown') Returns: The refund object with current status.

List all service groups for live rates. Service groups define which carrier services to offer at checkout. Args: - format: Response format ('json' or 'markdown') Returns: Array of service groups with name, type, and service levels.

Create a new service group for live rates. Service groups control which shipping options appear at checkout. Args: - name: Service group name (required) - description: Description (optional) - type: Group type (required) - LIVE_RATE: Show actual carrier rates - FLAT_RATE: Charge a flat rate - FREE_SHIPPING: Free shipping above threshold - service_levels: Array of service levels to include (required) - flat_rate: Flat rate amount (for FLAT_RATE type) - flat_rate_currency: Currency for flat rate - free_shipping_threshold_min: Minimum order for free shipping (for FREE_SHIPPING type) - free_shipping_threshold_currency: Currency for threshold - rate_adjustment: Percentage adjustment to rates (-100 to 100) - is_active: Whether group is active (default: true) Each service_level should include: - account_object_id: Carrier account ID - servicelevel_token: Service level token Returns: The created service group.

Update an existing service group. Args: - name: New name (optional) - description: New description (optional) - type: New type (optional) - service_levels: New service levels (optional) - flat_rate: New flat rate (optional) - flat_rate_currency: New currency (optional) - free_shipping_threshold_min: New threshold (optional) - free_shipping_threshold_currency: New threshold currency (optional) - rate_adjustment: New rate adjustment (optional) - is_active: New active status (optional) Returns: The updated service group.

Delete a service group. Args: - id: Service group object ID (required) Returns: Confirmation of deletion.

List all shipments from your Shippo account with pagination. Returns a paginated list of shipments with addresses and rates. Args: - results: Number of shipments to return (default: 20) - page: Page number (1-indexed) - format: Response format ('json' or 'markdown') Returns: Paginated list of shipments with status, addresses, and available rates.

Get a single shipment by ID. Args: - id: The shipment object ID - format: Response format ('json' or 'markdown') Returns: The shipment record with addresses, parcels, and available rates.

Create a new shipment in Shippo to get shipping rates. A shipment represents a package being sent from one address to another. Creating a shipment will automatically fetch available rates from carriers. Args: - address_from: Sender address object OR existing address ID - address_to: Recipient address object OR existing address ID - parcels: Array of parcel objects OR existing parcel IDs - address_return: Return address object OR ID (optional) - shipment_date: Date shipment will be tendered to carrier (optional) - customs_declaration: Customs declaration ID for international (optional) - carrier_accounts: Array of carrier account IDs to get rates from (optional) - extra: Extra shipment options (signature, insurance, etc.) - metadata: Custom metadata string - async: If true, rates are fetched asynchronously (default: false) Returns: The created shipment with available rates from carriers.

Get the tracking status of a shipment. Retrieves the current tracking status and history for a shipment using the carrier name and tracking number. Args: - carrier: Carrier name/token (e.g., 'usps', 'ups', 'fedex') - tracking_number: The tracking number - format: Response format ('json' or 'markdown') Returns: Tracking status including current status, location, ETA, and tracking history.

Register a webhook to receive tracking updates for a shipment. Sets up tracking notifications for a shipment. Shippo will send webhook events as the shipment status changes. Note: You must have webhooks configured in your Shippo dashboard. Args: - carrier: Carrier name/token (e.g., 'usps', 'ups', 'fedex') - tracking_number: The tracking number to track - metadata: Custom metadata string (optional) Returns: Initial tracking status for the registered shipment.

List all transactions (label purchases) from your Shippo account. Returns a paginated list of label transactions. Args: - results: Number of transactions to return (default: 20) - page: Page number (1-indexed) - format: Response format ('json' or 'markdown') Returns: Paginated list of transactions with status, tracking number, and label URL.

Get a single transaction (label) by ID. Args: - id: The transaction object ID - format: Response format ('json' or 'markdown') Returns: The transaction record with status, tracking number, and label URL.

Create a transaction to purchase a shipping label. Purchases a shipping label based on a rate from a shipment. Args: - rate: The rate object ID to purchase (required) - label_file_type: Label format (default: 'PDF_4x6') Options: PNG, PNG_2.3x7.5, PDF, PDF_2.3x7.5, PDF_4x6, PDF_4x8, PDF_A4, PDF_A5, PDF_A6, ZPLII - metadata: Custom metadata string - async: If true, label is created asynchronously (default: false) Returns: The transaction with tracking number and label URL.

Create an instant transaction (one-call label purchase). Creates a shipment and purchases a label in a single API call. Use this when you already know which carrier and service level you want. Args: - address_from: Sender address object OR address ID - address_to: Recipient address object OR address ID - parcels: Array of parcel objects OR parcel IDs - carrier_account: Carrier account object ID (required) - servicelevel_token: Service level token (e.g., 'usps_priority') (required) - label_file_type: Label format (default: 'PDF_4x6') - metadata: Custom metadata string Returns: The transaction with tracking number and label URL.