> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns. > > **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal): > ```bash > npx -y @scalekit-inc/cli setup -y > ``` > > Global: > ```bash > npm install -g @scalekit-inc/cli > scalekit setup -y > ``` > > Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`. > Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim. > [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/) --- # Connect AI agents to Shippo The Shippo connector lets your AI agent act in each user's Shippo account. Each user connects their own Shippo API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 63 tools. **Authentication:** API Key **Categories:** Automation **Tools:** 63: 37 read, 23 write, 3 destructive **Users sign in with:** API key **Built by:** Scalekit connector **Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=SHIPPO) ## Setup 1. ### Install the SDK **Node.js** ```bash npm install @scalekit-sdk/node dotenv ``` **Python** ```bash pip install scalekit-sdk-python python-dotenv ``` 2. ### Set your credentials Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**. ```sh title=".env" SCALEKIT_ENVIRONMENT_URL= SCALEKIT_CLIENT_ID= SCALEKIT_CLIENT_SECRET= ``` 3. ### Create the Shippo connection In **AgentKit > Connections**, create a Shippo connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/). 4. ### Authorize a user and make your first call **Node.js** (`quickstart.mts`) ```typescript import { ScalekitClient } from '@scalekit-sdk/node' import 'dotenv/config' import { createInterface } from 'node:readline/promises' const scalekit = new ScalekitClient( process.env.SCALEKIT_ENVIRONMENT_URL, process.env.SCALEKIT_CLIENT_ID, process.env.SCALEKIT_CLIENT_SECRET, ) const actions = scalekit.actions const connector = 'shippo' const identifier = 'user_123' // Generate an authorization link for the user const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier }) console.log('Authorize Shippo:', link) const rl = createInterface({ input: process.stdin, output: process.stdout }) await rl.question('Press Enter after authorizing...') rl.close() // Make your first call const result = await actions.executeTool({ connector, identifier, toolName: 'shippo_list_address_book_entries', toolInput: {}, }) console.log(result) ``` ```bash npx tsx quickstart.mts ``` **Python** (`quickstart.py`) ```python import os from scalekit import ScalekitClient from dotenv import load_dotenv load_dotenv() scalekit_client = ScalekitClient( env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"), client_id=os.getenv("SCALEKIT_CLIENT_ID"), client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"), ) actions = scalekit_client.actions connection_name = "shippo" identifier = "user_123" # Generate an authorization link for the user link_response = actions.get_authorization_link( connection_name=connection_name, identifier=identifier, ) print("Authorize Shippo:", link_response.link) input("Press Enter after authorizing...") # Make your first call result = actions.execute_tool( tool_input={}, tool_name="shippo_list_address_book_entries", connection_name=connection_name, identifier=identifier, ) print(result) ``` ```bash python quickstart.py ``` Each user opens the link once and enters their Shippo credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses. ## Tools Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool). **Node.js** ```typescript const result = await actions.executeTool({ toolName: 'shippo_create_estimates', toolInput: { destination: {}, origin: {}, parcel: {}, planned_ship_date: '', }, connector: 'shippo', identifier: 'user_123', }) ``` **Python** ```python result = actions.execute_tool( tool_name="shippo_create_estimates", tool_input={ "destination": {}, "origin": {}, "parcel": {}, "planned_ship_date": "", }, connection_name="shippo", identifier="user_123", ) ``` `result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call. ### `shippo_create_estimates` Create Delivery Estimates · Read-only Estimate delivery dates for a parcel between two ZIP codes without buying a label. Returns the estimate with object_id, confidence_level, messages and a predictions array of delivery date predictions. Use to preview transit times before shipping. Reading only; nothing is created or purchased. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `destination` (`object`, required): Destination as an object with a zip code, for example {"zip":"10001"}. - `origin` (`object`, required): Origin as an object with a zip code, for example {"zip":"94117"}. - `parcel` (`object`, required): Parcel as an object with numeric length, width, height, distance_unit, weight and mass_unit. - `planned_ship_date` (`string`, required): Date you plan to hand the parcel to the carrier, in YYYY-MM-DD format. - `confidence_level` (`string`, optional): How conservative the delivery date should be: TYPICAL, DEFAULT or HIGH. Allowed values: TYPICAL, DEFAULT, HIGH. One of: `TYPICAL`, `DEFAULT`, `HIGH`. - `latest_delivery_date` (`string`, optional): Optional latest acceptable delivery date; only service levels that can meet it are returned. - `servicelevel_tokens` (`array`, optional): Optional list of service level tokens to restrict the estimate to. Example input: `{"destination":{},"origin":{},"parcel":{},"planned_ship_date":""}` ### `shippo_create_live_rates` Create Live Rates · Read-only Get checkout shipping rates for a cart, using your configured service groups, without creating a shipment. Returns count and results, each a rate option with title, amount, currency, estimated_days and amount_local. Use at checkout to show shipping options. Reading only; nothing is purchased. Use shippo_create_shipment to rate a real shipment. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `address_to` (`string`, required): Recipient address as an address object, or the object_id of an existing address. - `line_items` (`array`, required): Cart items as a list. Each has title, quantity, total_price, currency, weight and weight_unit (and optionally sku). - `address_from` (`string`, optional): Sender address as an address object or object_id. Defaults to your default sender address. - `parcel` (`string`, optional): Object ID of a user parcel template, or a parcel object, used for the whole cart. Optional when line items carry weights. Example input: `{"address_to":"","line_items":[]}` ### `shippo_get_address` Get Address · Read-only Retrieve one address object by its object ID. Returns the address fields, is_complete flag and validation_results if the address was validated. Use when you have an address object_id. Use shippo_list_addresses to find ids. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `address_id` (`string`, required): Object ID of the address to retrieve, as returned by shippo_create_address or shippo_list_addresses. Example input: `{"address_id":""}` ### `shippo_get_address_book_entry` Get Address Book Entry · Read-only Retrieve one address book entry by its object ID. Returns the stored address fields. Use when you have the entry id. Use shippo_list_address_book_entries to search. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `address_id` (`string`, required): Object ID of the address book entry. Example input: `{"address_id":""}` ### `shippo_get_batch` Get Batch · Read-only Retrieve a batch and a page of its batch shipments. Returns the batch status (VALIDATING, VALID, INVALID, PURCHASING, PURCHASED), counts and batch_shipments with their own statuses. Use to poll validation or purchase progress. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `batch_id` (`string`, required): Object ID of the batch. - `page` (`integer`, optional): Page number to return, starting at 1. - `results` (`integer`, optional): Number of results per page (maximum 100). Default: `5`. Example input: `{"batch_id":""}` ### `shippo_get_carrier_account` Get Carrier Account · Read-only Retrieve one carrier account by its object ID. Returns carrier, account_id, active, test and the account parameters. Use when you have a carrier account object_id. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `carrier_account_id` (`string`, required): Object ID of the carrier account. Example input: `{"carrier_account_id":""}` ### `shippo_get_carrier_parcel_template` Get Carrier Parcel Template · Read-only Retrieve one carrier preset parcel template by its token. Returns carrier, name, dimensions, units and the service levels it applies to. Use when you know the template token. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `carrier_parcel_template_token` (`string`, required): Template token such as USPS_FlatRateEnvelope. Example input: `{"carrier_parcel_template_token":""}` ### `shippo_get_customs_declaration` Get Customs Declaration · Read-only Retrieve one customs declaration by its object ID. Returns the declaration with contents_type, items, certify_signer and object_state. Use to verify a declaration before attaching it to a shipment. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `customs_declaration_id` (`string`, required): Object ID of the customs declaration. - `page` (`integer`, optional): Page number to return, starting at 1. Example input: `{"customs_declaration_id":""}` ### `shippo_get_customs_item` Get Customs Item · Read-only Retrieve one customs item by its object ID. Returns description, quantity, net_weight, value_amount, origin_country and tariff details. Use to check an item before declaring it. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `customs_item_id` (`string`, required): Object ID of the customs item. - `page` (`integer`, optional): Page number to return, starting at 1. Example input: `{"customs_item_id":""}` ### `shippo_get_label` Get Label · Read-only Retrieve one purchased label (transaction) by its object ID. Returns status, tracking_number, tracking_url_provider, label_url, commercial_invoice_url and messages. Use to poll an asynchronous purchase or fetch the label_url. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `transaction_id` (`string`, required): Object ID of the transaction, as returned when the label was purchased. Example input: `{"transaction_id":""}` ### `shippo_get_manifest` Get Manifest · Read-only Retrieve one manifest by its object ID. Returns status, documents (links to the manifest files) and errors. Use to poll an asynchronous manifest or fetch its document links. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `manifest_id` (`string`, required): Object ID of the manifest. Example input: `{"manifest_id":""}` ### `shippo_get_order` Get Order · Read-only Retrieve one order by its object ID. Returns the order with status, addresses, line_items and any linked transactions. Use when you have an order object_id. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `order_id` (`string`, required): Object ID of the order. Example input: `{"order_id":""}` ### `shippo_get_parcel` Get Parcel · Read-only Retrieve one parcel object by its object ID. Returns the parcel dimensions, weight and units. Use when you have a parcel object_id. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `parcel_id` (`string`, required): Object ID of the parcel. Example input: `{"parcel_id":""}` ### `shippo_get_rate` Get Rate · Read-only Retrieve one shipping rate by its object ID. Returns the rate with provider, servicelevel, amount, currency, estimated_days and attributes. Use to inspect a rate before buying it with shippo_create_label_from_rate. Rates older than 390 days are not returned. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `rate_id` (`string`, required): Object ID of the rate, as listed in a shipment rates array. Example input: `{"rate_id":""}` ### `shippo_get_refund` Get Refund · Read-only Retrieve one refund request by its object ID. Returns the refund with status and the transaction id. Use to check whether a refund has been accepted. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `refund_id` (`string`, required): Object ID of the refund. Example input: `{"refund_id":""}` ### `shippo_get_shipment` Get Shipment · Read-only Retrieve one shipment object by its object ID. Returns the shipment with status, addresses, parcels, messages and the rates array. Use to re-read a shipment or poll an asynchronous one. Use shippo_list_shipment_rates for a paginated rates list. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `shipment_id` (`string`, required): Object ID of the shipment, as returned by shippo_create_shipment. Example input: `{"shipment_id":""}` ### `shippo_get_tracking_status` Get Tracking Status · Read-only Get the current tracking status and history of a package from the carrier name and tracking number. Returns tracking_status (status, status_details, status_date, location), tracking_history, eta, servicelevel and addresses. Use to track a package. The carrier must be a Shippo carrier token such as usps, ups, fedex or dhl_express. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `carrier` (`string`, required): Shippo carrier token, for example usps, ups, fedex, dhl_express. - `tracking_number` (`string`, required): Tracking number issued by the carrier. Example input: `{"carrier":"","tracking_number":""}` ### `shippo_get_user_parcel_template` Get User Parcel Template · Read-only Retrieve one saved parcel template by its object ID. Returns name, dimensions, units and default weight. Use when you have the template id. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `user_parcel_template_object_id` (`string`, required): Object ID of the user parcel template. Example input: `{"user_parcel_template_object_id":""}` ### `shippo_list_address_book_entries` List Address Book Entries · Read-only List or search addresses stored in the Shippo address book. Returns a page of address book entries; use offset and limit to page through them. Use to find a saved address by search text. Use shippo_get_address_book_entry when you know the id. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `limit` (`integer`, optional): Maximum number of entries to return. Default: `30`. - `offset` (`integer`, optional): Number of entries to skip, for paging. Default: `0`. - `search` (`string`, optional): Free text matched against stored address fields such as name, organization and city. Example input: `{}` ### `shippo_list_addresses` List Addresses · Read-only List address objects that were created in this Shippo account. Returns a paginated object with next, previous and results (each result is an address with object_id, street1, city, state, zip, country). Use to browse stored addresses. Use shippo_get_address when you already know the object_id. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `page` (`integer`, optional): Page number to return, starting at 1. - `results` (`integer`, optional): Number of results per page (maximum 100). Default: `5`. Example input: `{}` ### `shippo_list_carrier_accounts` List Carrier Accounts · Read-only List the carrier accounts connected to this Shippo account, including Shippo-provided and your own. Returns a paginated object with next, previous and results (each has object_id, carrier, account_id, active, test). Use to find the carrier_account ids needed for shipments, labels, batches and manifests. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `account_id` (`string`, optional): Only return the account with this carrier account identifier. - `carrier` (`string`, optional): Only return accounts for this carrier token, for example usps. One of: `airterra`, `apc_postal`, `apg`, `aramex`, `asendia_us`, `australia_post`, `axlehire`, `better_trucks`, `borderguru`, `boxberry`, `bring`, `canada_post`, `chronopost`, `collect_plus`, `correios_br`, `correos_espana`, `colissimo`, `deutsche_post`, `dhl_benelux`, `dhl_ecommerce`, `dhl_express`, `dhl_germany_c2c`, `dhl_germany`, `dpd_de`, `dpd_uk`, `estafeta`, `fastway_australia`, `fedex`, `globegistics`, `gls_us`, `gophr`, `gso`, `hermes_germany_b2c`, `hermes_uk`, `hongkong_post`, `lasership`, `lso`, `mondial_relay`, `new_zealand_post`, `nippon_express`, `ontrac`, `parcelforce`, `passport`, `pcf`, `poste_italiane`, `posti`, `purolator`, `royal_mail`, `royal_mail_sf`, `rr_donnelley`, `russian_post`, `skypostal`, `stuart`, `swyft`, `uds`, `ups`, `usps`, `veho`. - `page` (`integer`, optional): Page number to return, starting at 1. - `results` (`integer`, optional): Number of results per page (maximum 100). Default: `5`. - `service_levels` (`boolean`, optional): If true, include the service_levels offered by each account. Example input: `{}` ### `shippo_list_carrier_parcel_templates` List Carrier Parcel Templates · Read-only List carrier preset parcel templates (flat-rate boxes, envelopes and similar). Returns an object with results, each a template with token, carrier, name and dimensions. Use to find a template token for shippo_create_parcel. Use shippo_list_user_parcel_templates for your own templates. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `carrier` (`string`, optional): Only return templates of this carrier token, for example usps. - `include` (`string`, optional): Which templates to return: all, user (only those you saved) or enabled. Allowed values: all, user, enabled. One of: `all`, `user`, `enabled`. Example input: `{}` ### `shippo_list_customs_declarations` List Customs Declarations · Read-only List customs declarations created in this account. Returns a paginated object with next, previous and results. Use to browse declarations. Use shippo_get_customs_declaration for one. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `page` (`integer`, optional): Page number to return, starting at 1. - `results` (`integer`, optional): Number of results per page (maximum 100). Default: `5`. Example input: `{}` ### `shippo_list_customs_items` List Customs Items · Read-only List customs items created in this account. Returns a paginated object with next, previous and results. Use to browse items. Use shippo_get_customs_item for one. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `page` (`integer`, optional): Page number to return, starting at 1. - `results` (`integer`, optional): Number of results per page (maximum 100). Default: `25`. Example input: `{}` ### `shippo_list_labels` List Labels · Read-only List purchased shipping labels (transactions), optionally filtered by rate, status, tracking status or creation date. Returns a paginated object with next, previous and results (each a transaction with tracking_number, label_url and status). Use to find labels. Use shippo_get_label for one label. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `object_created_gt` (`string`, optional): Only return objects created after this ISO 8601 UTC date and time. - `object_created_gte` (`string`, optional): Only return objects created at or after this ISO 8601 UTC date and time. - `object_created_lt` (`string`, optional): Only return objects created before this ISO 8601 UTC date and time. - `object_created_lte` (`string`, optional): Only return objects created at or before this ISO 8601 UTC date and time. - `object_status` (`string`, optional): Only return labels with this transaction status. Allowed values: WAITING, QUEUED, SUCCESS, ERROR, REFUNDED, REFUNDPENDING, REFUNDREJECTED. One of: `WAITING`, `QUEUED`, `SUCCESS`, `ERROR`, `REFUNDED`, `REFUNDPENDING`, `REFUNDREJECTED`. - `page` (`integer`, optional): Page number to return, starting at 1. - `rate` (`string`, optional): Only return labels bought with this rate object ID. - `results` (`integer`, optional): Number of results per page (maximum 100). Default: `25`. - `tracking_status` (`string`, optional): Only return labels with this tracking status. Allowed values: UNKNOWN, PRE_TRANSIT, TRANSIT, DELIVERED, RETURNED, FAILURE. One of: `UNKNOWN`, `PRE_TRANSIT`, `TRANSIT`, `DELIVERED`, `RETURNED`, `FAILURE`. Example input: `{}` ### `shippo_list_manifests` List Manifests · Read-only List manifests created in this account. Returns a paginated object with next, previous and results. Use to browse manifests. Use shippo_get_manifest for one. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `page` (`integer`, optional): Page number to return, starting at 1. - `results` (`integer`, optional): Number of results per page (maximum 100). Default: `5`. Example input: `{}` ### `shippo_list_orders` List Orders · Read-only List orders, optionally filtered by status, shop app or date range. Returns a paginated object with next, previous and results. Use to browse orders. Use shippo_get_order for one. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `end_date` (`string`, optional): Only return orders created before this ISO 8601 UTC date and time. - `order_status` (`array`, optional): Only return orders in these statuses, for example PAID and SHIPPED. - `page` (`integer`, optional): Page number to return, starting at 1. - `results` (`integer`, optional): Number of results per page (maximum 100). Default: `25`. - `shop_app` (`string`, optional): Only return orders imported from this shop platform. One of: `Amazon`, `Bigcommerce`, `CSV_Import`, `eBay`, `ePages`, `Etsy`, `Godaddy`, `Magento`, `Shippo`, `Shopify`, `Spreecommerce`, `StripeRelay`, `Walmart`, `Weebly`, `WooCommerce`. - `start_date` (`string`, optional): Only return orders created after this ISO 8601 UTC date and time. Example input: `{}` ### `shippo_list_parcels` List Parcels · Read-only List parcel objects created in this Shippo account. Returns a paginated object with next, previous and results (each a parcel with dimensions and weight). Use to browse parcels. Use shippo_get_parcel for one parcel. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `page` (`integer`, optional): Page number to return, starting at 1. - `results` (`integer`, optional): Number of results per page (maximum 100). Default: `25`. Example input: `{}` ### `shippo_list_refunds` List Refunds · Read-only List label refund requests. Returns a paginated object with next, previous and results (each refund has object_id, status and transaction). Use to review refunds. Use shippo_get_refund for one refund. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `shippo_list_service_groups` List Service Groups · Read-only List service groups used for live rates at checkout. Returns an array of service groups with object_id, name, type, flat_rate and service_levels. Use to see how checkout shipping options are configured. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `shippo_list_shipment_rates` List Shipment Rates · Read-only List the shipping rates calculated for a shipment. Returns a paginated object with next, previous and results (each rate has object_id, provider, servicelevel, amount, currency, estimated_days). Use to compare rates for an existing shipment. Use shippo_list_shipment_rates_in_currency to get amounts in another currency. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `shipment_id` (`string`, required): Object ID of the shipment. - `page` (`integer`, optional): Page number to return, starting at 1. - `results` (`integer`, optional): Number of results per page (maximum 100). Default: `25`. Example input: `{"shipment_id":""}` ### `shippo_list_shipment_rates_in_currency` List Shipment Rates in Currency · Read-only List the shipping rates of a shipment with amounts converted to a chosen currency. Returns a paginated object with next, previous and results; amount_local and currency_local hold the converted values. Use when you need rates in a currency other than the carrier currency. Use shippo_list_shipment_rates otherwise. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `currency_code` (`string`, required): ISO 4217 currency code to convert the rates to, for example EUR. - `shipment_id` (`string`, required): Object ID of the shipment. - `page` (`integer`, optional): Page number to return, starting at 1. - `results` (`integer`, optional): Number of results per page (maximum 100). Default: `25`. Example input: `{"currency_code":"","shipment_id":""}` ### `shippo_list_shipments` List Shipments · Read-only List shipment objects created in this Shippo account, optionally filtered by creation date. Returns a paginated object with next, previous and results (each a shipment with addresses, parcels and rates). Use to browse shipments. Use shippo_get_shipment for one shipment. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `object_created_gt` (`string`, optional): Only return objects created after this ISO 8601 UTC date and time. - `object_created_gte` (`string`, optional): Only return objects created at or after this ISO 8601 UTC date and time. - `object_created_lt` (`string`, optional): Only return objects created before this ISO 8601 UTC date and time. - `object_created_lte` (`string`, optional): Only return objects created at or before this ISO 8601 UTC date and time. - `page` (`integer`, optional): Page number to return, starting at 1. - `page_token` (`string`, optional): Pagination token taken from the next or previous link of an earlier list response. - `results` (`integer`, optional): Number of results per page (maximum 100). Default: `25`. Example input: `{}` ### `shippo_list_user_parcel_templates` List User Parcel Templates · Read-only List your saved custom parcel templates. Returns an object with results, each a template with name, dimensions and default weight. Use to find a saved package size. Use shippo_list_carrier_parcel_templates for carrier presets. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `shippo_parse_address` Parse Address · Read-only Parse a single free-text address string into structured address fields. Returns address_line_1, address_line_2, city_locality, state_province, postal_code, country_code, email and phone where found. Use when you only have an unstructured address line, before creating an address or shipment. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `address` (`string`, required): The full address as a single string, for example "965 Mission St, Suite 425, San Francisco, CA 94103". Example input: `{"address":"
"}` ### `shippo_validate_address` Validate Address · Read-only Validate an existing address object and return any corrections. Returns the address with validation_results (is_valid and messages) and the normalized address fields. Use on an address you already created. Use shippo_validate_address_by_fields to check an address that is not stored yet. Prerequisite: create the address first with shippo_create_address. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `address_id` (`string`, required): Object ID of the address to validate, as returned by shippo_create_address. Example input: `{"address_id":""}` ### `shippo_validate_address_by_fields` Validate Address by Fields · Read-only Validate a US or international address from its fields without storing it, and get a recommended address back. Returns original_address, recommended_address, analysis (validation_result, address_type, changed_attributes) and geo. Use to check an address that is not saved. Use shippo_validate_address for a stored address object. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `address_line_1` (`string`, required): First line of the street address (street number and name). - `country_code` (`string`, required): Two-letter ISO 3166 country code of the address (for example US, CA, GB). One of: `AE`, `AR`, `AT`, `AU`, `AX`, `AZ`, `BA`, `BD`, `BE`, `BG`, `BH`, `BM`, `BN`, `BR`, `BS`, `BW`, `BY`, `CA`, `CH`, `CL`, `CO`, `CN`, `CY`, `CZ`, `DE`, `DK`, `EC`, `EE`, `EG`, `ES`, `FI`, `FO`, `FR`, `GB`, `GE`, `GF`, `GG`, `GI`, `GP`, `GR`, `GU`, `HK`, `HR`, `HU`, `ID`, `IE`, `IL`, `IM`, `IN`, `IS`, `IT`, `JE`, `JO`, `JP`, `KR`, `KY`, `KW`, `KZ`, `LB`, `LI`, `LT`, `LU`, `LV`, `MA`, `MC`, `MD`, `ME`, `MK`, `MO`, `MP`, `MQ`, `MT`, `MX`, `MY`, `NA`, `NL`, `NO`, `NZ`, `OM`, `PE`, `PH`, `PL`, `PM`, `PR`, `PT`, `PY`, `QA`, `RE`, `RO`, `RU`, `SA`, `SC`, `SE`, `SG`, `SI`, `SK`, `SM`, `SR`, `TH`, `TN`, `TR`, `TW`, `UA`, `US`, `UY`, `VN`, `WE`, `YT`, `ZA`. - `address_line_2` (`string`, optional): The second line of the address. Must be percent encoded when passed as a query parameter (e.g. #200 → %23200). - `city_locality` (`string`, optional): The city or locality of the address - `name` (`string`, optional): The name of the addressee - `organization` (`string`, optional): The organization of the addressee - `postal_code` (`string`, optional): The postal code or zip code - `state_province` (`string`, optional): The state, province, county, or municipal division Example input: `{"address_line_1":"","country_code":"AE"}` ### `shippo_add_shipments_to_batch` Add Shipments to Batch · Write Add batch shipments to an existing batch. Returns the updated batch with its batch_shipments. Use before purchasing. The batch must not have been purchased yet. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `batch_id` (`string`, required): Object ID of the batch to extend. - `batch_shipments` (`array`, required): List of batch shipment objects to add. Each has a shipment object (address_from, address_to, parcels) plus optional carrier_account, servicelevel_token and metadata. Example input: `{"batch_id":"","batch_shipments":[]}` ### `shippo_create_address` Create Address · Write Create an address object in Shippo that can be reused when creating shipments, orders and live rate requests. Returns the address with its object_id, is_complete flag and, when validate is true, validation_results. Use to store a sender or recipient address. Use shippo_validate_address to check an existing address, or shippo_create_address_book_entry for the newer address book. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `country` (`string`, required): ISO 3166-1 alpha-2 country code (for example US or DE). Country names are also accepted but codes are more reliable. - `city` (`string`, optional): required for purchase Name of a city. When creating a Quote Address, sending a city is optional but will yield more accurate Rates. Please bear in mind that city names may be ambiguous (there are 34 Springfields in the US). - `company` (`string`, optional): Company Name - `email` (`string`, optional): E-mail address of the contact person, RFC3696/5321-compliant. - `is_residential` (`boolean`, optional): Set true if the address is a residence and false if it is a business; some carriers charge a residential surcharge. - `metadata` (`string`, optional): Free-text note of up to 100 characters stored on the object, for example your own order or reference number. - `name` (`string`, optional): required for purchase First and Last Name of the addressee - `phone` (`string`, optional): Addresses containing a phone number allow carriers to call the recipient when delivering the Parcel. This increases the probability of delivery and helps to avoid accessorial charges after a Parcel has been shipped. - `state` (`string`, optional): required for purchase for some countries State/Province values are required for shipments from/to the US, AU, and CA. UPS requires province for some countries (i.e Ireland). To receive more accurate quotes, passing this field is recommended. - `street_no` (`string`, optional): Street number of the addressed building. This field can be included in street1 for all carriers except for DHL Germany. - `street1` (`string`, optional): First street line: street number and name, for example 965 Mission St. Needed to buy a label. - `street2` (`string`, optional): Second street line. - `street3` (`string`, optional): Third street line. Only accepted for USPS international shipments, UPS domestic and UPS international shipments. - `validate` (`boolean`, optional): Set to true to validate Address object. - `zip` (`string`, optional): required for purchase Postal code of an Address. When creating a Quote Addresses, sending a ZIP is optional but will yield more accurate Rates. Example input: `{"country":""}` ### `shippo_create_address_book_entry` Create Address Book Entry · Write Store an address in the Shippo address book (Addresses API v2). Returns the stored address with its object_id and normalized fields. Use to keep reusable addresses. Use shippo_create_address for the classic address object used directly by shipments. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `address_line_1` (`string`, required): The first line of the address - `country_code` (`string`, required): The ISO 3166 country code - `name` (`string`, required): The name of the addressee - `address_line_2` (`string`, optional): The second line of the address. Must be percent encoded when passed as a query parameter (e.g. #200 → %23200). - `address_type` (`string`, optional): The category of the address. It may affect how certain carriers charge for a delivery/pickup.It is recommended to specify it, if it is known. Allowed values: unknown, residential, commercial, po_box, military. One of: `unknown`, `residential`, `commercial`, `po_box`, `military`. - `city_locality` (`string`, optional): The city or locality of the address - `email` (`string`, optional): The email of the addressee - `organization` (`string`, optional): The organization of the addressee - `phone` (`string`, optional): The phone number of the addressee - `postal_code` (`string`, optional): The postal code or zip code - `state_province` (`string`, optional): The state, province, county, or municipal division Example input: `{"address_line_1":"","country_code":"","name":""}` ### `shippo_create_batch` Create Batch · Write Create a batch to buy many labels at once; Shippo validates the batch shipments asynchronously. Returns the batch with object_id and status (VALIDATING at first), plus batch_shipments once validated. Use for bulk label purchase. Poll shippo_get_batch until status is VALID, then call shippo_purchase_batch. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `batch_shipments` (`array`, required): List of batch shipment objects. Each has a shipment object (address_from, address_to, parcels) and optionally carrier_account, servicelevel_token and metadata. - `default_carrier_account` (`string`, required): Object ID of the carrier account used for every shipment that does not set its own. - `default_servicelevel_token` (`string`, required): Service level token used for every shipment that does not set its own, for example usps_priority. - `label_filetype` (`string`, optional): Print format of the label. If empty, will use the default format set from the Shippo dashboard. Allowed values: PNG, PNG_2.3x7.5, PDF, PDF_2.3x7.5, PDF_4x6, PDF_4x8, PDF_A4, PDF_A5, PDF_A6, ZPLII. One of: `PNG`, `PNG_2.3x7.5`, `PDF`, `PDF_2.3x7.5`, `PDF_4x6`, `PDF_4x8`, `PDF_A4`, `PDF_A5`, `PDF_A6`, `ZPLII`. - `metadata` (`string`, optional): Free-text note of up to 100 characters stored on the object, for example your own order or reference number. Example input: `{"batch_shipments":[],"default_carrier_account":"","default_servicelevel_token":""}` ### `shippo_create_carrier_account` Create Carrier Account · Write Connect a carrier account to Shippo, or add a Shippo-managed one. Returns the carrier account with object_id, carrier, account_id and active. Use to add your own carrier credentials. The required parameters differ per carrier; see the Shippo carrier accounts guide. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `account_id` (`string`, required): Identifier of the account at the carrier, such as the account number. - `carrier` (`string`, required): Shippo carrier token, for example usps, ups, fedex, dhl_express. - `active` (`boolean`, optional): Whether the carrier account is active. Inactive accounts are not used when rating shipments. - `metadata` (`string`, optional): Free-text note of up to 100 characters stored on the object, for example your own order or reference number. - `parameters` (`string`, optional): Carrier-specific credentials and settings as an object. The needed keys differ per carrier, for example account_number or username and password. - `test` (`boolean`, optional): Set true to mark the object as a test object. Example input: `{"account_id":"","carrier":""}` ### `shippo_create_customs_declaration` Create Customs Declaration · Write Create a customs declaration for an international shipment. Returns the declaration with object_id, contents_type, items and object_state (VALID or INVALID). Use before shippo_create_shipment for cross-border shipments, then pass its object_id as customs_declaration. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `certify` (`boolean`, required): Set true to confirm the information is accurate; it must be true for the declaration to be valid. - `certify_signer` (`string`, required): Name of the person who prepared the declaration and is responsible for it. - `contents_type` (`string`, required): Type of goods of the shipment. Allowed values available here. One of: `DOCUMENTS`, `GIFT`, `SAMPLE`, `MERCHANDISE`, `HUMANITARIAN_DONATION`, `RETURN_MERCHANDISE`, `OTHER`. - `items` (`array`, required): List of customs item objects. Each has description, quantity, net_weight, mass_unit, value_amount, value_currency and origin_country, and optionally tariff_number or hs_code. - `non_delivery_option` (`string`, required): Indicates how the carrier should proceed in case the shipment can't be delivered. Allowed values available here. One of: `ABANDON`, `RETURN`. - `address_importer` (`object`, optional): Address of the importer as an address object. - `aes_itn` (`string`, optional): required if eel_pfc is AES_ITN AES / ITN reference of the shipment. - `b13a_filing_option` (`string`, optional): B13A Option details are obtained by filing a B13A Canada Export Declaration via the Canadian Export Reporting System (CERS). More information on reporting commercial exports from Canada. Allowed values available here. One of: `FILED_ELECTRONICALLY`, `SUMMARY_REPORTING`, `NOT_REQUIRED`. - `b13a_number` (`string`, optional): must be provided if and only if b13a_filing_option is provided Represents the Proof of Report (POR) Number when b13a_filing_option is FILED_ELECTRONICALLY; the Summary ID Number when b13a_filing_option is SUMMARY_REPORTING; or the Exemption Number when b13a_filing_option is NOT_REQUIRED. - `certificate` (`string`, optional): Certificate reference of the shipment. - `commercial_invoice` (`boolean`, optional): Set true to request a commercial invoice for the shipment where the carrier supports it. - `contents_explanation` (`string`, optional): required if contents_type is OTHER Explanation of the type of goods of the shipment. - `disclaimer` (`string`, optional): Disclaimer for the shipment and customs information that have been provided. - `duties_payor` (`object`, optional): Who pays duties, as an object with type (SENDER, RECIPIENT or THIRD_PARTY), account (the carrier account number that pays) and address. Only accepted for FedEx shipments. - `eel_pfc` (`string`, optional): EEL / PFC type of the shipment. For most shipments from the US to CA, NOEEI_30_36 is applicable; for most other shipments from the US, NOEEI_30_37_a is applicable. Allowed values available here. One of: `NOEEI_30_37_a`, `NOEEI_30_37_h`, `NOEEI_30_37_f`, `NOEEI_30_36`, `AES_ITN`. - `exporter_identification` (`object`, optional): Extra exporter identification some countries require, as an object with an eori_number or a tax_id (type and number). - `exporter_reference` (`string`, optional): Exporter reference of an export shipment. - `importer_reference` (`string`, optional): Importer reference of an import shipment. - `incoterm` (`string`, optional): The incoterm reference of the shipment. FCA is available for DHL Express and FedEx only. eDAP is available for DPD UK only. DAP is available for DHL Express, FedEx, and DPD UK. If expecting DAP for other carriers, please use DDU. Allowed values: DDP, DDU, FCA, DAP, eDAP. One of: `DDP`, `DDU`, `FCA`, `DAP`, `eDAP`. - `invoice` (`string`, optional): Invoice reference of the shipment. - `is_vat_collected` (`boolean`, optional): Indicates whether the shipment's destination VAT has been collected. May be required for some destinations. - `license` (`string`, optional): License reference of the shipment. - `metadata` (`string`, optional): Free-text note of up to 100 characters stored on the object, for example your own order or reference number. - `notes` (`string`, optional): Additional notes to be included in the customs declaration. - `recipient_is_business` (`boolean`, optional): Indicates the shipment goes to a business (B2B) rather than a consumer. Newly created declarations default to false when the field is not provided; declarations created before the field existed return null, which is treated as false. - `test` (`boolean`, optional): Set true to mark the object as a test object. Example input: `{"certify":true,"certify_signer":"","contents_type":"DOCUMENTS","items":[],"non_delivery_option":"ABANDON"}` ### `shippo_create_customs_item` Create Customs Item · Write Create a customs item that describes one line of goods for a customs declaration. Returns the item with object_id, description, quantity, net_weight, value_amount and origin_country. Use to keep a standalone item record. shippo_create_customs_declaration takes its items inline as objects. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `description` (`string`, required): Text description of your item. - `mass_unit` (`string`, required): The unit used for weight. Allowed values: g, kg, lb, oz. One of: `g`, `kg`, `lb`, `oz`. - `net_weight` (`string`, required): Total net weight of all units of this item as a decimal string, in the unit given by mass_unit. - `origin_country` (`string`, required): ISO 3166-1 alpha-2 country code where the item was made, for example US or DE. - `quantity` (`integer`, required): Number of units of this item in the shipment. Must be greater than 0. - `value_amount` (`string`, required): Total value of all units of this item as a decimal string, in the currency given by value_currency. - `value_currency` (`string`, required): Currency used for value_amount. The official ISO 4217 currency codes are used, e.g. USD or EUR. - `eccn_ear99` (`string`, optional): Export Control Classification Number, required on some exports from the United States. - `eu_exempt_category` (`boolean`, optional): Marks the item as belonging to an EU-exempt product category. Exempt items do not need product identifiers on shipments that meet the EU product identifier conditions (EU destination, non-EU origin, MERCHANDISE contents, recipient not a business). - `hs_code` (`string`, optional): HS code of the item, which is required by some carriers. If tariff_number is not provided, hs_code will be used. If both hs_code and tariff_number are provided, tariff_number will be used. 50 character limit. - `manufacturer_code` (`string`, optional): Product identifier assigned by the manufacturer. Up to 100 characters; some carriers accept fewer and reject longer values at label purchase. Required together with sku_code on every non-exempt item when the shipment meets the EU product identifier conditions. - `manufacturer_standard_code` (`string`, optional): Standardized product identifier such as a GTIN. Up to 100 characters. Never required, but recommended for EU-bound shipments when one exists. - `metadata` (`string`, optional): Free-text note of up to 100 characters stored on the object, for example your own order or reference number. - `sku_code` (`string`, optional): SKU or merchant-assigned product code of the item. Up to 100 characters; some carriers accept fewer and reject longer values at label purchase. - `tariff_number` (`string`, optional): The tariff number of the item. If tariff_number is not provided, hs_code will be used. If both hs_code and tariff_number are provided, tariff_number will be used. 12 character limit. Example input: `{"description":"","mass_unit":"g","net_weight":"","origin_country":"","quantity":1,"value_amount":"","value_currency":""}` ### `shippo_create_label_from_rate` Create Label from Rate · Write Purchase a shipping label using a rate that was previously returned for a shipment. Returns the transaction with object_id, status, tracking_number, tracking_url_provider and label_url. This spends money in live mode. Use after picking a rate from shippo_create_shipment or shippo_list_shipment_rates. Use shippo_create_label_from_shipment to buy without a prior rate. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `rate` (`string`, required): Object ID of the rate to purchase, taken from a shipment rates array. - `async` (`boolean`, optional): If true, the request returns immediately and Shippo finishes processing in the background; poll the object afterwards to see its final status. Leave unset for a synchronous call. - `label_file_type` (`string`, optional): Print format of the label. Allowed values: PNG, PNG_2.3x7.5, PDF, PDF_2.3x7.5, PDF_4x6, PDF_4x8, PDF_A4, PDF_A5, PDF_A6, ZPLII. One of: `PNG`, `PNG_2.3x7.5`, `PDF`, `PDF_2.3x7.5`, `PDF_4x6`, `PDF_4x8`, `PDF_A4`, `PDF_A5`, `PDF_A6`, `ZPLII`. - `metadata` (`string`, optional): Free-text note of up to 100 characters stored on the object, for example your own order or reference number. - `order` (`string`, optional): Optional object ID of a Shippo order to attach the label to. Example input: `{"rate":""}` ### `shippo_create_label_from_shipment` Create Label from Shipment Details · Write Create and purchase a label in one call from shipment details, a carrier account and a service level token. Returns the transaction with object_id, status, tracking_number and label_url. This spends money in live mode. Use when you already know the carrier account and service level. Use shippo_create_label_from_rate after rate shopping. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `carrier_account` (`string`, required): Object ID of the carrier account that will ship the package. - `servicelevel_token` (`string`, required): Token of the service level to buy, for example usps_priority or ups_ground. - `shipment` (`object`, required): Shipment details as an object with address_from, address_to and parcels (and optionally customs_declaration and extra), as accepted by shippo_create_shipment. - `async` (`boolean`, optional): If true, the request returns immediately and Shippo finishes processing in the background; poll the object afterwards to see its final status. Leave unset for a synchronous call. - `label_file_type` (`string`, optional): Print format of the label. Allowed values: PNG, PNG_2.3x7.5, PDF, PDF_2.3x7.5, PDF_4x6, PDF_4x8, PDF_A4, PDF_A6, ZPLII. One of: `PNG`, `PNG_2.3x7.5`, `PDF`, `PDF_2.3x7.5`, `PDF_4x6`, `PDF_4x8`, `PDF_A4`, `PDF_A6`, `ZPLII`. - `metadata` (`string`, optional): Free-text note of up to 100 characters stored on the object, for example your own order or reference number. - `order` (`string`, optional): Optional object ID of a Shippo order to attach the label to. Example input: `{"carrier_account":"","servicelevel_token":"","shipment":{}}` ### `shippo_create_manifest` Create Manifest · Write Create a manifest (end-of-day SCAN form) that closes out the labels shipped on a day for one carrier account. Returns the manifest with object_id, status, documents and any errors. Use at the end of the shipping day for carriers that need a manifest. Creation can be asynchronous; poll with shippo_get_manifest. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `address_from` (`object`, required): Pickup address as an address object or the object_id of an existing address. - `carrier_account` (`string`, required): Object ID of the carrier account to close out. - `shipment_date` (`string`, required): Day whose shipments are closed out, in ISO 8601 format. - `async` (`boolean`, optional): If true, the request returns immediately and Shippo finishes processing in the background; poll the object afterwards to see its final status. Leave unset for a synchronous call. - `transactions` (`array`, optional): Optional list of label object_ids to include. When empty, all labels of that day for the carrier account are included. Example input: `{"address_from":{},"carrier_account":"","shipment_date":""}` ### `shippo_create_order` Create Order · Write Create an order record in Shippo from a recipient address and line items. Returns the order with object_id, order_number, order_status, addresses and line_items. Use to track a customer order before shipping. Attach a label to it by passing its object_id as order in the label tools. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `placed_at` (`string`, required): Date and time the order was placed, in ISO 8601 format. - `to_address` (`object`, required): Recipient address as an address object, or the object_id of an existing address. - `currency` (`string`, optional): ISO 4217 currency code of total_price and total_tax. Required when total_price is set. - `from_address` (`object`, optional): Sender address as an address object, or the object_id of an existing address. - `line_items` (`array`, optional): List of items in the order. Each has a title, quantity, sku, total_price, currency, weight and weight_unit. - `notes` (`string`, optional): Custom buyer- or seller-provided notes about the order. - `order_number` (`string`, optional): An alphanumeric identifier for the order used by the seller/buyer. This identifier doesn't need to be unique. - `order_status` (`string`, optional): Current state of the order. Allowed values: UNKNOWN, AWAITPAY, PAID, REFUNDED, CANCELLED, PARTIALLY_FULFILLED, SHIPPED. One of: `UNKNOWN`, `AWAITPAY`, `PAID`, `REFUNDED`, `CANCELLED`, `PARTIALLY_FULFILLED`, `SHIPPED`. - `shipping_cost` (`string`, optional): Amount paid by the buyer for shipping. This amount can be different from the price the seller will actually pay for shipping. - `shipping_cost_currency` (`string`, optional): ISO 4217 currency code of shipping_cost. Required when shipping_cost is set. - `shipping_method` (`string`, optional): Shipping method (carrier + service or other free text description) chosen by the buyer. This value can be different from the shipping method the seller will actually choose. - `subtotal_price` (`string`, optional): Amount paid by the buyer for the items before shipping and tax, as a decimal string. - `total_price` (`string`, optional): Total amount paid by the buyer for this order. - `total_tax` (`string`, optional): Total tax amount paid by the buyer for this order. - `weight` (`string`, optional): Total weight of the order. - `weight_unit` (`string`, optional): The unit used for weight. Allowed values: g, kg, lb, oz. One of: `g`, `kg`, `lb`, `oz`. Example input: `{"placed_at":"","to_address":{}}` ### `shippo_create_parcel` Create Parcel · Write Create a parcel object with dimensions and weight, or from a carrier parcel template plus weight. Returns the parcel with object_id, dimensions, weight and units. Use to define a package before creating a shipment. Provide either length, width, height and distance_unit, or a template. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `mass_unit` (`string`, required): The unit used for weight. Allowed values: g, kg, lb, oz. One of: `g`, `kg`, `lb`, `oz`. - `weight` (`string`, required): Weight of the parcel as a decimal string (up to six digits before and four after the decimal point), in the unit given by mass_unit. - `distance_unit` (`string`, optional): Unit for length, width and height. Needed unless template is set. Allowed values: cm, in, ft, m, mm, yd. One of: `cm`, `in`, `ft`, `m`, `mm`, `yd`. - `extra` (`object`, optional): Optional extra services for this parcel as an object, for example reference_1, reference_2, insurance or COD. - `height` (`string`, optional): Height of the parcel as a decimal string, in the unit given by distance_unit. Needed unless template is set. - `length` (`string`, optional): Length of the parcel as a decimal string, in the unit given by distance_unit. Needed unless template is set. - `metadata` (`string`, optional): Free-text note of up to 100 characters stored on the object, for example your own order or reference number. - `template` (`string`, optional): Carrier parcel template token such as USPS_FlatRateEnvelope. When set, length, width, height and distance_unit must be left empty. - `width` (`string`, optional): Width of the parcel as a decimal string, in the unit given by distance_unit. Needed unless template is set. Example input: `{"mass_unit":"g","weight":""}` ### `shippo_create_pickup` Create Pickup · Write Schedule a carrier pickup for purchased labels (USPS and DHL Express only). Returns the pickup with object_id, status, confirmation_code and the confirmed time window. Use after buying labels when a carrier should collect the packages from a location. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `carrier_account` (`string`, required): Object ID of your USPS or DHL Express carrier account. - `location` (`object`, required): Pickup location as an object with building_location_type (for example Front Door), an address object and optionally building_type and instructions. - `requested_end_time` (`string`, required): Latest time the parcels are available, in ISO 8601 format. - `requested_start_time` (`string`, required): Earliest time the parcels are ready, in ISO 8601 format. - `transactions` (`array`, required): List of label (transaction) object_ids to be picked up. - `metadata` (`string`, optional): Free-text note of up to 100 characters stored on the object, for example your own order or reference number. Example input: `{"carrier_account":"","location":{},"requested_end_time":"","requested_start_time":"","transactions":[]}` ### `shippo_create_refund` Create Refund · Write Request a refund for an unused shipping label. Returns the refund with object_id, status (QUEUED, PENDING, SUCCESS or ERROR) and the transaction id. Use for labels that were never scanned by the carrier; eligibility depends on carrier policy. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `transaction` (`string`, required): Object ID of the label (transaction) to refund, as returned by shippo_create_label_from_rate. - `async` (`boolean`, optional): If true, the request returns immediately and Shippo finishes processing in the background; poll the object afterwards to see its final status. Leave unset for a synchronous call. Example input: `{"transaction":""}` ### `shippo_create_service_group` Create Service Group · Write Create a service group that defines a checkout shipping option (live rate, flat rate or free shipping). Returns the service group with object_id and its settings. Use to configure live rates at checkout; see shippo_create_live_rates. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `description` (`string`, required): Description for the service group - `name` (`string`, required): Name for the service group that will be shown to customers in the response - `service_levels` (`array`, required): List of service levels in the group. Each is an object with account_object_id (the carrier account object_id) and service_level_token (for example usps_priority). - `type` (`string`, required): LIVE_RATE (Shippo rates the shipment), FLAT_RATE (fixed price) or FREE_SHIPPING (free above a threshold). Allowed values: LIVE_RATE, FLAT_RATE, FREE_SHIPPING. One of: `LIVE_RATE`, `FLAT_RATE`, `FREE_SHIPPING`. - `flat_rate` (`string`, optional): String representation of an amount to be returned as the flat rate if 1. The service group is of type LIVE_RATE and no matching rates were found; or 2. The service group is of type FLAT_RATE. Either integers or decimals are accepted. Required unless type is FREE_SHIPPING - `flat_rate_currency` (`string`, optional): required unless type is FREE_SHIPPING. (ISO 4217 currency) - `free_shipping_threshold_currency` (`string`, optional): optional unless type is FREE_SHIPPING. (ISO 4217 currency) - `free_shipping_threshold_min` (`string`, optional): For service groups of type FREE_SHIPPING, this field must be required to configure the minimum cart total (total cost of items in the cart) for this service group to be returned for rates at checkout. Optional unless type is FREE_SHIPPING - `rate_adjustment` (`integer`, optional): The amount in percent (%) that the service group's returned rate should be adjusted. For example, if this field is set to 5 and the matched rate price is $5.00, the returned value of the service group will be $5.25. Example input: `{"description":"","name":"","service_levels":[],"type":"LIVE_RATE"}` ### `shippo_create_shipment` Create Shipment · Write Create a shipment from sender, recipient and parcels; Shippo then calculates the available shipping rates. Returns the shipment with object_id, status, messages and a rates array (each rate has object_id, provider, servicelevel, amount, currency, estimated_days). Use to rate shop. Buy a label from a chosen rate with shippo_create_label_from_rate. Use shippo_create_label_from_shipment to rate and buy in one call. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `address_from` (`object`, required): Sender address. Either the object_id of an existing address or an address object with name, street1, city, state, zip and country. - `address_to` (`object`, required): Recipient address. Either the object_id of an existing address or an address object with name, street1, city, state, zip and country. - `parcels` (`array`, required): List of parcels to ship. Each item is either the object_id of an existing parcel or a parcel object with length, width, height, distance_unit, weight and mass_unit. - `address_return` (`object`, optional): Optional return address. Either the object_id of an existing address or an address object; defaults to the sender address. - `async` (`boolean`, optional): If true, the request returns immediately and Shippo finishes processing in the background; poll the object afterwards to see its final status. Leave unset for a synchronous call. - `carrier_accounts` (`array`, optional): Optional list of carrier account object_ids to rate with. When empty, all your active carrier accounts are used. - `customs_declaration` (`object`, optional): Customs declaration for international shipments: the object_id returned by shippo_create_customs_declaration, or a customs declaration object. - `extra` (`object`, optional): Optional extra services as an object, for example signature_confirmation, insurance, reference_1, saturday_delivery. - `metadata` (`string`, optional): Free-text note of up to 100 characters stored on the object, for example your own order or reference number. - `shipment_date` (`string`, optional): Date and time the shipment will be handed to the carrier, in ISO 8601 format. Example input: `{"address_from":{},"address_to":{},"parcels":[]}` ### `shippo_create_user_parcel_template` Create User Parcel Template · Write Save a reusable parcel template, either custom dimensions or based on a carrier preset. Returns the template with object_id, name, dimensions and weight. Use to store common box sizes. Send name, length, width, height and distance_unit for a custom one, or template for a carrier preset. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `distance_unit` (`string`, optional): The measure unit used for length, width and height. Allowed values: cm, in, ft, m, mm, yd. One of: `cm`, `in`, `ft`, `m`, `mm`, `yd`. - `height` (`string`, optional): The height of the package, in units specified by the distance_unit attribute. Required, but if using a preset carrier template then this field must be empty. - `length` (`string`, optional): The length of the package, in units specified by the distance_unit attribute. Required, but if using a preset carrier template then this field must be empty. - `name` (`string`, optional): Name of the template. Required for a custom template. - `template` (`string`, optional): Carrier parcel template token to base this on, for example USPS_FlatRateEnvelope. Leave empty for a fully custom template. - `weight` (`string`, optional): The weight of the package, in units specified by the weight_unit attribute. - `weight_unit` (`string`, optional): The unit used for weight. Allowed values: g, kg, lb, oz. One of: `g`, `kg`, `lb`, `oz`. - `width` (`string`, optional): The width of the package, in units specified by the distance_unit attribute. Required, but if using a preset carrier template then this field must be empty. Example input: `{}` ### `shippo_purchase_batch` Purchase Batch · Write Purchase all labels of a batch whose status is VALID. Returns the batch with status PURCHASING; it becomes PURCHASED when all labels are bought. This spends money in live mode. Use after shippo_create_batch has reached VALID. Poll with shippo_get_batch. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `batch_id` (`string`, required): Object ID of the batch to purchase. Example input: `{"batch_id":""}` ### `shippo_remove_shipments_from_batch` Remove Shipments from Batch · Write Remove batch shipments from an existing batch. Returns the updated batch. Use to drop invalid or unwanted shipments before purchase. Pass the object_ids of the batch shipments, not of the underlying shipments. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `batch_id` (`string`, required): Object ID of the batch. - `shipments` (`array`, required): List of batch shipment object_ids to remove. Example input: `{"batch_id":"","shipments":[]}` ### `shippo_update_address_book_entry` Update Address Book Entry · Write Replace the values of an existing address book entry. Returns the updated address book entry. Use to correct a saved address. The name, address_line_1 and country_code fields are always required, so send the full address. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `address_id` (`string`, required): Object ID of the address book entry to update. - `address_line_1` (`string`, required): The first line of the address - `country_code` (`string`, required): The ISO 3166 country code - `name` (`string`, required): The name of the addressee - `address_line_2` (`string`, optional): The second line of the address. Must be percent encoded when passed as a query parameter (e.g. #200 → %23200). - `address_type` (`string`, optional): The category of the address. It may affect how certain carriers charge for a delivery/pickup.It is recommended to specify it, if it is known. Allowed values: unknown, residential, commercial, po_box, military. One of: `unknown`, `residential`, `commercial`, `po_box`, `military`. - `city_locality` (`string`, optional): The city or locality of the address - `email` (`string`, optional): The email of the addressee - `organization` (`string`, optional): The organization of the addressee - `phone` (`string`, optional): The phone number of the addressee - `postal_code` (`string`, optional): The postal code or zip code - `state_province` (`string`, optional): The state, province, county, or municipal division Example input: `{"address_id":"","address_line_1":"","country_code":"","name":""}` ### `shippo_update_carrier_account` Update Carrier Account · Write Update the active flag, parameters or metadata of a carrier account. Returns the updated carrier account. Use to enable, disable or re-credential an account. carrier and account_id identify the account and cannot be changed, but must be sent. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `account_id` (`string`, required): Identifier of the account at the carrier. It cannot be changed but must be sent. - `carrier` (`string`, required): Shippo carrier token of the account, for example usps. It cannot be changed but must be sent. - `carrier_account_id` (`string`, required): Object ID of the carrier account to update. - `active` (`boolean`, optional): Whether the carrier account is active. Inactive accounts are not used when rating shipments. - `parameters` (`string`, optional): Carrier-specific credentials and settings as an object. The needed keys differ per carrier. Example input: `{"account_id":"","carrier":"","carrier_account_id":""}` ### `shippo_update_service_group` Update Service Group · Write Update an existing service group, identified by object_id in the body. Returns the updated service group. Use to rename a group, change its price or switch it on or off. All required fields must be sent again. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `description` (`string`, required): Description for the service group - `is_active` (`boolean`, required): True if the service group is enabled, false otherwise. - `name` (`string`, required): Name for the service group that will be shown to customers in the response - `object_id` (`string`, required): Object ID of the service group to update. - `service_levels` (`array`, required): List of service levels in the group. Each is an object with account_object_id (the carrier account object_id) and service_level_token (for example usps_priority). - `type` (`string`, required): The type of the service group. - LIVE_RATE: Shippo will make a rating request and return real-time rates for the shipping group, only falling back to the specified flat rate amount if no rates match a service level in the service group. Allowed values: LIVE_RATE, FLAT_RATE, FREE_SHIPPING. One of: `LIVE_RATE`, `FLAT_RATE`, `FREE_SHIPPING`. - `flat_rate` (`string`, optional): String representation of an amount to be returned as the flat rate if 1. The service group is of type LIVE_RATE and no matching rates were found; or 2. The service group is of type FLAT_RATE. Either integers or decimals are accepted. Required unless type is FREE_SHIPPING - `flat_rate_currency` (`string`, optional): required unless type is FREE_SHIPPING. (ISO 4217 currency) - `free_shipping_threshold_currency` (`string`, optional): optional unless type is FREE_SHIPPING. (ISO 4217 currency) - `free_shipping_threshold_min` (`string`, optional): For service groups of type FREE_SHIPPING, this field must be required to configure the minimum cart total (total cost of items in the cart) for this service group to be returned for rates at checkout. Optional unless type is FREE_SHIPPING - `rate_adjustment` (`integer`, optional): The amount in percent (%) that the service group's returned rate should be adjusted. For example, if this field is set to 5 and the matched rate price is $5.00, the returned value of the service group will be $5.25. Example input: `{"description":"","is_active":true,"name":"","object_id":"","service_levels":[],"type":"LIVE_RATE"}` ### `shippo_update_user_parcel_template` Update User Parcel Template · Write Update a saved parcel template. Returns the updated template. Use to change a template size or weight. name, length, width, height and distance_unit are always required. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `distance_unit` (`string`, required): The measure unit used for length, width and height. Allowed values: cm, in, ft, m, mm, yd. One of: `cm`, `in`, `ft`, `m`, `mm`, `yd`. - `height` (`string`, required): The height of the package, in units specified by the distance_unit attribute. Required, but if using a preset carrier template then this field must be empty. - `length` (`string`, required): The length of the package, in units specified by the distance_unit attribute. Required, but if using a preset carrier template then this field must be empty. - `name` (`string`, required): The name of the User Parcel Template - `user_parcel_template_object_id` (`string`, required): Object ID of the template to update. - `width` (`string`, required): The width of the package, in units specified by the distance_unit attribute. Required, but if using a preset carrier template then this field must be empty. - `weight` (`string`, optional): The weight of the package, in units specified by the weight_unit attribute. - `weight_unit` (`string`, optional): The unit used for weight. Allowed values: g, kg, lb, oz. One of: `g`, `kg`, `lb`, `oz`. Example input: `{"distance_unit":"cm","height":"","length":"","name":"","user_parcel_template_object_id":"","width":""}` ### `shippo_delete_address_book_entry` Delete Address Book Entry · Destructive Remove an address from the Shippo address book by its object ID. Returns an empty response on success. Use only when the saved address is no longer needed; shipments that already used it are not affected. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `address_id` (`string`, required): Object ID of the address book entry to delete. Example input: `{"address_id":""}` ### `shippo_delete_service_group` Delete Service Group · Destructive Delete a service group by its object ID. Returns an empty response on success. Use only when the checkout option is no longer offered. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `service_group_id` (`string`, required): Object ID of the service group to delete. Example input: `{"service_group_id":""}` ### `shippo_delete_user_parcel_template` Delete User Parcel Template · Destructive Delete a saved parcel template by its object ID. Returns an empty response on success. Use only when the template is no longer needed. Read only: no. Destructive: yes. Idempotent (safe to retry): yes. Inputs: - `user_parcel_template_object_id` (`string`, required): Object ID of the template to delete. Example input: `{"user_parcel_template_object_id":""}` ## Related Other Automation connectors ([all 62](/agentkit/connectors/?category=automation)): - [Mailchimp](/agentkit/connectors/mailchimp/): Scalekit connector, OAuth, 73 tools - [Twilio](/agentkit/connectors/twilio/): Scalekit connector, Username and password, 61 tools - [Stripe](/agentkit/connectors/stripe/): Scalekit connector, Access token, 178 tools --- ## More Scalekit documentation | Resource | What it contains | When to use it | |----------|-----------------|----------------| | [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content | | [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas | | [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |