Easypost Knowledge Patch

---
name: easypost-knowledge-patch
description: EasyPost
version: null
license: MIT
metadata:
  author: Nevaberry
---


# EasyPost Knowledge Patch

## Use this patch

Load this skill before implementing or reviewing EasyPost address verification,
tracking, shipment purchase, label handling, carrier-account operations, or SDK
upgrades.

Before changing an integration:

1. Identify whether each resource is being created, retrieved, verified,
   purchased, converted, listed, or deleted.
2. Preserve presence-based request semantics: for address verification, sending
   a key with `false` is not the same as omitting it.
3. Supply every required input before creating an immutable Address, Tracker, or
   Shipment.
4. Distinguish EasyPost IDs from caller references and carrier display names
   from API carrier strings.
5. Account for default date windows, maximum page sizes, and rate limits on
   index endpoints.
6. For SDK changes, identify the language, runtime, middleware hooks, HTTP
   client hooks, and whether callers depend on model-class instances.

## Reference index

| Reference | Topics |
| --- | --- |
| [addresses.md](references/addresses.md) | Creation-time verification, carrier verification, existing Addresses, normalization |
| [trackers.md](references/trackers.md) | Tracker creation, statuses, scan data, lookup, test codes, deletion |
| [shipments-labels-and-rates.md](references/shipments-labels-and-rates.md) | Shipment creation and purchase, labels, claims, rate adjustments, international and carrier rules |
| [accounts-events-and-subscriptions.md](references/accounts-events-and-subscriptions.md) | Carrier accounts, groups, webhooks, JWT sessions, subscriptions |
| [sdk-and-api.md](references/sdk-and-api.md) | Node.js SDK migration, generic requests, timestamps, index throttling |

## Critical request-semantics guardrails

- On `POST /v2/addresses`, the presence of `verify` or `verify_strict` triggers
  delivery and ZIP verification even if its value is `false`. Omit both keys to
  avoid verification.
- `verify_strict` takes precedence over `verify` and errors for an unverified
  address; a correctable address is corrected and returned.
- `POST /v2/shipments` creates an immutable Shipment. Provide all creation and
  rating inputs up front.
- Shipment `line_items` are request-only: they support carrier-claim automation,
  are not passed to the carrier, and are not returned in the response.
- `GET /v2/shipments/:id` accepts an ID or caller-supplied `reference`, but
  references are not unique. Use the generated ID for reliable retrieval.
- `GET /v2/trackers/:id` accepts only a Tracker ID. Code-based lookup belongs on
  `GET /v2/trackers` with the plural `tracking_codes` array.
- Trackers are immutable. Deleting one permanently removes it, stops future
  webhook Event deliveries, and makes later retrieval return `404 Not Found`.

## Address verification quick reference

Choose creation-time verification behavior deliberately:

| Request shape | Behavior |
| --- | --- |
| Neither verification key present | Do not verify |
| `verify` present | Return the Address with per-check results |
| `verify_strict` present | Error if unverified; correct and return if correctable |
| Verification key plus `verify_carrier: "ups"` or `"fedex"` | Use that carrier's Address Verification Service |

Carrier verification reports the service used in
`verifications.verify_carrier`. To verify an immutable existing Address, call
`GET /v2/addresses/:id/verify`; the normalized replacement is wrapped in
`address`.

For US and Canadian addresses, verification can move a recognized trailing
unit from `street1` to an empty `street2` when `street1` exceeds 35 characters.
Street-name abbreviation occurs only for USPS verification and only when the
validated `street1` exceeds 40 characters.

See [addresses.md](references/addresses.md) for verification result fields and
examples.

## Shipment creation and purchase quick reference

- Creating a Shipment with valid `to_address`, `from_address`, and `parcel`
  automatically populates `rates`; each value may be an existing ID or an
  inline object.
- International destinations, including US territories, require
  `customs_info`.
- If omitted, `return_address` defaults to `from_address`.
- `carrier_accounts` limits rating. Any invalid or disabled supplied account
  causes an error.
- Buy a selected rate with `POST /v2/shipments/:id/buy` and a `rate.id`. The
  response fills `tracking_code` and `postage_label`.
