Agent Skills: EasyPost Knowledge Patch

EasyPost Knowledge Patch

Use this skill when implementing or reviewing EasyPost integrations involving addresses, trackers, shipments, labels, rating, carrier accounts, webhooks, or SDK and API compatibility.

Reference index

| Reference | Topics | | --- | --- | | addresses.md | Address verification triggers, carrier verification, existing-address verification, and line normalization | | tracking.md | Tracker states, scan details, identity, carrier strings, test data, lookup, deletion, and batch creation | | shipments-and-rating.md | Shipment creation and purchase, labels, listing, claims, rate adjustments, international rating, and carrier options | | platform-and-sdks.md | SDK compatibility, generic requests, webhooks, throttling, carrier accounts, groups, sessions, and subscriptions |

Critical compatibility changes

Address verification is presence-based

On POST /v2/addresses, including either verify or verify_strict triggers delivery and ZIP verification even if the key's value is false. Omit both keys when verification is not wanted.

verify returns the Address with per-check results. verify_strict takes precedence and returns an error when the address is unverified; correctable addresses are corrected and returned.

{
  "address": {
    "street1": "417 Montgomery St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US"
  },
  "verify_strict": true
}

Shipment creation is immutable

POST /v2/shipments creates an immutable Shipment. Supply all inputs up front. Valid to_address, from_address, and parcel values automatically populate rates.

Addresses and parcels may be existing IDs or inline objects. customs_info is required for international destinations, including US territories. If return_address is omitted, it defaults to from_address. carrier_accounts limits rating, but any invalid or disabled supplied account causes an error.

V2 shipment validation rejects missing or zero-valued parcel details.

{
  "shipment": {
    "to_address": {"id": "adr_..."},
    "from_address": {"id": "adr_..."},
    "parcel": {"id": "prcl_..."},
    "carrier_accounts": ["ca_..."]
  }
}

Node.js SDK behavior changed

The Node.js SDK:

• Uses fetch instead of superagent.
• Drops Node 16 support.
• Renames superagentMiddleware to httpMiddleware.
• Renames fetchClient to httpClient.
• Returns API resources as plain JSON-compatible objects rather than model-class instances.

Index endpoints are rate-limited

Index endpoints have request-per-second rate limiting. Integrations that enumerate resources must tolerate throttling instead of assuming unrestricted pagination.

Shipment references are not unique

GET /v2/shipments/:id accepts either an EasyPost Shipment ID or a caller-supplied reference. Reference uniqueness is not enforced, so use the generated ID for reliable retrieval.

Common operations

Use carrier-grade address verification

Set verify_carrier to ups or fedex alongside verify or verify_strict. This uses the selected carrier's Address Verification Service instead of standard EasyPost verification. The response verifications object includes a verify_carrier key naming the service used.

{"verify": true, "verify_carrier": "fedex"}

Verify an existing Address

An existing Address is immutable. Verify it with GET /v2/addresses/:id/verify. The response wraps the normalized replacement in address.

The replacement's verifications.zip4 and verifications.delivery entries contain success, field errors, and details. Delivery details can include latitude, longitude, and an IANA time zone.

Buy a rated Shipment

Purchase with POST /v2/shipments/:id/buy and a rate.id. The response fills tracking_code and postage_label. Optional insurance must be a USD string. Labels default to PNG unless options.label_format requests another format.

{"rate": {"id": "rate_..."}, "insurance": "249.99"}

Use one-call shipment purchase

When the carrier service is already known, include both service and carrier_accounts in the POST /v2/shipments payload to collapse the normal create-then-buy flow.

{
  "shipment": {
    "to_address": {"id": "adr_..."},
    "from_address": {"id": "adr_..."},
    "parcel": {"id": "prcl_..."},
    "service": "NextDayAir",
    "carrier_accounts": ["ca_..."]
  }
}

Convert a purchased label

Use GET /v2/shipments/:id/label?file_format=ZPL to convert a purchased Shipment label to PDF, ZPL, or EPL2. The original label must be PNG. Conversion works best from a 4x6 PNG to ZPL.

Create and identify Trackers

For POST /v2/trackers, omitting carrier invokes auto-detection. Ambiguous codes can match multiple carriers, explicit selection is faster, and some carriers require carrier-specific credentials for third-party tracking.

Trackers are immutable. When the same user creates the same tracking_code and carrier within three months, EasyPost returns the original Tracker instead of a duplicate.

The carrier field uses an API tracking string, which may differ from the display name. See tracking.md for non-obvious mappings.

Query Trackers correctly

Use GET /v2/trackers with the plural tracking_codes array, optionally narrowed by carrier, to find Trackers by code. GET /v2/trackers/:id accepts only a Tracker ID.

The list defaults to one month ago through the end of the current day. With only one datetime bound, it uses a one-month span around that bound. Supply an explicit start_datetime for older matches. page_size defaults to 20 and has a maximum of 100.

Delete Trackers with care

DELETE /v2/trackers/:id permanently removes the Tracker, stops all future webhook Event deliveries for it, and makes later retrieval return 404 Not Found.

{"success": true}

Use generic SDK requests when needed

The C#, Java, Node.js, PHP, and Ruby SDKs expose a generic request interface for arbitrary API endpoints, including endpoints without typed resource wrappers.

Additional routing

• For status values, event fields, deterministic test codes, and carrier API strings, read tracking.md.
• For request-only claim data, shipment-list cursor rules, rating systems, insurance, and carrier-specific delivery behavior, read shipments-and-rating.md.
• For webhook events, account lifecycle, groups, JWT sessions, and subscriptions, read platform-and-sdks.md.