A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The EasyPost API is how an app or AI agent works with a shipping account: comparing carrier rates, buying and printing a label, verifying an address, and tracking a parcel. Access is granted through an API key, either a test key that moves no money or a production key for live operations, and there are no per-endpoint scopes, so the key itself is the boundary. A state change, like a tracker advancing, emits an Event that EasyPost can deliver to a registered endpoint.
How an app or AI agent connects to EasyPost determines what it can reach. There is a route for making calls, authenticated by an API key, and a route for receiving events, where EasyPost posts updates to a registered endpoint. The key it uses, test or production, sets what the agent can do.
The REST API takes JSON request bodies, returns JSON, and pages through lists with before_id and after_id cursors, under the v2 path at https://api.easypost.com/v2. A call authenticates with an API key sent through HTTP Basic auth, with the key as the username and a blank password. A separate test key operates on simulated data so no money moves.
EasyPost POSTs Event objects to an HTTPS endpoint registered through the Webhooks API or the Dashboard. When a webhook_secret is set, EasyPost signs each delivery and sends the signature in the X-Hmac-Signature header, so the receiver can verify it with the validate_webhook helper and reject anything that does not match. An endpoint must return a 2XX status to acknowledge receipt.
A production key operates on live data and moves real money when buying labels, pickups, or insurance. It is sent through HTTP Basic auth as the username, with a blank password, over TLS 1.2 or later. EasyPost has no granular per-endpoint scopes, so a production key can call every endpoint the account has access to. A compromised key can be disabled immediately in the Dashboard.
A test key operates on simulated data so an integration can be built and exercised without spending money or printing real postage. It authenticates the same way as a production key, as the HTTP Basic username with a blank password. Some account-management operations, like creating carrier accounts, require a production key.
The EasyPost API is split into areas an agent can act on, like shipments, rates, trackers, addresses, and customs. Each area has its own methods, and writes in some areas spend money, like buying a label or a pickup.
Methods for creating shipments, comparing rates, and buying, refunding, and insuring labels.
Methods for retrieving and regenerating shipping rates.
Methods for tracking parcels by tracking code.
Methods for creating and verifying addresses.
Methods for describing the package being shipped.
Methods for the customs information attached to international shipments.
Methods for standalone insurance on parcels not shipped through EasyPost.
Methods for buying and manifesting many shipments at once.
Methods for scheduling a carrier to collect parcels.
Methods for the carrier credentials an account ships through.
Methods for reading events and managing webhook endpoints.
Methods for bulk-refunding purchased postage.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
ShipmentsMethods for creating shipments, comparing rates, and buying, refunding, and insuring labels.7 | ||||||
| POST | /v2/shipments | Create a Shipment from a to_address, from_address, and parcel, which auto-populates available rates. | write | Production key | Current | |
A Shipment is immutable once created. Creating one does not buy a label. A test key creates test shipments. Acts onshipment Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/shipments/:id | Retrieve a Shipment by id. | read | Production key | Current | |
Read-only. Acts onshipment Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/shipments | List Shipments on the account, paginated. | read | Production key | Current | |
A list endpoint, subject to the 5 requests-per-second index limit. Acts onshipment Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limit5 requests/second (index endpoints) SourceOfficial documentation ↗ | ||||||
| POST | /v2/shipments/:id/buy | Buy a Shipment by selecting a rate, which purchases postage and returns the label. | write | Production key | Current | |
Spends real money. Governed by the load-based limiter that protects buying and rating. Acts onshipment Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/shipments/:id/refund | Request a refund for a single purchased Shipment label. | write | Production key | Current | |
Refund eligibility and timing depend on the carrier. Acts onshipment Permission (capability) Production keyVersionAvailable since the API’s base version Webhook event refund.successfulRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/shipments/:id/insure | Add insurance to a purchased Shipment by declaring an amount. | write | Production key | Current | |
Spends money. Insure at buy time or with this endpoint after buying. Acts onshipment Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/shipments/:id/label | Convert a purchased label to another format, like PDF, ZPL, or EPL2. | read | Production key | Current | |
Works on shipments that already have a label; conversion works best from a 4x6 PNG. Acts onshipment Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
RatesMethods for retrieving and regenerating shipping rates.2 | ||||||
| POST | /beta/rates | Retrieve Rates for a to_address, from_address, and parcel without creating a Shipment. | read | Production key | Current | |
A beta endpoint for comparing rates; it does not buy anything. Acts onrate Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/shipments/:id/rerate | Regenerate the Rates of an existing Shipment for the most up-to-date pricing. | write | Production key | Current | |
Useful when a shipment is bought on a different day than it was created. Acts onshipment Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TrackersMethods for tracking parcels by tracking code.4 | ||||||
| POST | /v2/trackers | Create a Tracker for a tracking_code, optionally with a carrier, to follow a parcel. | write | Production key | Current | |
If carrier is omitted, EasyPost attempts to auto-detect it. Updates arrive by webhook. Acts ontracker Permission (capability) Production keyVersionAvailable since the API’s base version Webhook event tracker.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/trackers/:id | Retrieve a Tracker by id. | read | Production key | Current | |
Read-only. Acts ontracker Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/trackers | List Trackers on the account, paginated and filterable. | read | Production key | Current | |
A list endpoint, subject to the 5 requests-per-second index limit. Acts ontracker Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limit5 requests/second (index endpoints) SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/trackers/:id | Delete a Tracker, which stops all future webhook updates for it. | write | Production key | Current | |
Stops webhook Event deliveries associated with the Tracker. Acts ontracker Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AddressesMethods for creating and verifying addresses.4 | ||||||
| POST | /v2/addresses | Create an Address representing a person, place, or organization. | write | Production key | Current | |
Verification can be requested at creation time with a verify parameter. Acts onaddress Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/addresses/create_and_verify | Create an Address and verify it in one call, returning corrected and residential details. | write | Production key | Current | |
Verification returns deliverability and residential flags used in rate calculation. Acts onaddress Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/addresses/:id/verify | Verify an existing Address to detect deliverability issues and correct minor errors. | read | Production key | Current | |
Returns corrected data and whether the address is residential. Acts onaddress Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/addresses | List Addresses on the account, paginated. | read | Production key | Current | |
A list endpoint, subject to the 5 requests-per-second index limit. Acts onaddress Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limit5 requests/second (index endpoints) SourceOfficial documentation ↗ | ||||||
ParcelsMethods for describing the package being shipped.1 | ||||||
| POST | /v2/parcels | Create a Parcel describing weight and optional dimensions or a predefined package. | write | Production key | Current | |
A Parcel is immutable once created; weight is required. Acts onparcel Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CustomsMethods for the customs information attached to international shipments.2 | ||||||
| POST | /v2/customs_infos | Create CustomsInfo, the customs declaration attached to an international Shipment. | write | Production key | Current | |
Carries CustomsItems describing the goods; immutable once created. Acts oncustoms_info Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/customs_items | Create a CustomsItem describing a single product in an international shipment. | write | Production key | Current | |
A CustomsItem is immutable once created. Acts oncustoms_item Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
InsuranceMethods for standalone insurance on parcels not shipped through EasyPost.2 | ||||||
| POST | /v2/insurances | Create standalone Insurance for a parcel not shipped through EasyPost. | write | Production key | Current | |
Spends money. For EasyPost shipments, insure via the shipment instead. Acts oninsurance Permission (capability) Production keyVersionAvailable since the API’s base version Webhook event insurance.purchasedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/insurances/:id/refund | Refund standalone Insurance purchased through EasyPost. | write | Production key | Current | |
Only for standalone insurance; tracking status must be pre_transit, cancelled, or unknown. Acts oninsurance Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BatchesMethods for buying and manifesting many shipments at once.4 | ||||||
| POST | /v2/batches | Create a Batch to group many shipments for bulk buying and manifesting. | write | Production key | Current | |
Creating a batch does not buy labels. Acts onbatch Permission (capability) Production keyVersionAvailable since the API’s base version Webhook event batch.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/batches/:id/buy | Buy every Shipment in a Batch, purchasing all their labels at once. | write | Production key | Current | |
Spends real money across the whole batch. Acts onbatch Permission (capability) Production keyVersionAvailable since the API’s base version Webhook event batch.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/batches/:id/label | Generate a single combined label file for all bought shipments in a Batch. | write | Production key | Current | |
Runs after the batch is bought. Acts onbatch Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/batches/:id/scan_form | Create a ScanForm (manifest) for the shipments in a Batch. | write | Production key | Current | |
A scan form lets a carrier scan one barcode for the whole batch. Acts onbatch Permission (capability) Production keyVersionAvailable since the API’s base version Webhook event scan_form.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PickupsMethods for scheduling a carrier to collect parcels.3 | ||||||
| POST | /v2/pickups | Create a Pickup request for a carrier to collect parcels. | write | Production key | Current | |
Creating a pickup does not book it; a Pickup is immutable once created. Acts onpickup Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/pickups/:id/buy | Buy a Pickup by selecting a rate, booking the carrier collection. | write | Production key | Current | |
Books and may pay for a real carrier collection. Acts onpickup Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/pickups/:id/cancel | Cancel a booked Pickup. | write | Production key | Current | |
Cancellation rules depend on the carrier. Acts onpickup Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Carrier AccountsMethods for the carrier credentials an account ships through.4 | ||||||
| POST | /v2/carrier_accounts | Create a CarrierAccount holding the credentials for a carrier the account ships through. | write | Production key | Current | |
Requires a production key. Adds carrier credentials used for rating and buying. Acts oncarrier_account Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/carrier_accounts | List the CarrierAccounts configured on the account. | read | Production key | Current | |
Requires a production key. Acts oncarrier_account Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/carrier_accounts/:id | Update a CarrierAccount's credentials or settings. | write | Production key | Current | |
The id may be the carrier_account id (ca_...) or its reference value. Acts oncarrier_account Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/carrier_accounts/:id | Delete a CarrierAccount. | write | Production key | Current | |
Removes the carrier credentials from the account. Acts oncarrier_account Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Events & WebhooksMethods for reading events and managing webhook endpoints.4 | ||||||
| GET | /v2/events | List Events on the account, the record of things that happened. | read | Production key | Current | |
A list endpoint, subject to the 5 requests-per-second index limit. Acts onevent Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limit5 requests/second (index endpoints) SourceOfficial documentation ↗ | ||||||
| POST | /v2/webhooks | Create a Webhook endpoint EasyPost posts Events to. | write | Production key | Current | |
Set a webhook_secret so receivers can verify the X-Hmac-Signature header. Acts onwebhook Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/webhooks/:id | Update or re-enable a Webhook endpoint. | write | Production key | Current | |
Used to re-enable a webhook that was disabled after repeated delivery failures. Acts onwebhook Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/webhooks/:id | Delete a Webhook endpoint so EasyPost stops sending Events to it. | write | Production key | Current | |
Stops all future deliveries to that endpoint. Acts onwebhook Permission (capability) Production keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
RefundsMethods for bulk-refunding purchased postage.1 | ||||||
| POST | /v2/refunds | Bulk-request Refunds for multiple purchased labels by carrier and tracking codes. | write | Production key | Current | |
For a single shipment, use the shipment refund endpoint instead. Acts onrefund Permission (capability) Production keyVersionAvailable since the API’s base version Webhook event refund.successfulRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
EasyPost can notify an app when something happens on an account, like a tracker advancing to a new status or a batch finishing. It posts an Event describing what changed, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
tracker.created | A Tracker was created and is now following a parcel. | /v2/trackers |
tracker.updated | A Tracker advanced to a new status or recorded a new tracking detail, like out for delivery or delivered. | /v2/trackers |
batch.created | A Batch was created. | /v2/batches |
batch.updated | A Batch changed state, for example as its shipments finish buying. | /v2/batches/:id/buy |
scan_form.created | A ScanForm (manifest) was created for a batch of shipments. | /v2/batches/:id/scan_form |
insurance.purchased | Standalone Insurance was purchased. | /v2/insurances |
refund.successful | A requested Refund was approved by the carrier and completed. | /v2/shipments/:id/refund/v2/refunds |
EasyPost limits how fast an app can call. A load-based limiter protects buying and rating, and a fixed limit of five requests per second applies to list endpoints, with going over returning an error.
EasyPost uses a dual-layer rate-limiting strategy. A load-based limiter dynamically protects overall capacity for high-priority operations, like buying and rating, rather than enforcing a fixed number. A separate fixed limit of five requests per second applies to list (index) endpoints, like listing shipments or trackers. Going over returns HTTP 429 Too Many Requests, which should be handled with exponential backoff. A separate constraint caps a single rating request at 60 carrier accounts, and only the first 60 are used if more are supplied.
List endpoints are cursor-based, paged with before_id and after_id parameters and a page_size parameter that sets how many records come back. The response indicates whether more pages remain. Listing endpoints are the ones subject to the five-requests-per-second index limit.
A single rating request uses at most 60 carrier accounts; any beyond that are ignored rather than failing the request. Label conversion works best on 4x6 labels converted from a PNG to ZPL or another format.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | UNAUTHORIZED | Authentication is required and failed, usually a missing or wrong API key. | Send a valid key as the HTTP Basic username, and confirm test versus production mode. |
| 402 | PAYMENT_REQUIRED | Billing information is missing or there are insufficient funds to complete the request. | Add a payment method or top up the balance before buying labels, pickups, or insurance. |
| 403 | FORBIDDEN | The request was valid but the server refused it, for example using a test key where a production key is required. | Use a production key for account-management calls, and confirm the account has access. |
| 404 | NOT_FOUND | The requested resource could not be found. | Check the object id, and confirm it belongs to the same mode and account. |
| 422 | UNPROCESSABLE_ENTITY | The request was well-formed but the data could not be processed, like a failed address verification (ADDRESS.VERIFY.FAILURE). | Read the errors array for the field, message, and suggestion, fix the input, and resend. |
| 429 | TOO_MANY_REQUESTS | Too many requests arrived too quickly, for example over five per second on a list endpoint. | Slow down and retry with exponential backoff and jitter. |
| 500 | INTERNAL_SERVER_ERROR | An unexpected error occurred on EasyPost's side. A 503 means the service is temporarily unavailable. | Retry with backoff, and contact EasyPost support if it persists. |
EasyPost serves a single stable API under the v2 path and ships dated platform releases on top of it, mostly carrier updates and additive features rather than breaking changes.
EasyPost serves a single stable API under the v2 path rather than pinning a dated version per account. Dated platform releases ship on top, mostly carrier integrations and additive features, published in the releases feed.
New carrier integrations and rate-shopping controls.
Returns workflows and timestamp standardization.
FedEx SmartPost REST support.
The v2 API is stable; track the dated releases for carrier and feature changes.
EasyPost releases ↗Bollard AI sits between a team's AI agents and EasyPost. Grant each agent exactly the access it needs, read or write, action by action, and every call is checked and logged.