easypost-api

Original：🇺🇸 English

Translated

8 scripts

Build, debug, and extend integrations with the EasyPost shipping API. Use this skill whenever the user mentions EasyPost, shipping labels, postage, rate shopping, tracking packages programmatically, customs forms, carrier accounts (USPS/UPS/FedEx/DHL/ePost Global), scan forms, pickups, shipping insurance, or webhooks for shipping events. Also trigger on phrases like "create a shipping label," "buy postage," "rate a parcel," "verify an address," "international shipment," "commercial invoice," "Luma rate shopping," "UPS DAP," "DHL eCommerce," or any task involving the `@easypost/api` Node.js SDK or REST endpoints under `api.easypost.com/v2`. Optimized for Node.js/TypeScript but the REST patterns, field names, and carrier gotchas apply in any language.

2installs

Sourcehamstudy/easypost-skill

Added on2026-04-18

NPX Install

npx skill4agent add hamstudy/easypost-skill easypost-api

SKILL.md Content

View Translation Comparison →

EasyPost API Skill

This skill makes Claude productive at building EasyPost integrations. It covers the full shipping workflow: addresses, parcels, rates, labels, customs, tracking, pickups, scan forms, batches, insurance, claims, reports, webhooks, and the carrier-specific peculiarities that cause most real-world bugs.

It is Node.js-first and defaults to the official

@easypost/api

SDK, but field names and endpoint shapes are the same across languages. When the SDK can't do something, drop to

client.makeApiCall()

or raw HTTPS against the documented REST endpoint.

Source of truth, in this order:

Content of this skill (battle-tested patterns, carrier gotchas).
Official docs: https://docs.easypost.com/
SDK source: https://github.com/easypost/easypost-node

If this skill and the docs disagree about behavior, trust the docs and update the skill afterward.

How to use this skill

This skill is deliberately split into focused reference files. Don't load everything — load only the topics you need for the task at hand. Each file is short enough to digest in a single read and ends with pointers to adjacent topics.

Start by identifying the task, then read the matching file(s). If the task touches multiple areas (e.g., "international shipment with insurance"), read each area's file.

Routing table

For ecommerce integrations, start with

references/ecommerce-flows.md

— it walks the cart → checkout → fulfillment → delivery → returns lifecycle and points at the per-concept files.

If the task is about…	Read
End-to-end ecommerce flow (cart, checkout, fulfillment, returns, notifications)	`references/ecommerce-flows.md`
What EasyPost does NOT do (duties, tax, autocomplete, cutoffs, etc.)	`references/scope-boundaries.md`
Installing the SDK, configuring the client, TypeScript types, test vs. production keys	`references/setup-and-client.md`
SDK helper methods ( `getLowestRate` , `validateWebhook` , `getLowestSmartRate` )	`references/utils.md`
Finding current service levels, predefined packages, supported options at runtime	`references/discovery.md`
Creating a shipment, picking a rate, buying a label, downloading the label	`references/shipments.md`
Address validation, international address quirks	`references/addresses.md`
Parcel dimensions, weight, predefined packages	`references/parcels.md`
Choosing the cheapest/fastest rate, SmartRate, Luma rulesets	`references/rates-and-smartrate.md`
International shipping, customs forms, EEI, incoterms, tax IDs	`references/international.md`
Real-time tracking, tracker statuses, tracking URLs, bulk retrieve	`references/tracking.md`
Webhook setup, HMAC verification, event payloads	`references/webhooks.md`
Return labels, refunding postage	`references/returns-refunds.md`
Bulk label purchase (batches)	`references/batches.md`
End-of-day scan forms / manifests	`references/scan-forms.md`
Scheduling carrier pickups	`references/pickups.md`
Buying insurance, filing claims	`references/insurance-claims.md`
CSV reports (shipment, invoice, cash flow, etc.)	`references/reports.md`
Adding/managing carrier accounts, credentials, metadata	`references/carrier-accounts.md`
Commercial invoice, QR codes, packing slips	`references/forms.md`
Error classes, retries, idempotency, rate limits	`references/errors-and-retries.md`
Listing resources, cursor pagination	`references/pagination.md`
Test API keys, test tracking codes, sandbox behavior	`references/testing.md`
API keys, users, child accounts, billing	`references/api-keys-users.md`
Multi-parcel Orders, EndShippers (resellers/DAP)	`references/orders-endshippers.md`
USPS specifics (flat rate, HazMat, domestic vs. international)	`references/carriers/usps.md`
UPS specifics (weight limits, OAuth, predefined packages)	`references/carriers/ups.md`
UPS Digital Access Program (DAP) rules	`references/carriers/ups-dap.md`
FedEx specifics (BYOCA, SmartPost, Express One Rate, lithium batteries)	`references/carriers/fedex.md`
DHL Express (international only)	`references/carriers/dhl-express.md`
DHL eCommerce (C2C/B2C only, placeholder rates)	`references/carriers/dhl-ecommerce.md`
ePost Global (USPS first mile + international)	`references/carriers/epost-global.md`