- Optional purchase `insurance` is a USD string. Labels default to PNG unless
  `options.label_format` requests another format.
- When the carrier service is known, include both `service` and
  `carrier_accounts` in `POST /v2/shipments` for one-call purchase.
- V2 shipment validation rejects missing or zero-valued parcel details.

Label conversion through
`GET /v2/shipments/:id/label?file_format=ZPL` supports `PDF`, `ZPL`, and `EPL2`,
but requires an original PNG label. Conversion works best from a 4x6 PNG to
ZPL.

See [shipments-labels-and-rates.md](references/shipments-labels-and-rates.md)
for line-item requirements, list behavior, rate rules, claims, and carrier
options.

## Tracker quick reference

- Omitting `carrier` from `POST /v2/trackers` invokes auto-detection. Ambiguous
  codes can match multiple carriers, and explicit carrier selection is faster.
- Some carriers require carrier-specific credentials for third-party tracking.
- Creating the same `tracking_code` and `carrier` for the same user within three
  months returns the original Tracker rather than a duplicate.
- Current status values are `unknown`, `pre_transit`, `in_transit`,
  `out_for_delivery`, `delivered`, `available_for_pickup`,
  `return_to_sender`, `failure`, `cancelled`, and `error`.
- Historical scans are in `tracking_details`. Their timestamps use a local zone
  inferred from a sufficiently complete `tracking_location`; otherwise they use
  UTC.
- `POST /v2/trackers/batch` accepts up to 100 tracking codes.

Tracker lists default to one month ago through the current day's end. A single
datetime bound creates a one-month span around that bound; older matches need an
explicit `start_datetime`. `page_size` defaults to 20 and caps at 100.

The API `carrier` value is not always the display name. Preserve exact strings
such as `ColumbusLastMile`, `DhlEcs`, `LaserShipV2`, `PassportGlobal`,
`TforceConcise`, and `UspsShip`.

See [trackers.md](references/trackers.md) for status detail, carrier detail,
test-mode codes, and deletion behavior.

## SDK and API migration guardrails

For the Node.js SDK:

- Use a supported runtime; Node 16 support was dropped.
- Replace `superagentMiddleware` with `httpMiddleware`.
- Replace `fetchClient` with `httpClient`.
- Account for the SDK using `fetch` instead of `superagent`.
- Treat returned API resources as plain JSON-compatible objects, not model-class
  instances.

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

Index endpoints have request-per-second rate limiting. Integrations that
enumerate resources must tolerate throttling rather than assume unrestricted
pagination.

See [sdk-and-api.md](references/sdk-and-api.md) for the consolidated migration
surface.

## Account, event, and subscription quick reference

- Carrier-account APIs cover registration, platform-account types and
  configuration, and team-authorized status updates. Platform account
  availability exposes access and setup options.
- BYOCA support extends to all users, and most carrier accounts no longer need a
  separate manual registration step.
- Groups support subgroup creation, viewing, listing, and deletion, plus
  sub-account assignment. Sub-account lists can include group information.
- `shipment.invoice.updated` reports billed-shipment disputes.
- `payment.created` and `payment.failed` are emitted again for bank and
  credit-card charges.
- Embeddable components and customer portals can create JWT-authenticated
  sessions.
- SAML invitations accept `return_to_url` for the post-acceptance destination.
- Advanced Tracking subscriptions can be canceled, and their brand
  customization can be synchronized.
- A subscription plan can be charged immediately when it is created.

See [accounts-events-and-subscriptions.md](references/accounts-events-and-subscriptions.md)
for the complete platform-operation details.

## Integration review checklist

- Test omission separately from `false` for address verification keys.
- Keep immutable-resource creation payloads complete.
- Store generated Shipment and Tracker IDs where deterministic retrieval is
  required.
- Use plural `tracking_codes` only on the Tracker list endpoint.
- Request older list data with explicit datetime bounds and respect page-size
  caps.
- Preserve carrier API strings exactly.
- Accept ISO 8601 timestamps and the documented tracker status set.
- Handle throttling while enumerating index endpoints.
- Recheck Node.js middleware, HTTP client, runtime, and returned-object
  assumptions during SDK upgrades.
- Apply carrier-specific delivery, customs, claim, and label rules before
  purchase.