Shippo connector for AI agents

Tools your shipping agent reaches for on Shippo, scoped per user.

CALL ANY TOOL

63 tools for shipping in Shippo: create shipments and compare rates, buy labels, track packages, validate addresses, prepare customs, and run batches, manifests, and pickups.

shippo_add_shipments_to_batch

Batch add shipments to

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.

Parameters

Name

Type

Required

Description

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.

shippo_create_address

Create address

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.

Parameters

Name

Type

Required

Description

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

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.

shippo_create_batch

Batch create

shippo_create_customs_item

Create customs item

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.

Parameters

Name

Type

Required

Description

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.

shippo_create_label_from_rate

Create label from rate

shippo_create_manifest

Create manifest

shippo_create_parcel

Create parcel

shippo_create_service_group

Create service group

shippo_delete_address_book_entry

Delete address book entry

shippo_get_address

Get address

shippo_get_batch

Batch get

shippo_get_carrier_parcel_template

Get carrier parcel template

shippo_get_customs_item

Get customs item

shippo_get_manifest

Get manifest

shippo_get_parcel

Get parcel

shippo_get_refund

Refund get

shippo_get_tracking_status

Get tracking status

shippo_list_address_book_entries

List address book entries

shippo_list_carrier_accounts

List carrier accounts

shippo_list_customs_declarations

List customs declarations

shippo_list_labels

List labels

shippo_list_orders

List orders

shippo_list_refunds

List refunds

shippo_list_shipment_rates

List shipment rates

shippo_list_shipments

List shipments

shippo_parse_address

Parse address

shippo_remove_shipments_from_batch

Batch remove shipments from

shippo_update_address_book_entry

Update address book entry

shippo_update_service_group

Update service group

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.

Parameters

Name

Type

Required

Description

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.

shippo_validate_address

Validate address

For more tools, view docs.

Build your Agent

Same auth pattern across LangChain, OpenAI, Anthropic, and Google ADK.

import { ScalekitClient } from "@scalekit-sdk/node";
import { createReactAgent } from "@langchain/langgraph/prebuilt";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);

// Shippo tools scoped to this user
const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["shippo"], toolNames: [
    "shippo_create_shipment",
    "shippo_create_label_from_rate",
    "shippo_get_tracking_status"] },
  pageSize: 100,
});

const agent = createReactAgent({ llm, tools });
await agent.invoke({ messages: [{ role: "user", content: "Buy the cheapest label for a 2 lb parcel from Austin to Denver" }] });

import OpenAI from "openai";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);
const openai = new OpenAI();

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["shippo"] }, pageSize: 100,
});

const res = await openai.chat.completions.create({
  model: "gpt-5",
  messages: [{ role: "user", content: "Buy the cheapest label for a 2 lb parcel from Austin to Denver" }],
  tools,
});

// Execute the tool call with the user's vaulted Shippo API key
await sk.tools.executeTool(res.choices[0].message.tool_calls[0], "user_123");

import Anthropic from "@anthropic-ai/sdk";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);
const anthropic = new Anthropic();

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["shippo"] }, pageSize: 100,
});

const msg = await anthropic.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Buy the cheapest label for a 2 lb parcel from Austin to Denver" }],
  tools,
});

// Tool call runs with the user's vaulted Shippo API key
await sk.tools.executeTool(msg.content, "user_123");

import { Agent } from "@google/adk/agents";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["shippo"] }, pageSize: 100,
});

const agent = new Agent({
  name: "shipping_agent",
  model: "gemini-2.5-pro",
  instruction: "Shippo tools scoped to this user",
  tools,
});

await agent.run("Buy the cheapest label for a 2 lb parcel from Austin to Denver");

Try these prompts

Copy any prompt into your agent. Each maps directly to a Shippo tool. Click to copy, paste into your agent, done.

Rates and labels

Copy the prompt

Copied

Get rates for a 2 lb parcel from Austin to Denver.

Copy the prompt

Copied

Buy a label with the cheapest rate on that shipment.

Copy the prompt

Copied

Request a refund for the unused label on order 1042.