Runnable examples

scripts/

contains minimal, runnable Node.js examples that you can copy wholesale as starting points:

```
scripts/create-shipment.mjs
```
— address → parcel → shipment → buy lowest rate → save label PDF

scripts/verify-address.mjs

— address verification with

createAndVerify

```
scripts/international-shipment.mjs
```
— customs info + items + shipment with tax identifier
```
scripts/track-shipment.mjs
```
— create tracker, poll status

scripts/webhook-handler.mjs

— Express endpoint using

client.Utils.validateWebhook

```
scripts/batch-buy.mjs
```
— create batch, add shipments, purchase, generate combined label
```
scripts/schedule-pickup.mjs
```
— create pickup, buy cheapest pickup rate
```
scripts/smartrate-deliver-by.mjs
```
— pick cheapest rate meeting a delivery deadline

Cardinal rules

These apply everywhere and save most of the common footguns:

Always use a test API key during development. Production keys cost real money on every label purchase. Test keys start with
```
test_
```
(or
```
EZTK
```
), production with
```
EZAK
```
.
```
references/testing.md
```
has the full rundown.
Inspect
shipment.messages
whenever
rates
is shorter than expected. Carriers that failed to rate return a message (carrier name + reason) instead of a rate. Silently missing rates is usually a missing field or wrong credential.
For international shipments, customs info is required, not optional. Build
```
CustomsInfo
```
with accurate HS tariff numbers, set
```
customs_certify = true
```
, and set
```
customs_signer
```
. See
```
references/international.md
```
.
Do not trust
lowestRate()
blindly for international or time-critical shipments. Use SmartRate or Luma when delivery guarantees matter (
```
references/rates-and-smartrate.md
```
).
Verify webhook HMAC signatures with
client.Utils.validateWebhook()
. See
```
references/webhooks.md
```
for the exact pattern.
Rates and services differ between test and production. Negotiated discounts only surface in production. Don't use test-mode rates in your analytics.
Phone number and company name reduce address-correction fees on FedEx and UPS. Always pass them when you have them.
Label URLs expire.
```
postage_label.label_url
```
is a signed URL with a TTL. Download the PDF/PNG to your own storage immediately after purchase.
end_shipper_id
is required for UPS DAP and some reseller/partner accounts. If you get a rating error mentioning "end shipper," create an
```
EndShipper
```
and pass its ID at purchase.

Carrier-specific fields belong in
options
, not at the top level. E.g.,

options.hazmat

,

options.aes_itn

,

options.incoterm

,

options.delivery_confirmation

,

options.label_format

.

Skill-wide conventions for generated code

When you write EasyPost code for the user, follow these conventions unless the user says otherwise:

Use the SDK (
```
@easypost/api
```
) before raw HTTP. Fall back to
```
client.makeApiCall()
```
only for endpoints the SDK doesn't cover.
In TypeScript, import entity and parameter types from
```
@easypost/api
```
(
```
IShipment
```
,
```
IShipmentCreateParameters
```
, etc.).
Never hardcode an API key — read from
```
process.env.EASYPOST_API_KEY
```
.
Always wrap purchase calls (
```
Shipment.buy
```
,
```
Batch.buy
```
,
```
Pickup.buy
```
,
```
Insurance.create
```
) in try/catch. These are the calls that cost money.
Log the full
```
shipment.messages
```
array when a shipment has fewer rates than expected.
When downloading a label, fetch
```
postage_label.label_url
```
and persist the bytes — don't store just the URL.
When retrying a failed purchase, avoid double-purchasing: look up the shipment first and check whether
```
postage_label
```
is already populated.

Prefer

client.Utils

helpers (

getLowestRate

,

getLowestSmartRate

,

validateWebhook

) over rolling your own.

Writing style when teaching the user

When the user is learning EasyPost (e.g., "how do I...?"), prefer showing a minimal runnable snippet over listing every field. Link to the specific reference file for the exhaustive field list. The PDF-style field dump is in the reference files; the top of SKILL.md and scripts are for "the five lines you actually need."