EasyPost

EasyPost

This connector works with one EasyPost account through the EasyPost API v2 (https://api.easypost.com/v2): addresses with verification, parcels, shipments with live rates from your carriers, buying and refunding labels, label formats, insurance, tracking, customs declarations, batches and scan forms.

Setup (about 3 minutes)

1. Sign up at https://app.easypost.com/signup (free). EasyPost asks you to set up the wallet and a ship-from address before it shows keys, and a new account may first have to fill in a short security check with its business details; the keys appear once EasyPost has accepted it.
2. Open https://app.easypost.com/account/settings?tab=api-keys. Copy the Test key (free, labels are void) or the Production key (buys real labels).
3. Paste it into EASYPOST_API_KEY and install. easypost_list_addresses checks the key.

Test or production: the key decides, and every object carries mode. With a test key labels cost nothing and are void, trackers only accept the test codes EZ1000000001 (pre_transit) to EZ4000000004 (delivered), EZ5000000005 (return_to_sender), EZ6000000006 (failure) and EZ7000000007 (unknown). Carrier accounts can only be listed with a production key.

Buying costs money: confirm first. With a production key easypost_buy_shipment and easypost_insure_shipment charge the EasyPost wallet at once. State carrier, service, price and both addresses and wait for the user's yes. easypost_refund_shipment voids the label (it must not be used afterwards); the refund takes days to weeks.

Typical flow

1. easypost_create_shipment with to_address, from_address and parcel (each {"id": "..."} of a saved object, or the full object) returns rates[] with id, carrier, service, rate and delivery_days.
2. Pick a rate with the user, then easypost_buy_shipment with the shipment id and the rate id. The answer has postage_label.label_url (PNG; easypost_convert_label gives PDF or ZPL), tracking_code and tracker.public_url.
3. Follow the parcel with easypost_get_tracker (the tracker comes with the bought shipment) or start tracking any code with easypost_create_tracker.

Addresses: send verify true to easypost_create_address to check an address (a failed check still saves it, with verifications.delivery.success false and suggestions), or use easypost_create_and_verify_address to save only verified addresses. Saved addresses cannot be changed; create a new one. easypost_verify_address returns the checked address, which may have its own id: ship to the id in that answer.

Units: weight in ounces and dimensions in inches (1 kg = 35.27 oz, 1 cm = 0.394 in). Money as decimal strings in USD unless a currency is given. Countries are ISO 2 codes.

International: create customs items (easypost_create_customs_item), then easypost_create_customs_info with their ids, contents_type and customs_signer with customs_certify true, and pass its id as customs_info when creating the shipment.

Lists return the newest first with has_more; for the next page pass the last id as before_id. Shipments, trackers and scan forms cover the last month unless start_datetime is set, and shipment lists show only bought shipments unless purchased is false. A list on a fresh account may come back without its array.

Common errors (error.code)

• 401 UNAUTHORIZED or 403 APIKEY.INACTIVE: missing, wrong or disabled key.
• 403 MODE.UNAUTHORIZED: the call needs a production key (carrier accounts).
• 402 PAYMENT_REQUIRED: the wallet has no funds.
• 422 ADDRESS.VERIFY.FAILURE, SHIPMENT.POSTAGE.FAILURE, SHIPMENT.CUSTOMS_INFO.REQUIRED: error.errors[] names the problem.
• 429: rate limited (lists allow about 5 a second); wait and retry.

Out of scope here: pickups, orders, returns, webhooks, users and API keys, reports and connecting carrier accounts.