Tracking and addresses

Copy the prompt

Copied

What is the tracking status of this USPS package?

Copy the prompt

Copied

Validate this address: 1 Main St, Springfield, IL.

Copy the prompt

Copied

Parse this pasted address into fields.

Bulk and international

Copy the prompt

Copied

Create a batch for today's 40 orders.

Copy the prompt

Copied

Create a customs declaration for 3 T-shirts shipping to Canada.

Copy the prompt

Copied

Schedule a USPS pickup for today's labels.

SEE HOW AUTH WORKS

Each user connects their own Shippo API key once, and Scalekit sends it with every call. Keys stay vaulted, every call is scope checked, and every action is logged.

Authorize

Your user connects

Shippo

once. We tie it to their identity and the meetings they approved — no shared bot account, no org-wide access

Who:

user ‘A’

when:

Once per user

access:

Limited to user

Store

Their

Shippo

token lives in a vault scoped to them. User A's meetings are never reachable by an agent acting for user B, even on the same connection

vault:

encrypted

scope:

per-user

tokens:

auto-refreshed

Resolve

When your agent calls a

Shippo

tool, we fetch the right token server-side. It never touches your agent, never appears in the LLM context, never shows up in your logs

speed:

~40ms

check:

before every call

seen by:

nobody

Audit

Every

Shippo

tool call is logged — who triggered it, which meeting was fetched, what came back. 90 days of history, tied to the user who authorized it

history:

90 days

export:

SIEM-ready

logged:

every call

Test other agents

See the same per-user auth pattern across other automation and commerce connectors.

Support and Ops Teams

Support ticket automation agent

Fetches new Zendesk tickets, drafts a reply from Notion knowledge base articles, digests what it cannot answer to Slack, and archives the rest, acting as the support agent rather than a shared API key.

GTM and RevOps Teams

CRM AI agent

Reads the Granola transcript after every call, extracts next steps and updates the HubSpot record, drafts the follow-up in Gmail, and confirms in Slack, all on the rep's own delegated OAuth.

Why Scalekit

Secure your agent's access. Connectors ship in minutes

01.

Shared tokens break per-user analytics

A shared Shippo API key looks fine in a demo. In production every label purchase and refund looks like one service account, and you cannot tell which user triggered it. Scalekit resolves the credential of the actual user who triggered the agent, never a shared bot.

// shared key
audit → bot_service_account

// scalekit
audit → user_abc ✓

02.

Authentication is not authorization

03.

Multi-tenancy is architectural

04.

Shippo today. Ten connectors tomorrow.

“Our agents act across Salesforce, Gong, Google Drive, and more, on behalf of every customer. Scalekit behind the scenes meant we can keep adding tools without ever rebuilding how credentials or tool calling work.”

Venu Madhav Kattagoni

Head of Engineering / Von

FAQs

Frequently Asked Questions

Does the agent access Shippo as the user or through a shared key?

As the user. Each user connects their own Shippo API key once, and Scalekit sends it with every call. Audit logs attribute every label purchase and refund to that user, not a shared service account.

Where is the Shippo API key stored?

In Scalekit's managed AES-256 token vault, namespaced per tenant. To rotate it, the user reconnects with a new API key. Revocation is a single dashboard action. Credentials never appear in prompts, logs, or LLM context.

Can I limit what the agent does in Shippo?

Yes. Filter by tool name in listScopedTools to expose only what you want, for example rate and tracking tools without shippo_create_label_from_rate or shippo_purchase_batch, which buy labels. Scalekit also enforces scope checks before every API call.

What happens when a user revokes Shippo access?

The connection is invalidated on the next tool call. Subsequent requests for that user fail closed with a clear error. Other users in the tenant remain unaffected. The event is logged for audit.

Can the agent buy shipping labels?

Yes, if you expose those tools. shippo_create_label_from_rate buys a label from a rate you already fetched, shippo_create_label_from_shipment creates and buys a label in one call, and shippo_purchase_batch buys every label in a valid batch. shippo_create_refund requests a refund for an unused label.