What we do
Tools
Industries
Department
How we workLet's talk →
Home/EasyPost/EasyPost API
EasyPost

The EasyPost API: Which Calls, in Which Order, With Which Key

You can get a test label out of the EasyPost API in an afternoon. The sequence is short: check the address, create a shipment, pick one of the rates it returns, buy it, and listen for tracker events. What takes longer is the week after you swap in the production key, when real carrier rates, real webhooks and real addresses arrive.

The EasyPost API in four lines

Two keys. The test key is free and its labels aren't real postage. The production key buys real labels and is the one that shows your negotiated carrier rates. Both sit on the API Keys page of your EasyPost dashboard.

A shipment is a rate quote. Send a to address, a from address and a parcel, and the response lists a rate from each carrier account you can use.

Buying a rate makes the label. You get back the label file and a tracking code, and a tracker starts following the parcel.

Webhooks bring the news. Status changes arrive as Events posted to your endpoint, signed with your webhook secret.

From test key to a label you can ship

  1. 1

    Start on the test key

    Build the whole flow against test mode first. Nothing is charged, and every object EasyPost returns carries a mode field, so your logs can show which environment produced it.

    Watch for: the production key ending up in a developer's local config. Keep each key in its own environment variable and never in the repository.

  2. 2

    Verify the address before anything else

    Create the destination as an address object with verification switched on. EasyPost checks it and sends back a corrected version where it can, such as a fixed ZIP code or a standardised street.

    Watch for: saving the address the customer typed instead of the corrected one. Store what came back, and show the customer the change when it matters.

  3. 3

    Create the shipment and read its rates

    Post the to and from addresses with a parcel. Weight goes in ounces, and international parcels need customs info as well. The response has a rates list, one entry per carrier service.

    Watch for: the messages list. When a carrier can't rate the parcel, the reason goes there instead of failing the call, so a missing UPS rate can go unnoticed.

  4. 4

    Pick a rate by your rule, then buy it

    Cheapest, fastest within a delivery promise, or a preferred carrier unless it's much dearer: apply the same rule in code every time, then buy that rate. Pass carrier_accounts if a shipment should only be rated on certain accounts.

  5. 5

    Register a webhook and check its signature

    Point a webhook at your endpoint and give it a webhook_secret. Each event then arrives with an X-Hmac-Signature header, and the client libraries have a helper that validates it. Reject anything that doesn't match.

    Watch for: slow responses. Answer with a 200 straight away and do the real work after, because an endpoint that keeps failing can be switched off.

A store plugin, or calls to the API yourself

Shopify and WooCommerce stores can get EasyPost labels through apps and plugins from EasyPost and its partners. Whether that's enough depends on what has to happen around the label.

Plugin

Labels for store orders

  • Install, connect your EasyPost account, print labels from the order screen.
  • Rates follow the plugin's own settings, not your business rules.
  • Fine for one store with simple shipping.
API

Labels inside your own system

  • Orders from several channels, a warehouse system or a custom app.
  • Your rate rule, address checks and packaging logic, applied the same way every time.
  • Tracker events written back to the order and to whoever handles exceptions.

If staff copy order details from one screen to another to print a label, the plugin has stopped being enough.

Your first week on the production key

None of these show up in test mode, which is why they catch teams that shipped straight from the quickstart.

Rates jump when you go live

How you'll know: Prices on the production key don't match what you tested with, and free-shipping thresholds or margins you set are now wrong.

Fix: Your negotiated carrier rates only come back in production. Run a handful of real parcel profiles on the production key before launch and set shipping prices from those numbers.

Tracking updates simply stop

How you'll know: Orders sit at "label printed" for days, and the webhook list in EasyPost shows the endpoint as disabled.

Fix: Your endpoint returned errors or timed out often enough to be switched off. Re-enable it through the webhook update call, then put a queue behind the endpoint so it acknowledges first and processes later.

The same event is handled twice

How you'll know: A customer gets two "delivered" emails, or a return is logged twice in the ERP.

Fix: Record each event's ID when you process it and skip IDs you've already seen. Webhooks should be treated as delivered at least once, not exactly once.

Checkout waits on every carrier

How you'll know: Shoppers stare at a spinner while rates come back from four or five carrier accounts.

Fix: Rate only the carriers your rule can actually choose, cache rates for identical carts and addresses for a short window, and show a fixed fallback rate if the call runs past your time limit.

Unused labels quietly cost money

How you'll know: Orders cancelled after the label was bought still show postage charges on the EasyPost bill.

Fix: Request a refund on the shipment when an order is cancelled, and watch its refund_status until it says refunded or rejected.

After the label

The tracking side of EasyPost, what each status means and how events get matched back to orders, is on our EasyPost tracking page. If you're still choosing a label API, Shippo's API is the closest alternative, and ShipStation suits teams that want a screen to work from instead of code.

n-frames builds production EasyPost integrations for stores, 3PLs and marketplaces: address checks before every shipment, a rate rule that answers inside checkout, webhooks behind a queue, and refunds requested on cancelled orders. Freight moving by sea or air as well? See Flexport's API.

Questions people ask

Where do I find my EasyPost API key?

On the API Keys page of your EasyPost dashboard. You'll see a test key and a production key. Calls that manage keys themselves only work with the production key, and a lot of first-week bugs come from the test key being used where the production one should be, or the other way round.

Where are the EasyPost API docs?

At docs.easypost.com. They cover addresses, shipments, rates, trackers, webhooks, carrier accounts and API keys, with code samples for EasyPost's client libraries in several languages.

Does EasyPost have a status page?

Yes. It reports the API and individual carrier connections, so check it first when rates from one carrier vanish, before you start digging through your own code.

Does EasyPost integrate with Shopify or WooCommerce?

Yes, through apps and plugins from EasyPost and its partners, which cover buying and printing labels for store orders. Custom rate rules, address checks at checkout, several sales channels or tracker events written back to the order usually mean building against the API.

What does EasyPost's address verification actually check?

Whether the address is deliverable as written, and what the corrected version is: a missing unit number, a wrong ZIP code, a street that doesn't exist. It's most useful at checkout or order entry, so a bad address is caught while the customer is still there to fix it.

Can I test EasyPost tracking without shipping anything?

Yes. In test mode EasyPost provides test tracking codes such as EZ1000000001, and a tracker created from one sends a test event, so you can exercise your webhook handling before a real parcel moves.

Who builds a production EasyPost integration?

Usually your own developers, or an agency like n-frames when they're busy elsewhere. We take it from a working test call to production: rate rules, address checks, a webhook queue, refunds and the monitoring that shows when a carrier stops returning rates.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.