Overview Flow Guide

The shipment lifecycle

Steps 2 and 3 can be a single call: create the shipment with buy_label: true and the label comes back in the same response.

Before you start

Credentials

Data you need for each shipment

Choose your integration path

Step by step

1. Get rates

   Compare every courier available for the parcel. Each rate has a courier_service.id, a total_charge, delivery days and ranking fields. Full details: How to Get Shipping Rates.

   cURLPOST /2024-09/rates

   curl -X POST https://public-api.easyship.com/2024-09/rates \ -H "Authorization: Bearer $EASYSHIP_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "origin_address": { "line_1": "1 Market St", "city": "San Francisco", "state": "CA", "postal_code": "94105", "country_alpha2": "US" }, "destination_address": { "line_1": "10 Downing Street", "city": "London", "postal_code": "SW1A 2AA", "country_alpha2": "GB" }, "incoterms": "DDU", "parcels": [{ "total_actual_weight": 1.2, "box": { "length": 30, "width": 20, "height": 10 }, "items": [{ "description": "T-shirt", "category": "fashion", "hs_code": "61091000", "quantity": 2, "declared_currency": "USD", "declared_customs_value": 25 }] }] }'

   Pick a rate and keep its courier_service.id.

   Optional. If you skip this step, POST /shipments still returns all rates and assigns the best-value courier.
2. Create the shipment

   Send the same addresses and parcels, plus the chosen courier in courier_settings. Add contact details (contact_name, contact_phone, contact_email) to both addresses; couriers need them on the label.

   cURLPOST /2024-09/shipments

   curl -X POST https://public-api.easyship.com/2024-09/shipments \ -H "Authorization: Bearer $EASYSHIP_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: order-1001" \ -d '{ "origin_address": { "...": "as in step 1, plus contact details" }, "destination_address": { "...": "as in step 1, plus contact details" }, "incoterms": "DDU", "courier_settings": { "courier_service_id": "01563646-58c1-4607-8fe0-cae3e33c0001", "allow_fallback": false }, "shipping_settings": { "buy_label": false }, "parcels": [{ "...": "as in step 1" }] }'

   Response201 Created

   { "shipment": { "easyship_shipment_id": "ESUS10006002", "shipment_state": "created", "label_state": "not_created", "courier_service": { "id": "01563646-58c1-4607-8fe0-cae3e33c0001", "name": "DHL Express Worldwide" }, "rates": [ ... ], "tracking_page_url": "https://www.trackmyshipment.co/shipment-tracking/ESUS10006002" } }

   Option	Effect
   courier_settings.allow_fallback	If the chosen courier can't be used, let Easyship pick another instead of failing
   courier_settings.apply_shipping_rules	Apply the shipping rules set up on your account
   shipping_settings.buy_label	Buy the label in the same call (skips step 3)
   shipping_settings.buy_label_synchronous	With buy_label: wait and return the label in the response. Not available for batches
   Idempotency-Key header	Retry safely: a repeated request with the same key returns the first successful response instead of creating a second shipment

   To change the shipment before buying the label, use Update a Shipment.

3. Buy the label

   This books the courier, charges your balance and returns the label and other shipping documents. You can pass courier_service_id here to set or change the courier; if none is set, Easyship assigns the best-value courier.

   cURLPOST /2024-09/shipments/ESUS10006002/label

   curl -X POST https://public-api.easyship.com/2024-09/shipments/ESUS10006002/label \ -H "Authorization: Bearer $EASYSHIP_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "courier_service_id": "01563646-58c1-4607-8fe0-cae3e33c0001" }'

   Response201 Created

   { "shipment": { "easyship_shipment_id": "ESUS10006002", "label_state": "generated", "label_paid_at": "2026-10-15T10:21:00Z", "shipping_documents": [ { "category": "label", "format": "pdf", "page_size": "4x6", "base64_encoded_strings": ["JVBERi0xLjUK..."] } ], "trackings": [ ... ] } }

   Decode base64_encoded_strings to get the file, or fetch it later with GET /shipments/{id}/documents. Need a different format or page size? Pass printing_options.

   Buying the label commits the shipment. From here the courier is booked. To stop it, use Cancel a Shipment.
4. Hand the parcel to the courier

   Drop it off, or book a collection with POST /pickups if the courier offers pickups. Send the courier_service_id, a selected_date, a time window (or a time_slot_id) and the shipment IDs.

   cURLPOST /2024-09/pickups

   curl -X POST https://public-api.easyship.com/2024-09/pickups \ -H "Authorization: Bearer $EASYSHIP_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "courier_service_id": "01563646-58c1-4607-8fe0-cae3e33c0001", "selected_date": "2026-10-16", "selected_from_time": "12:00", "selected_to_time": "16:00", "easyship_shipment_ids": ["ESUS10006002"] }'
5. Track the shipment

   Tracking starts automatically once the label exists. Subscribe to the tracking webhooks below, or look it up:

   cURLGET /2024-09/shipments/trackings

   curl "https://public-api.easyship.com/2024-09/shipments/trackings?easyship_shipment_id=ESUS10006002&include_checkpoints=true" \ -H "Authorization: Bearer $EASYSHIP_TOKEN"

   You can also share tracking_page_url with your buyer. Full details: How to Track a Shipment.

Webhooks to subscribe to

Create a webhook with the Webhooks API and list these names in event_types. In each delivery, the payload's event_type uses the dotted form shown under each name.

Shipment states

Every shipment response carries four state fields. These are the values you'll see most:

FAQ and common errors

Related