Looking for the old docs? View our old docs site.
API Docs

Shipment

The workhorse of the EasyPost API, a Shipment is made up of a "to" and "from" Address, the Parcel being shipped, and any Forms required for international deliveries. Once created, a Shipment object is used to retrieve shipping Rates and purchase a label.

A Shipment created with a valid to_address, from_address, and parcel will automatically populate its rates attribute.

Endpoints
POST
/shipments
POST
/shipments/:id/buy
GET
/shipments
GET
/shipments/:id
GET
/shipments/:id/label

Shipment object

id
string
Unique, begins with "shp_"
object
string
"Shipment"
reference
string
An optional field that may be used in place of id in other API endpoints
mode
string
"test" or "production"
to_address
The destination address
from_address
The origin address
return_address
The shipper's address, defaults to from_address
More attributes
buyer_address
The buyer's address, defaults to to_address
parcel
The dimensions and weight of the package
customs_info
Information for the processing of customs
scan_form
Document created to manifest and scan multiple shipments
forms
Form array
All associated Form objects
insurance
string
The associated insurance amount
rates
Rate array
All associated Rate objects
selected_rate
The specific rate purchased for the shipment, or null if unpurchased or purchased through another mechanism
postage_label
The associated PostageLabel object
messages
Message array
Any carrier errors encountered during rating. Discussed in more depth below.
options
All of the options passed to the shipment, discussed in more depth below
is_return
boolean
Set true to create as a return. Discussed in more depth below.
tracking_code
string
If purchased, the tracking code will appear here as well as within the Tracker object.
usps_zone
integer
The USPS zone of the shipment, if purchased with USPS
status
string
The current status of the shipment. Possible values:
  • "unknown"
  • "pre_transit"
  • "in_transit"
  • "out_for_delivery"
  • "delivered"
  • "available_for_pickup"
  • "return_to_sender"
  • "failure"
  • "cancelled"
  • "error"
tracker
The associated Tracker object
fees
Fee array
The associated Fee objects charged to the billing user account
refund_status
string
The current status of the shipment refund process. Possible values:
  • "submitted"
  • "refunded"
  • "rejected"
batch_id
string
The ID of the Batch that contains this shipment, if any
batch_status
string
The current status of the associated BatchShipment
batch_message
string
The current message of the associated BatchShipment
created_at
datetime
When the Shipment was created
updated_at
datetime
When the Shipment was last updated
Shipment Object
{
  "created_at": "2024-01-24T00:07:30Z",
  "is_return": false,
  "messages": [],
  "mode": "test",
  "options": {
    "currency": "USD",
    "payment": {
      "type": "SENDER"
    },
    "date_advance": 0
  },
  "reference": null,
  "status": "unknown",
  "tracking_code": null,
  "updated_at": "2024-01-24T00:07:30Z",
  "batch_id": null,
  "batch_status": null,
  "batch_message": null,
  "customs_info": {
    "id": "cstinfo_657b430669ef456584bc4b82b3271084",
    "object": "CustomsInfo",
    "created_at": "2024-01-24T00:07:30Z",
    "updated_at": "2024-01-24T00:07:30Z",
    "contents_explanation": "",
    "contents_type": "merchandise",
    "customs_certify": true,
    "customs_signer": "Steve Brule",
    "eel_pfc": "NOEEI 30.37(a)",
    "non_delivery_option": "return",
    "restriction_comments": null,
    "restriction_type": "none",
    "mode": "test",
    "declaration": null,
    "customs_items": [
      {
        "id": "cstitem_046758e6b61847f99623c4d2290a26bd",
        "object": "CustomsItem",
        "created_at": "2024-01-24T00:07:30Z",
        "updated_at": "2024-01-24T00:07:30Z",
        "description": "T-shirt",
        "hs_tariff_number": "123456",
        "origin_country": "US",
        "quantity": 1,
        "value": "10.0",
        "weight": 5,
        "code": "123",
        "mode": "test",
        "manufacturer": null,
        "currency": null,
        "eccn": null,
        "printed_commodity_identifier": null
      }
    ]
  },
  "from_address": {
    "id": "adr_90e0406bba4c11eea7d53cecef1b359e",
    "object": "Address",
    "created_at": "2024-01-24T00:07:30+00:00",
    "updated_at": "2024-01-24T00:07:30+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "insurance": null,
  "order_id": null,
  "parcel": {
    "id": "prcl_4dde100b45af43acbe9c68244fa51851",
    "object": "Parcel",
    "created_at": "2024-01-24T00:07:30Z",
    "updated_at": "2024-01-24T00:07:30Z",
    "length": 20.2,
    "width": 10.9,
    "height": 5,
    "predefined_package": null,
    "weight": 65.9,
    "mode": "test"
  },
  "postage_label": null,
  "rates": [
    {
      "id": "rate_3cbb8d9c4ea1477588a17b0ee3e0c5b4",
      "object": "Rate",
      "created_at": "2024-01-24T00:07:30Z",
      "updated_at": "2024-01-24T00:07:30Z",
      "mode": "test",
      "service": "Express",
      "carrier": "USPS",
      "rate": "49.60",
      "currency": "USD",
      "retail_rate": "57.40",
      "retail_currency": "USD",
      "list_rate": "49.60",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": null,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": null,
      "shipment_id": "shp_93170d48eb1a413aa5c0d8bf4384a350",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
    },
    {
      "id": "rate_c9e1a6c4be1e40a7af83b42d1115c550",
      "object": "Rate",
      "created_at": "2024-01-24T00:07:30Z",
      "updated_at": "2024-01-24T00:07:30Z",
      "mode": "test",
      "service": "Priority",
      "carrier": "USPS",
      "rate": "7.33",
      "currency": "USD",
      "retail_rate": "15.20",
      "retail_currency": "USD",
      "list_rate": "10.89",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 2,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 2,
      "shipment_id": "shp_93170d48eb1a413aa5c0d8bf4384a350",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
    },
    {
      "id": "rate_a39910cfd937402fb77a9eaed223dcfe",
      "object": "Rate",
      "created_at": "2024-01-24T00:07:30Z",
      "updated_at": "2024-01-24T00:07:30Z",
      "mode": "test",
      "service": "GroundAdvantage",
      "carrier": "USPS",
      "rate": "6.79",
      "currency": "USD",
      "retail_rate": "13.15",
      "retail_currency": "USD",
      "list_rate": "9.41",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 3,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 3,
      "shipment_id": "shp_93170d48eb1a413aa5c0d8bf4384a350",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
    },
    {
      "id": "rate_d0b494c33c3e42f893b619d730f24058",
      "object": "Rate",
      "created_at": "2024-01-24T00:07:30Z",
      "updated_at": "2024-01-24T00:07:30Z",
      "mode": "test",
      "service": "First",
      "carrier": "USPS",
      "rate": "6.79",
      "currency": "USD",
      "retail_rate": "13.15",
      "retail_currency": "USD",
      "list_rate": "9.41",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 3,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 3,
      "shipment_id": "shp_93170d48eb1a413aa5c0d8bf4384a350",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
    },
    {
      "id": "rate_dad1a54ef6f64dfc9def001cbbb2b142",
      "object": "Rate",
      "created_at": "2024-01-24T00:07:30Z",
      "updated_at": "2024-01-24T00:07:30Z",
      "mode": "test",
      "service": "ParcelSelect",
      "carrier": "USPS",
      "rate": "6.79",
      "currency": "USD",
      "retail_rate": "13.15",
      "retail_currency": "USD",
      "list_rate": "9.41",
      "list_currency": "USD",
      "billing_type": "easypost",
      "delivery_days": 3,
      "delivery_date": null,
      "delivery_date_guaranteed": false,
      "est_delivery_days": 3,
      "shipment_id": "shp_93170d48eb1a413aa5c0d8bf4384a350",
      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
    }
  ],
  "refund_status": null,
  "scan_form": null,
  "selected_rate": null,
  "tracker": null,
  "to_address": {
    "id": "adr_90dd5fb4ba4c11ee9e88ac1f6bc539ae",
    "object": "Address",
    "created_at": "2024-01-24T00:07:30+00:00",
    "updated_at": "2024-01-24T00:07:30+00:00",
    "name": "Dr. Steve Brule",
    "company": null,
    "street1": "179 N Harbor Dr",
    "street2": null,
    "city": "Redondo Beach",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "8573875756",
    "email": "dr_steve_brule@gmail.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "usps_zone": 4,
  "return_address": {
    "id": "adr_90e0406bba4c11eea7d53cecef1b359e",
    "object": "Address",
    "created_at": "2024-01-24T00:07:30+00:00",
    "updated_at": "2024-01-24T00:07:30+00:00",
    "name": "EasyPost",
    "company": null,
    "street1": "417 Montgomery Street",
    "street2": "5th Floor",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94104",
    "country": "US",
    "phone": "4153334445",
    "email": "support@easypost.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "buyer_address": {
    "id": "adr_90dd5fb4ba4c11ee9e88ac1f6bc539ae",
    "object": "Address",
    "created_at": "2024-01-24T00:07:30+00:00",
    "updated_at": "2024-01-24T00:07:30+00:00",
    "name": "Dr. Steve Brule",
    "company": null,
    "street1": "179 N Harbor Dr",
    "street2": null,
    "city": "Redondo Beach",
    "state": "CA",
    "zip": "90277",
    "country": "US",
    "phone": "8573875756",
    "email": "dr_steve_brule@gmail.com",
    "mode": "test",
    "carrier_facility": null,
    "residential": null,
    "federal_tax_id": null,
    "state_tax_id": null,
    "verifications": {}
  },
  "forms": [],
  "fees": [],
  "id": "shp_93170d48eb1a413aa5c0d8bf4384a350",
  "object": "Shipment"
}

Postage Label object

id
string
Unique, begins with "pl_"
object
string
"PostageLabel"
label_date
datetime
The date that appears on the postage label
label_epl2_url
string
The URL of the EPL2 label file
label_file_type
string
File type of the label
label_pdf_url
string
The URL of the PDF label file
label_resolution
integer
The resolution of the label
label_size
string
The size of the label
More attributes
label_type
string
The type of the label
label_url
string
The URL of the label file
label_zpl_url
string
The URL of the ZPL label file
created_at
datetime
When the PostageLabel was created
updated_at
datetime
When the PostageLabel was last updated
Postage Label Object
{
  "object": "PostageLabel",
  "id": "pl_e5d4aec4ee23458ebcb4d29c41ee75f4",
  "created_at": "2024-01-24T00:07:36Z",
  "updated_at": "2024-01-24T00:07:38Z",
  "date_advance": 0,
  "integrated_form": "none",
  "label_date": "2024-01-24T00:07:36Z",
  "label_resolution": 300,
  "label_size": "4x6",
  "label_type": "default",
  "label_file_type": "image/png",
  "label_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/20240124/e8118119c07a5e44a2aee0f6189f13f80a.png",
  "label_pdf_url": null,
  "label_zpl_url": "https://easypost-files.s3-us-west-2.amazonaws.com/files/postage_label/20240124/af790a0077514f32b1d035d8b2795bb0.zpl",
  "label_epl2_url": null,
  "label_file": null
}

Create a Shipment

A Shipment is almost exclusively a container for other objects, and thus a Shipment may reuse many of these objects. Additionally, all the objects contained within a Shipment may be created at the same time.

The origin/destination Address and

Parcel are required for rating. CustomInfo is required to rate an international Shipment, this includes when the destination is a U.S. territory. The associated Tracker,Fee, and Rates are generated by EasyPost and cannot be modified by the user.

You can limit the CarrierAccounts to use for rating by passing the carrier_accounts parameter. If the CarrierAccount IDs provided are invalid or disabled, the shipment creation call will result in an error.

A Shipment object is immutable once created. All information must be provided during creation; it cannot be modified later.

Request Parameters

reference
OPTIONAL
i.e. "my-reference"
An optional field that may be used in place of id in other API endpoints
to_address
REQUIRED
i.e. Address
Can be specified by ID or attributes to create a new one, and be verified inline. See Create and Verify Address
from_address
REQUIRED
i.e. Address
Can be specified by ID or attributes to create a new one, and be verified inline. See Create and Verify Address
parcel
REQUIRED
i.e. Parcel
The dimensions and weight of the package
customs_info
OPTIONAL
Information for processing the package through international customs
carrier_accounts
OPTIONAL
i.e. ["ca_...", ...]
List of CarrierAccount IDs
POST /shipments
1curl -X POST https://api.easypost.com/v2/shipments \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "shipment": {
6      "to_address": {
7        "name": "Dr. Steve Brule",
8        "street1": "179 N Harbor Dr",
9        "city": "Redondo Beach",
10        "state": "CA",
11        "zip": "90277",
12        "country": "US",
13        "phone": "8573875756",
14        "email": "dr_steve_brule@gmail.com"
15      },
16      "from_address": {
17        "name": "EasyPost",
18        "street1": "417 Montgomery Street",
19        "street2": "5th Floor",
20        "city": "San Francisco",
21        "state": "CA",
22        "zip": "94104",
23        "country": "US",
24        "phone": "4153334445",
25        "email": "support@easypost.com"
26      },
27      "parcel": {
28        "length": "20.2",
29        "width": "10.9",
30        "height": "5",
31        "weight": "65.9"
32      },
33      "customs_info": {
34        "id": "cstinfo_..."
35      }
36    }
37  }'
Response
1{
2  "created_at": "2024-01-24T00:07:30Z",
3  "is_return": false,
4  "messages": [],
5  "mode": "test",
6  "options": {
7    "currency": "USD",
8    "payment": {
9      "type": "SENDER"
10    },
11    "date_advance": 0
12  },
13  "reference": null,
14  "status": "unknown",
15  "tracking_code": null,
16  "updated_at": "2024-01-24T00:07:30Z",
17  "batch_id": null,
18  "batch_status": null,
19  "batch_message": null,
20  "customs_info": {
21    "id": "cstinfo_657b430669ef456584bc4b82b3271084",
22    "object": "CustomsInfo",
23    "created_at": "2024-01-24T00:07:30Z",
24    "updated_at": "2024-01-24T00:07:30Z",
25    "contents_explanation": "",
26    "contents_type": "merchandise",
27    "customs_certify": true,
28    "customs_signer": "Steve Brule",
29    "eel_pfc": "NOEEI 30.37(a)",
30    "non_delivery_option": "return",
31    "restriction_comments": null,
32    "restriction_type": "none",
33    "mode": "test",
34    "declaration": null,
35    "customs_items": [
36      {
37        "id": "cstitem_046758e6b61847f99623c4d2290a26bd",
38        "object": "CustomsItem",
39        "created_at": "2024-01-24T00:07:30Z",
40        "updated_at": "2024-01-24T00:07:30Z",
41        "description": "T-shirt",
42        "hs_tariff_number": "123456",
43        "origin_country": "US",
44        "quantity": 1,
45        "value": "10.0",
46        "weight": 5.0,
47        "code": "123",
48        "mode": "test",
49        "manufacturer": null,
50        "currency": null,
51        "eccn": null,
52        "printed_commodity_identifier": null
53      }
54    ]
55  },
56  "from_address": {
57    "id": "adr_90e0406bba4c11eea7d53cecef1b359e",
58    "object": "Address",
59    "created_at": "2024-01-24T00:07:30+00:00",
60    "updated_at": "2024-01-24T00:07:30+00:00",
61    "name": "EasyPost",
62    "company": null,
63    "street1": "417 Montgomery Street",
64    "street2": "5th Floor",
65    "city": "San Francisco",
66    "state": "CA",
67    "zip": "94104",
68    "country": "US",
69    "phone": "4153334445",
70    "email": "support@easypost.com",
71    "mode": "test",
72    "carrier_facility": null,
73    "residential": null,
74    "federal_tax_id": null,
75    "state_tax_id": null,
76    "verifications": {}
77  },
78  "insurance": null,
79  "order_id": null,
80  "parcel": {
81    "id": "prcl_4dde100b45af43acbe9c68244fa51851",
82    "object": "Parcel",
83    "created_at": "2024-01-24T00:07:30Z",
84    "updated_at": "2024-01-24T00:07:30Z",
85    "length": 20.2,
86    "width": 10.9,
87    "height": 5.0,
88    "predefined_package": null,
89    "weight": 65.9,
90    "mode": "test"
91  },
92  "postage_label": null,
93  "rates": [
94    {
95      "id": "rate_3cbb8d9c4ea1477588a17b0ee3e0c5b4",
96      "object": "Rate",
97      "created_at": "2024-01-24T00:07:30Z",
98      "updated_at": "2024-01-24T00:07:30Z",
99      "mode": "test",
100      "service": "Express",
101      "carrier": "USPS",
102      "rate": "49.60",
103      "currency": "USD",
104      "retail_rate": "57.40",
105      "retail_currency": "USD",
106      "list_rate": "49.60",
107      "list_currency": "USD",
108      "billing_type": "easypost",
109      "delivery_days": null,
110      "delivery_date": null,
111      "delivery_date_guaranteed": false,
112      "est_delivery_days": null,
113      "shipment_id": "shp_93170d48eb1a413aa5c0d8bf4384a350",
114      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
115    },
116    {
117      "id": "rate_c9e1a6c4be1e40a7af83b42d1115c550",
118      "object": "Rate",
119      "created_at": "2024-01-24T00:07:30Z",
120      "updated_at": "2024-01-24T00:07:30Z",
121      "mode": "test",
122      "service": "Priority",
123      "carrier": "USPS",
124      "rate": "7.33",
125      "currency": "USD",
126      "retail_rate": "15.20",
127      "retail_currency": "USD",
128      "list_rate": "10.89",
129      "list_currency": "USD",
130      "billing_type": "easypost",
131      "delivery_days": 2,
132      "delivery_date": null,
133      "delivery_date_guaranteed": false,
134      "est_delivery_days": 2,
135      "shipment_id": "shp_93170d48eb1a413aa5c0d8bf4384a350",
136      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
137    },
138    {
139      "id": "rate_a39910cfd937402fb77a9eaed223dcfe",
140      "object": "Rate",
141      "created_at": "2024-01-24T00:07:30Z",
142      "updated_at": "2024-01-24T00:07:30Z",
143      "mode": "test",
144      "service": "GroundAdvantage",
145      "carrier": "USPS",
146      "rate": "6.79",
147      "currency": "USD",
148      "retail_rate": "13.15",
149      "retail_currency": "USD",
150      "list_rate": "9.41",
151      "list_currency": "USD",
152      "billing_type": "easypost",
153      "delivery_days": 3,
154      "delivery_date": null,
155      "delivery_date_guaranteed": false,
156      "est_delivery_days": 3,
157      "shipment_id": "shp_93170d48eb1a413aa5c0d8bf4384a350",
158      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
159    },
160    {
161      "id": "rate_d0b494c33c3e42f893b619d730f24058",
162      "object": "Rate",
163      "created_at": "2024-01-24T00:07:30Z",
164      "updated_at": "2024-01-24T00:07:30Z",
165      "mode": "test",
166      "service": "First",
167      "carrier": "USPS",
168      "rate": "6.79",
169      "currency": "USD",
170      "retail_rate": "13.15",
171      "retail_currency": "USD",
172      "list_rate": "9.41",
173      "list_currency": "USD",
174      "billing_type": "easypost",
175      "delivery_days": 3,
176      "delivery_date": null,
177      "delivery_date_guaranteed": false,
178      "est_delivery_days": 3,
179      "shipment_id": "shp_93170d48eb1a413aa5c0d8bf4384a350",
180      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
181    },
182    {
183      "id": "rate_dad1a54ef6f64dfc9def001cbbb2b142",
184      "object": "Rate",
185      "created_at": "2024-01-24T00:07:30Z",
186      "updated_at": "2024-01-24T00:07:30Z",
187      "mode": "test",
188      "service": "ParcelSelect",
189      "carrier": "USPS",
190      "rate": "6.79",
191      "currency": "USD",
192      "retail_rate": "13.15",
193      "retail_currency": "USD",
194      "list_rate": "9.41",
195      "list_currency": "USD",
196      "billing_type": "easypost",
197      "delivery_days": 3,
198      "delivery_date": null,
199      "delivery_date_guaranteed": false,
200      "est_delivery_days": 3,
201      "shipment_id": "shp_93170d48eb1a413aa5c0d8bf4384a350",
202      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
203    }
204  ],
205  "refund_status": null,
206  "scan_form": null,
207  "selected_rate": null,
208  "tracker": null,
209  "to_address": {
210    "id": "adr_90dd5fb4ba4c11ee9e88ac1f6bc539ae",
211    "object": "Address",
212    "created_at": "2024-01-24T00:07:30+00:00",
213    "updated_at": "2024-01-24T00:07:30+00:00",
214    "name": "Dr. Steve Brule",
215    "company": null,
216    "street1": "179 N Harbor Dr",
217    "street2": null,
218    "city": "Redondo Beach",
219    "state": "CA",
220    "zip": "90277",
221    "country": "US",
222    "phone": "8573875756",
223    "email": "dr_steve_brule@gmail.com",
224    "mode": "test",
225    "carrier_facility": null,
226    "residential": null,
227    "federal_tax_id": null,
228    "state_tax_id": null,
229    "verifications": {}
230  },
231  "usps_zone": 4,
232  "return_address": {
233    "id": "adr_90e0406bba4c11eea7d53cecef1b359e",
234    "object": "Address",
235    "created_at": "2024-01-24T00:07:30+00:00",
236    "updated_at": "2024-01-24T00:07:30+00:00",
237    "name": "EasyPost",
238    "company": null,
239    "street1": "417 Montgomery Street",
240    "street2": "5th Floor",
241    "city": "San Francisco",
242    "state": "CA",
243    "zip": "94104",
244    "country": "US",
245    "phone": "4153334445",
246    "email": "support@easypost.com",
247    "mode": "test",
248    "carrier_facility": null,
249    "residential": null,
250    "federal_tax_id": null,
251    "state_tax_id": null,
252    "verifications": {}
253  },
254  "buyer_address": {
255    "id": "adr_90dd5fb4ba4c11ee9e88ac1f6bc539ae",
256    "object": "Address",
257    "created_at": "2024-01-24T00:07:30+00:00",
258    "updated_at": "2024-01-24T00:07:30+00:00",
259    "name": "Dr. Steve Brule",
260    "company": null,
261    "street1": "179 N Harbor Dr",
262    "street2": null,
263    "city": "Redondo Beach",
264    "state": "CA",
265    "zip": "90277",
266    "country": "US",
267    "phone": "8573875756",
268    "email": "dr_steve_brule@gmail.com",
269    "mode": "test",
270    "carrier_facility": null,
271    "residential": null,
272    "federal_tax_id": null,
273    "state_tax_id": null,
274    "verifications": {}
275  },
276  "forms": [],
277  "fees": [],
278  "id": "shp_93170d48eb1a413aa5c0d8bf4384a350",
279  "object": "Shipment"
280}

Buy a Shipment

To purchase a Shipment you only need to specify the

Rate to purchase. This operation populates the tracking_code and postage_label attributes. The default image format of the associated PostageLabel is PNG. To change this default, see the label_format option.

Additionally, insurance may be added during the purchase. To specify an amount to insure, pass the insurance attribute as a string. The currency of all insurance is U.S. Dollars (USD).

Request Parameters

rate
i.e. Rate
insurance
i.e. "100.00"
POST /shipments/:id/buy
1curl -X POST https://api.easypost.com/v2/shipments/shp_.../buy \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "rate": {
6      "id": "rate_..."
7    },
8    "insurance": "249.99"
9  }'
Response
1{
2  "created_at": "2024-01-24T00:07:32Z",
3  "is_return": false,
4  "messages": [],
5  "mode": "test",
6  "options": {
7    "currency": "USD",
8    "payment": {
9      "type": "SENDER"
10    },
11    "date_advance": 0
12  },
13  "reference": null,
14  "status": "unknown",
15  "tracking_code": "9434600207552011812848",
16  "updated_at": "2024-01-24T00:07:33Z",
17  "batch_id": null,
18  "batch_status": null,
19  "batch_message": null,
20  "customs_info": {
21    "id": "cstinfo_fd42061296ef450285b451ef66f9b9d5",
22    "object": "CustomsInfo",
23    "created_at": "2024-01-24T00:07:32Z",
24    "updated_at": "2024-01-24T00:07:32Z",
25    "contents_explanation": "",
26    "contents_type": "merchandise",
27    "customs_certify": true,
28    "customs_signer": "Steve Brule",
29    "eel_pfc": "NOEEI 30.37(a)",
30    "non_delivery_option": "return",
31    "restriction_comments": null,
32    "restriction_type": "none",
33    "mode": "test",
34    "declaration": null,
35    "customs_items": [
36      {
37        "id": "cstitem_f7de527850e34f018ef41e9f69be6758",
38        "object": "CustomsItem",
39        "created_at": "2024-01-24T00:07:32Z",
40        "updated_at": "2024-01-24T00:07:32Z",
41        "description": "T-shirt",
42        "hs_tariff_number": "123456",
43        "origin_country": "US",
44        "quantity": 1,
45        "value": "10.0",
46        "weight": 5.0,
47        "code": "123",
48        "mode": "test",
49        "manufacturer": null,
50        "currency": null,
51        "eccn": null,
52        "printed_commodity_identifier": null
53      }
54    ]
55  },
56  "from_address": {
57    "id": "adr_91fa95f1ba4c11ee8c59ac1f6bc53342",
58    "object": "Address",
59    "created_at": "2024-01-24T00:07:32+00:00",
60    "updated_at": "2024-01-24T00:07:32+00:00",
61    "name": "EasyPost",
62    "company": null,
63    "street1": "417 Montgomery Street",
64    "street2": "5th Floor",
65    "city": "San Francisco",
66    "state": "CA",
67    "zip": "94104",
68    "country": "US",
69    "phone": "4153334445",
70    "email": "support@easypost.com",
71    "mode": "test",
72    "carrier_facility": null,
73    "residential": null,
74    "federal_tax_id": null,
75    "state_tax_id": null,
76    "verifications": {}
77  },
78  "insurance": "249.99",
79  "order_id": null,
80  "parcel": {
81    "id": "prcl_a5e317e47ac9442988d338cb2a0fde17",
82    "object": "Parcel",
83    "created_at": "2024-01-24T00:07:32Z",
84    "updated_at": "2024-01-24T00:07:32Z",
85    "length": 20.2,
86    "width": 10.9,
87    "height": 5.0,
88    "predefined_package": null,
89    "weight": 65.9,
90    "mode": "test"
91  },
92  "postage_label": {
93    "object": "PostageLabel",
94    "id": "pl_51b80cc8523d4fc28c4ab710594e0913",
95    "created_at": "2024-01-24T00:07:33Z",
96    "updated_at": "2024-01-24T00:07:33Z",
97    "date_advance": 0,
98    "integrated_form": "none",
99    "label_date": "2024-01-24T00:07:33Z",
100    "label_resolution": 300,
101    "label_size": "4x6",
102    "label_type": "default",
103    "label_file_type": "image/png",
104    "label_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/20240124/e81cecd85b82d749a19cf38dae0e30fc53.png",
105    "label_pdf_url": null,
106    "label_zpl_url": null,
107    "label_epl2_url": null,
108    "label_file": null
109  },
110  "rates": [
111    {
112      "id": "rate_6366c70cbea94c60b8d282ccf0f60ce0",
113      "object": "Rate",
114      "created_at": "2024-01-24T00:07:32Z",
115      "updated_at": "2024-01-24T00:07:32Z",
116      "mode": "test",
117      "service": "GroundAdvantage",
118      "carrier": "USPS",
119      "rate": "6.79",
120      "currency": "USD",
121      "retail_rate": "13.15",
122      "retail_currency": "USD",
123      "list_rate": "9.41",
124      "list_currency": "USD",
125      "billing_type": "easypost",
126      "delivery_days": 3,
127      "delivery_date": null,
128      "delivery_date_guaranteed": false,
129      "est_delivery_days": 3,
130      "shipment_id": "shp_56b10c708daa4c25b5895c5354758aaf",
131      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
132    },
133    {
134      "id": "rate_7dd1fb53702d473bbb9eeaf53d7a72d7",
135      "object": "Rate",
136      "created_at": "2024-01-24T00:07:32Z",
137      "updated_at": "2024-01-24T00:07:32Z",
138      "mode": "test",
139      "service": "First",
140      "carrier": "USPS",
141      "rate": "6.79",
142      "currency": "USD",
143      "retail_rate": "13.15",
144      "retail_currency": "USD",
145      "list_rate": "9.41",
146      "list_currency": "USD",
147      "billing_type": "easypost",
148      "delivery_days": 3,
149      "delivery_date": null,
150      "delivery_date_guaranteed": false,
151      "est_delivery_days": 3,
152      "shipment_id": "shp_56b10c708daa4c25b5895c5354758aaf",
153      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
154    },
155    {
156      "id": "rate_263930dcc1ef4331b9a16313f55c47d6",
157      "object": "Rate",
158      "created_at": "2024-01-24T00:07:32Z",
159      "updated_at": "2024-01-24T00:07:32Z",
160      "mode": "test",
161      "service": "ParcelSelect",
162      "carrier": "USPS",
163      "rate": "6.79",
164      "currency": "USD",
165      "retail_rate": "13.15",
166      "retail_currency": "USD",
167      "list_rate": "9.41",
168      "list_currency": "USD",
169      "billing_type": "easypost",
170      "delivery_days": 3,
171      "delivery_date": null,
172      "delivery_date_guaranteed": false,
173      "est_delivery_days": 3,
174      "shipment_id": "shp_56b10c708daa4c25b5895c5354758aaf",
175      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
176    },
177    {
178      "id": "rate_bd7a2aa312224b43b15d56b2e818e946",
179      "object": "Rate",
180      "created_at": "2024-01-24T00:07:32Z",
181      "updated_at": "2024-01-24T00:07:32Z",
182      "mode": "test",
183      "service": "Express",
184      "carrier": "USPS",
185      "rate": "49.60",
186      "currency": "USD",
187      "retail_rate": "57.40",
188      "retail_currency": "USD",
189      "list_rate": "49.60",
190      "list_currency": "USD",
191      "billing_type": "easypost",
192      "delivery_days": null,
193      "delivery_date": null,
194      "delivery_date_guaranteed": false,
195      "est_delivery_days": null,
196      "shipment_id": "shp_56b10c708daa4c25b5895c5354758aaf",
197      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
198    },
199    {
200      "id": "rate_6ec39e90cf6b4f2d97aab43d7c946559",
201      "object": "Rate",
202      "created_at": "2024-01-24T00:07:32Z",
203      "updated_at": "2024-01-24T00:07:32Z",
204      "mode": "test",
205      "service": "Priority",
206      "carrier": "USPS",
207      "rate": "7.33",
208      "currency": "USD",
209      "retail_rate": "15.20",
210      "retail_currency": "USD",
211      "list_rate": "10.89",
212      "list_currency": "USD",
213      "billing_type": "easypost",
214      "delivery_days": 2,
215      "delivery_date": null,
216      "delivery_date_guaranteed": false,
217      "est_delivery_days": 2,
218      "shipment_id": "shp_56b10c708daa4c25b5895c5354758aaf",
219      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
220    }
221  ],
222  "refund_status": null,
223  "scan_form": null,
224  "selected_rate": {
225    "id": "rate_6366c70cbea94c60b8d282ccf0f60ce0",
226    "object": "Rate",
227    "created_at": "2024-01-24T00:07:33Z",
228    "updated_at": "2024-01-24T00:07:33Z",
229    "mode": "test",
230    "service": "GroundAdvantage",
231    "carrier": "USPS",
232    "rate": "6.79",
233    "currency": "USD",
234    "retail_rate": "13.15",
235    "retail_currency": "USD",
236    "list_rate": "9.41",
237    "list_currency": "USD",
238    "billing_type": "easypost",
239    "delivery_days": 3,
240    "delivery_date": null,
241    "delivery_date_guaranteed": false,
242    "est_delivery_days": 3,
243    "shipment_id": "shp_56b10c708daa4c25b5895c5354758aaf",
244    "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
245  },
246  "tracker": {
247    "id": "trk_814a807c3fae4203a4d61293b2b0b3dc",
248    "object": "Tracker",
249    "mode": "test",
250    "tracking_code": "9434600207552011812848",
251    "status": "unknown",
252    "status_detail": "unknown",
253    "created_at": "2024-01-24T00:07:34Z",
254    "updated_at": "2024-01-24T00:07:34Z",
255    "signed_by": null,
256    "weight": null,
257    "est_delivery_date": null,
258    "shipment_id": "shp_56b10c708daa4c25b5895c5354758aaf",
259    "carrier": "USPS",
260    "tracking_details": [],
261    "fees": [],
262    "carrier_detail": null,
263    "public_url": "https://track.easypost.com/djE6dHJrXzgxNGE4MDdjM2ZhZTQyMDNhNGQ2MTI5M2IyYjBiM2Rj"
264  },
265  "to_address": {
266    "id": "adr_91f7ca0fba4c11eeb731ac1f6bc539aa",
267    "object": "Address",
268    "created_at": "2024-01-24T00:07:32+00:00",
269    "updated_at": "2024-01-24T00:07:33+00:00",
270    "name": "DR. STEVE BRULE",
271    "company": null,
272    "street1": "179 N HARBOR DR",
273    "street2": "",
274    "city": "REDONDO BEACH",
275    "state": "CA",
276    "zip": "90277-2506",
277    "country": "US",
278    "phone": "8573875756",
279    "email": "DR_STEVE_BRULE@GMAIL.COM",
280    "mode": "test",
281    "carrier_facility": null,
282    "residential": false,
283    "federal_tax_id": null,
284    "state_tax_id": null,
285    "verifications": {
286      "zip4": {
287        "success": true,
288        "errors": [],
289        "details": null
290      },
291      "delivery": {
292        "success": true,
293        "errors": [],
294        "details": {
295          "latitude": 33.8436,
296          "longitude": -118.39177,
297          "time_zone": "America/Los_Angeles"
298        }
299      }
300    }
301  },
302  "usps_zone": 4,
303  "return_address": {
304    "id": "adr_91fa95f1ba4c11ee8c59ac1f6bc53342",
305    "object": "Address",
306    "created_at": "2024-01-24T00:07:32+00:00",
307    "updated_at": "2024-01-24T00:07:32+00:00",
308    "name": "EasyPost",
309    "company": null,
310    "street1": "417 Montgomery Street",
311    "street2": "5th Floor",
312    "city": "San Francisco",
313    "state": "CA",
314    "zip": "94104",
315    "country": "US",
316    "phone": "4153334445",
317    "email": "support@easypost.com",
318    "mode": "test",
319    "carrier_facility": null,
320    "residential": null,
321    "federal_tax_id": null,
322    "state_tax_id": null,
323    "verifications": {}
324  },
325  "buyer_address": {
326    "id": "adr_91f7ca0fba4c11eeb731ac1f6bc539aa",
327    "object": "Address",
328    "created_at": "2024-01-24T00:07:32+00:00",
329    "updated_at": "2024-01-24T00:07:33+00:00",
330    "name": "DR. STEVE BRULE",
331    "company": null,
332    "street1": "179 N HARBOR DR",
333    "street2": "",
334    "city": "REDONDO BEACH",
335    "state": "CA",
336    "zip": "90277-2506",
337    "country": "US",
338    "phone": "8573875756",
339    "email": "DR_STEVE_BRULE@GMAIL.COM",
340    "mode": "test",
341    "carrier_facility": null,
342    "residential": false,
343    "federal_tax_id": null,
344    "state_tax_id": null,
345    "verifications": {
346      "zip4": {
347        "success": true,
348        "errors": [],
349        "details": null
350      },
351      "delivery": {
352        "success": true,
353        "errors": [],
354        "details": {
355          "latitude": 33.8436,
356          "longitude": -118.39177,
357          "time_zone": "America/Los_Angeles"
358        }
359      }
360    }
361  },
362  "forms": [],
363  "fees": [
364    {
365      "object": "Fee",
366      "type": "LabelFee",
367      "amount": "0.00000",
368      "charged": true,
369      "refunded": false
370    },
371    {
372      "object": "Fee",
373      "type": "PostageFee",
374      "amount": "6.79000",
375      "charged": true,
376      "refunded": false
377    },
378    {
379      "object": "Fee",
380      "type": "InsuranceFee",
381      "amount": "1.24995",
382      "charged": true,
383      "refunded": false
384    }
385  ],
386  "id": "shp_56b10c708daa4c25b5895c5354758aaf",
387  "object": "Shipment"
388}

Buy a Shipment without rating (One-Call Buy)

There is an alternative way to purchase shipments that is known as the "one-call buy" method. This method is often used if you have a flat-rate set with a mail carrier for a given service level or if you know your desired service level without needing to see the rate first.

Utilizing the "one-call buy" method can improve the performance of your integration, because it cuts out an API call from our standard "Create Shipment" then "Buy Shipment" workflow. In order to achieve this behavior, all you have to do is add a single CarrierAccount and service level name to your Create Shipment call.

Request Parameters

reference
i.e. "my-reference"
An optional field that may be used in place of id in other API endpoints
to_address
i.e. Address
Can be specified by ID or attributes to create a new one, and be verified inline. See Create and Verify Address
from_address
i.e. Address
Can be specified by ID or attributes to create a new one, and be verified inline. See Create and Verify Address
parcel
i.e. Parcel
carrier_accounts
i.e. ["ca_...", ...]
List of CarrierAccount IDs
service
i.e. "Priority"
The service of carrier
POST /shipments/:id/buy
1curl -X POST https://api.easypost.com/v2/shipments \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "shipment": {
6      "to_address": {
7        "name": "Dr. Steve Brule",
8        "street1": "179 N Harbor Dr",
9        "city": "Redondo Beach",
10        "state": "CA",
11        "zip": "90277",
12        "country": "US",
13        "phone": "8573875756",
14        "email": "dr_steve_brule@gmail.com"
15      },
16      "from_address": {
17        "name": "EasyPost",
18        "street1": "417 Montgomery Street",
19        "street2": "5th Floor",
20        "city": "San Francisco",
21        "state": "CA",
22        "zip": "94104",
23        "country": "US",
24        "phone": "4153334445",
25        "email": "support@easypost.com"
26      },
27      "parcel": {
28        "length": "20.2",
29        "width": "10.9",
30        "height": "5",
31        "weight": "65.9"
32      },
33      "service": "NextDayAir",
34      "carrier_accounts": ["ca_..."]
35    }
36  }'
Response
1{
2  "created_at": "2024-01-24T00:07:34Z",
3  "is_return": false,
4  "messages": [],
5  "mode": "test",
6  "options": {
7    "currency": "USD",
8    "payment": {
9      "type": "SENDER"
10    },
11    "date_advance": 0
12  },
13  "reference": null,
14  "status": "unknown",
15  "tracking_code": "9405500207552011812856",
16  "updated_at": "2024-01-24T00:07:35Z",
17  "batch_id": null,
18  "batch_status": null,
19  "batch_message": null,
20  "customs_info": {
21    "id": "cstinfo_e6014c4dcdf5453791e90ce9a1e02415",
22    "object": "CustomsInfo",
23    "created_at": "2024-01-24T00:07:34Z",
24    "updated_at": "2024-01-24T00:07:34Z",
25    "contents_explanation": "",
26    "contents_type": "merchandise",
27    "customs_certify": true,
28    "customs_signer": "Steve Brule",
29    "eel_pfc": "NOEEI 30.37(a)",
30    "non_delivery_option": "return",
31    "restriction_comments": null,
32    "restriction_type": "none",
33    "mode": "test",
34    "declaration": null,
35    "customs_items": [
36      {
37        "id": "cstitem_a3eccb0d4eea40919cd8ce3fb946f294",
38        "object": "CustomsItem",
39        "created_at": "2024-01-24T00:07:34Z",
40        "updated_at": "2024-01-24T00:07:34Z",
41        "description": "T-shirt",
42        "hs_tariff_number": "123456",
43        "origin_country": "US",
44        "quantity": 1,
45        "value": "10.0",
46        "weight": 5.0,
47        "code": "123",
48        "mode": "test",
49        "manufacturer": null,
50        "currency": null,
51        "eccn": null,
52        "printed_commodity_identifier": null
53      }
54    ]
55  },
56  "from_address": {
57    "id": "adr_931d01beba4c11eea85f3cecef1b359e",
58    "object": "Address",
59    "created_at": "2024-01-24T00:07:34+00:00",
60    "updated_at": "2024-01-24T00:07:34+00:00",
61    "name": "EasyPost",
62    "company": null,
63    "street1": "417 Montgomery Street",
64    "street2": "5th Floor",
65    "city": "San Francisco",
66    "state": "CA",
67    "zip": "94104",
68    "country": "US",
69    "phone": "4153334445",
70    "email": "support@easypost.com",
71    "mode": "test",
72    "carrier_facility": null,
73    "residential": null,
74    "federal_tax_id": null,
75    "state_tax_id": null,
76    "verifications": {}
77  },
78  "insurance": null,
79  "order_id": null,
80  "parcel": {
81    "id": "prcl_e41371b468254344b140e685e879d69b",
82    "object": "Parcel",
83    "created_at": "2024-01-24T00:07:34Z",
84    "updated_at": "2024-01-24T00:07:34Z",
85    "length": 20.2,
86    "width": 10.9,
87    "height": 5.0,
88    "predefined_package": null,
89    "weight": 65.9,
90    "mode": "test"
91  },
92  "postage_label": {
93    "object": "PostageLabel",
94    "id": "pl_737e9444077f4b00b11dd489f1ff1b24",
95    "created_at": "2024-01-24T00:07:34Z",
96    "updated_at": "2024-01-24T00:07:35Z",
97    "date_advance": 0,
98    "integrated_form": "none",
99    "label_date": "2024-01-24T00:07:34Z",
100    "label_resolution": 300,
101    "label_size": "4x6",
102    "label_type": "default",
103    "label_file_type": "image/png",
104    "label_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/20240124/e855deb38cef7e400083067c600a9848f2.png",
105    "label_pdf_url": null,
106    "label_zpl_url": null,
107    "label_epl2_url": null,
108    "label_file": null
109  },
110  "rates": [
111    {
112      "id": "rate_2c2df636028f414a9334c086be6d8a78",
113      "object": "Rate",
114      "created_at": "2024-01-24T00:07:34Z",
115      "updated_at": "2024-01-24T00:07:34Z",
116      "mode": "test",
117      "service": "Express",
118      "carrier": "USPS",
119      "rate": "49.60",
120      "currency": "USD",
121      "retail_rate": "57.40",
122      "retail_currency": "USD",
123      "list_rate": "49.60",
124      "list_currency": "USD",
125      "billing_type": "easypost",
126      "delivery_days": null,
127      "delivery_date": null,
128      "delivery_date_guaranteed": false,
129      "est_delivery_days": null,
130      "shipment_id": "shp_032866f1a5174949bc938acc7f4a19fc",
131      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
132    },
133    {
134      "id": "rate_55157308ac5e46ef88c45f726bcbc786",
135      "object": "Rate",
136      "created_at": "2024-01-24T00:07:34Z",
137      "updated_at": "2024-01-24T00:07:34Z",
138      "mode": "test",
139      "service": "Priority",
140      "carrier": "USPS",
141      "rate": "7.33",
142      "currency": "USD",
143      "retail_rate": "15.20",
144      "retail_currency": "USD",
145      "list_rate": "10.89",
146      "list_currency": "USD",
147      "billing_type": "easypost",
148      "delivery_days": 2,
149      "delivery_date": null,
150      "delivery_date_guaranteed": false,
151      "est_delivery_days": 2,
152      "shipment_id": "shp_032866f1a5174949bc938acc7f4a19fc",
153      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
154    },
155    {
156      "id": "rate_9f6994d9e21940288ae27be89a958e92",
157      "object": "Rate",
158      "created_at": "2024-01-24T00:07:34Z",
159      "updated_at": "2024-01-24T00:07:34Z",
160      "mode": "test",
161      "service": "GroundAdvantage",
162      "carrier": "USPS",
163      "rate": "6.79",
164      "currency": "USD",
165      "retail_rate": "13.15",
166      "retail_currency": "USD",
167      "list_rate": "9.41",
168      "list_currency": "USD",
169      "billing_type": "easypost",
170      "delivery_days": 3,
171      "delivery_date": null,
172      "delivery_date_guaranteed": false,
173      "est_delivery_days": 3,
174      "shipment_id": "shp_032866f1a5174949bc938acc7f4a19fc",
175      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
176    },
177    {
178      "id": "rate_75c2218b6bd149ec9b9145380024c633",
179      "object": "Rate",
180      "created_at": "2024-01-24T00:07:34Z",
181      "updated_at": "2024-01-24T00:07:34Z",
182      "mode": "test",
183      "service": "First",
184      "carrier": "USPS",
185      "rate": "6.79",
186      "currency": "USD",
187      "retail_rate": "13.15",
188      "retail_currency": "USD",
189      "list_rate": "9.41",
190      "list_currency": "USD",
191      "billing_type": "easypost",
192      "delivery_days": 3,
193      "delivery_date": null,
194      "delivery_date_guaranteed": false,
195      "est_delivery_days": 3,
196      "shipment_id": "shp_032866f1a5174949bc938acc7f4a19fc",
197      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
198    },
199    {
200      "id": "rate_c8fd8ed2574c4c1aa5d751e344786157",
201      "object": "Rate",
202      "created_at": "2024-01-24T00:07:34Z",
203      "updated_at": "2024-01-24T00:07:34Z",
204      "mode": "test",
205      "service": "ParcelSelect",
206      "carrier": "USPS",
207      "rate": "6.79",
208      "currency": "USD",
209      "retail_rate": "13.15",
210      "retail_currency": "USD",
211      "list_rate": "9.41",
212      "list_currency": "USD",
213      "billing_type": "easypost",
214      "delivery_days": 3,
215      "delivery_date": null,
216      "delivery_date_guaranteed": false,
217      "est_delivery_days": 3,
218      "shipment_id": "shp_032866f1a5174949bc938acc7f4a19fc",
219      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
220    }
221  ],
222  "refund_status": null,
223  "scan_form": null,
224  "selected_rate": {
225    "id": "rate_55157308ac5e46ef88c45f726bcbc786",
226    "object": "Rate",
227    "created_at": "2024-01-24T00:07:34Z",
228    "updated_at": "2024-01-24T00:07:34Z",
229    "mode": "test",
230    "service": "Priority",
231    "carrier": "USPS",
232    "rate": "7.33",
233    "currency": "USD",
234    "retail_rate": "15.20",
235    "retail_currency": "USD",
236    "list_rate": "10.89",
237    "list_currency": "USD",
238    "billing_type": "easypost",
239    "delivery_days": 2,
240    "delivery_date": null,
241    "delivery_date_guaranteed": false,
242    "est_delivery_days": 2,
243    "shipment_id": "shp_032866f1a5174949bc938acc7f4a19fc",
244    "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
245  },
246  "tracker": {
247    "id": "trk_4f377a2463fe4af8a42f0bd2ea17d6d3",
248    "object": "Tracker",
249    "mode": "test",
250    "tracking_code": "9405500207552011812856",
251    "status": "unknown",
252    "status_detail": "unknown",
253    "created_at": "2024-01-24T00:07:35Z",
254    "updated_at": "2024-01-24T00:07:35Z",
255    "signed_by": null,
256    "weight": null,
257    "est_delivery_date": null,
258    "shipment_id": "shp_032866f1a5174949bc938acc7f4a19fc",
259    "carrier": "USPS",
260    "tracking_details": [],
261    "fees": [],
262    "carrier_detail": null,
263    "public_url": "https://track.easypost.com/djE6dHJrXzRmMzc3YTI0NjNmZTRhZjhhNDJmMGJkMmVhMTdkNmQz"
264  },
265  "to_address": {
266    "id": "adr_9319ec85ba4c11ee8ca2ac1f6bc53342",
267    "object": "Address",
268    "created_at": "2024-01-24T00:07:34+00:00",
269    "updated_at": "2024-01-24T00:07:34+00:00",
270    "name": "DR. STEVE BRULE",
271    "company": null,
272    "street1": "179 N HARBOR DR",
273    "street2": "",
274    "city": "REDONDO BEACH",
275    "state": "CA",
276    "zip": "90277-2506",
277    "country": "US",
278    "phone": "8573875756",
279    "email": "DR_STEVE_BRULE@GMAIL.COM",
280    "mode": "test",
281    "carrier_facility": null,
282    "residential": false,
283    "federal_tax_id": null,
284    "state_tax_id": null,
285    "verifications": {
286      "zip4": {
287        "success": true,
288        "errors": [],
289        "details": null
290      },
291      "delivery": {
292        "success": true,
293        "errors": [],
294        "details": {
295          "latitude": 33.8436,
296          "longitude": -118.39177,
297          "time_zone": "America/Los_Angeles"
298        }
299      }
300    }
301  },
302  "usps_zone": 4,
303  "return_address": {
304    "id": "adr_931d01beba4c11eea85f3cecef1b359e",
305    "object": "Address",
306    "created_at": "2024-01-24T00:07:34+00:00",
307    "updated_at": "2024-01-24T00:07:34+00:00",
308    "name": "EasyPost",
309    "company": null,
310    "street1": "417 Montgomery Street",
311    "street2": "5th Floor",
312    "city": "San Francisco",
313    "state": "CA",
314    "zip": "94104",
315    "country": "US",
316    "phone": "4153334445",
317    "email": "support@easypost.com",
318    "mode": "test",
319    "carrier_facility": null,
320    "residential": null,
321    "federal_tax_id": null,
322    "state_tax_id": null,
323    "verifications": {}
324  },
325  "buyer_address": {
326    "id": "adr_9319ec85ba4c11ee8ca2ac1f6bc53342",
327    "object": "Address",
328    "created_at": "2024-01-24T00:07:34+00:00",
329    "updated_at": "2024-01-24T00:07:34+00:00",
330    "name": "DR. STEVE BRULE",
331    "company": null,
332    "street1": "179 N HARBOR DR",
333    "street2": "",
334    "city": "REDONDO BEACH",
335    "state": "CA",
336    "zip": "90277-2506",
337    "country": "US",
338    "phone": "8573875756",
339    "email": "DR_STEVE_BRULE@GMAIL.COM",
340    "mode": "test",
341    "carrier_facility": null,
342    "residential": false,
343    "federal_tax_id": null,
344    "state_tax_id": null,
345    "verifications": {
346      "zip4": {
347        "success": true,
348        "errors": [],
349        "details": null
350      },
351      "delivery": {
352        "success": true,
353        "errors": [],
354        "details": {
355          "latitude": 33.8436,
356          "longitude": -118.39177,
357          "time_zone": "America/Los_Angeles"
358        }
359      }
360    }
361  },
362  "forms": [],
363  "fees": [
364    {
365      "object": "Fee",
366      "type": "LabelFee",
367      "amount": "0.00000",
368      "charged": true,
369      "refunded": false
370    },
371    {
372      "object": "Fee",
373      "type": "PostageFee",
374      "amount": "7.33000",
375      "charged": true,
376      "refunded": false
377    }
378  ],
379  "id": "shp_032866f1a5174949bc938acc7f4a19fc",
380  "object": "Shipment"
381}

Retrieve all Shipments

A list of all Shipment objects associated with the given API Key can also be retrieved. See the Pagination section of our docs for more details on retrieving all records when multiple pages are available.

Request Parameters

before_id
i.e. shp_...
Optional pagination parameter. Only records created before the given ID will be included. May not be used with after_id.
after_id
i.e. shp_...
Optional pagination parameter. Only records created after the given ID will be included. May not be used with before_id.
start_datetime
i.e. 2016-01-02T00:00:00Z
Only return records created after this timestamp. Defaults to 1 month ago, or 1 month before a passed end_datetime.
end_datetime
i.e. 2016-01-02T00:00:00Z
Only return records created before this timestamp. Defaults to end of the current day, or 1 month after a passed start_datetime.
page_size
i.e. 20
The number of records to return on each page. The maximum value is 100, and default is 20.
purchased
i.e. true
Only include Shipments that have been purchased. Default is true
include_children
i.e. false
Also include Shipments created by Child Users. Defaults to false
GET /shipments
1curl -X GET https://api.easypost.com/v2/shipments?page_size=5 \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "shipments": [
3    {
4      "created_at": "2024-01-24T00:07:28Z",
5      "is_return": false,
6      "messages": [],
7      "mode": "test",
8      "options": {
9        "currency": "USD",
10        "payment": {
11          "type": "SENDER"
12        },
13        "date_advance": 0
14      },
15      "reference": null,
16      "status": "unknown",
17      "tracking_code": "9405500207552011812825",
18      "updated_at": "2024-01-24T00:07:29Z",
19      "batch_id": "batch_83009a1272fa48ffb1a3d29074a16960",
20      "batch_status": "postage_purchased",
21      "batch_message": null,
22      "customs_info": {
23        "id": "cstinfo_916710a3039140c5a6e7f2f812ef83d7",
24        "object": "CustomsInfo",
25        "created_at": "2024-01-24T00:07:28Z",
26        "updated_at": "2024-01-24T00:07:28Z",
27        "contents_explanation": "",
28        "contents_type": "merchandise",
29        "customs_certify": true,
30        "customs_signer": "Steve Brule",
31        "eel_pfc": "NOEEI 30.37(a)",
32        "non_delivery_option": "return",
33        "restriction_comments": null,
34        "restriction_type": "none",
35        "mode": "test",
36        "declaration": null,
37        "customs_items": [
38          {
39            "id": "cstitem_eead7973a2d644189ebd7c8f11f9647a",
40            "object": "CustomsItem",
41            "created_at": "2024-01-24T00:07:28Z",
42            "updated_at": "2024-01-24T00:07:28Z",
43            "description": "T-shirt",
44            "hs_tariff_number": "123456",
45            "origin_country": "US",
46            "quantity": 1,
47            "value": "10.0",
48            "weight": 5.0,
49            "code": "123",
50            "mode": "test",
51            "manufacturer": null,
52            "currency": null,
53            "eccn": null,
54            "printed_commodity_identifier": null
55          }
56        ]
57      },
58      "from_address": {
59        "id": "adr_8f5e7e74ba4c11ee8bd0ac1f6bc53342",
60        "object": "Address",
61        "created_at": "2024-01-24T00:07:28+00:00",
62        "updated_at": "2024-01-24T00:07:28+00:00",
63        "name": "EasyPost",
64        "company": null,
65        "street1": "417 Montgomery Street",
66        "street2": "5th Floor",
67        "city": "San Francisco",
68        "state": "CA",
69        "zip": "94104",
70        "country": "US",
71        "phone": "4153334445",
72        "email": "support@easypost.com",
73        "mode": "test",
74        "carrier_facility": null,
75        "residential": null,
76        "federal_tax_id": null,
77        "state_tax_id": null,
78        "verifications": {}
79      },
80      "insurance": null,
81      "order_id": null,
82      "parcel": {
83        "id": "prcl_bba0f7cc48d64a299938fef3a3e0b9a0",
84        "object": "Parcel",
85        "created_at": "2024-01-24T00:07:28Z",
86        "updated_at": "2024-01-24T00:07:28Z",
87        "length": 20.2,
88        "width": 10.9,
89        "height": 5.0,
90        "predefined_package": null,
91        "weight": 65.9,
92        "mode": "test"
93      },
94      "postage_label": {
95        "object": "PostageLabel",
96        "id": "pl_9562571fa39b4e49892a8c60f12be255",
97        "created_at": "2024-01-24T00:07:28Z",
98        "updated_at": "2024-01-24T00:07:28Z",
99        "date_advance": 0,
100        "integrated_form": "none",
101        "label_date": "2024-01-24T00:07:28Z",
102        "label_resolution": 300,
103        "label_size": "4x6",
104        "label_type": "default",
105        "label_file_type": "image/png",
106        "label_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/20240124/e8a95864fe9ec34eeabf5fc2ad415fda5d.png",
107        "label_pdf_url": null,
108        "label_zpl_url": null,
109        "label_epl2_url": null,
110        "label_file": null
111      },
112      "rates": [
113        {
114          "id": "rate_15a03f25e00d49a098da8d40c8e1719e",
115          "object": "Rate",
116          "created_at": "2024-01-24T00:07:28Z",
117          "updated_at": "2024-01-24T00:07:28Z",
118          "mode": "test",
119          "service": "Express",
120          "carrier": "USPS",
121          "rate": "49.60",
122          "currency": "USD",
123          "retail_rate": "57.40",
124          "retail_currency": "USD",
125          "list_rate": "49.60",
126          "list_currency": "USD",
127          "billing_type": "easypost",
128          "delivery_days": null,
129          "delivery_date": null,
130          "delivery_date_guaranteed": false,
131          "est_delivery_days": null,
132          "shipment_id": "shp_8631f00640ba4d62b9131da3852a26e4",
133          "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
134        },
135        {
136          "id": "rate_edd7e3cedd9d4aa9bd21eb23a740af7d",
137          "object": "Rate",
138          "created_at": "2024-01-24T00:07:28Z",
139          "updated_at": "2024-01-24T00:07:28Z",
140          "mode": "test",
141          "service": "Priority",
142          "carrier": "USPS",
143          "rate": "7.33",
144          "currency": "USD",
145          "retail_rate": "15.20",
146          "retail_currency": "USD",
147          "list_rate": "10.89",
148          "list_currency": "USD",
149          "billing_type": "easypost",
150          "delivery_days": 2,
151          "delivery_date": null,
152          "delivery_date_guaranteed": false,
153          "est_delivery_days": 2,
154          "shipment_id": "shp_8631f00640ba4d62b9131da3852a26e4",
155          "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
156        },
157        {
158          "id": "rate_bc0979e7fa314d2b935d8fee9312c766",
159          "object": "Rate",
160          "created_at": "2024-01-24T00:07:28Z",
161          "updated_at": "2024-01-24T00:07:28Z",
162          "mode": "test",
163          "service": "GroundAdvantage",
164          "carrier": "USPS",
165          "rate": "6.79",
166          "currency": "USD",
167          "retail_rate": "13.15",
168          "retail_currency": "USD",
169          "list_rate": "9.41",
170          "list_currency": "USD",
171          "billing_type": "easypost",
172          "delivery_days": 3,
173          "delivery_date": null,
174          "delivery_date_guaranteed": false,
175          "est_delivery_days": 3,
176          "shipment_id": "shp_8631f00640ba4d62b9131da3852a26e4",
177          "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
178        },
179        {
180          "id": "rate_418622e2edeb4015b8bbd72fbe2d3ff6",
181          "object": "Rate",
182          "created_at": "2024-01-24T00:07:28Z",
183          "updated_at": "2024-01-24T00:07:28Z",
184          "mode": "test",
185          "service": "First",
186          "carrier": "USPS",
187          "rate": "6.79",
188          "currency": "USD",
189          "retail_rate": "13.15",
190          "retail_currency": "USD",
191          "list_rate": "9.41",
192          "list_currency": "USD",
193          "billing_type": "easypost",
194          "delivery_days": 3,
195          "delivery_date": null,
196          "delivery_date_guaranteed": false,
197          "est_delivery_days": 3,
198          "shipment_id": "shp_8631f00640ba4d62b9131da3852a26e4",
199          "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
200        },
201        {
202          "id": "rate_699f9b847989489891a0db1489c6c0f2",
203          "object": "Rate",
204          "created_at": "2024-01-24T00:07:28Z",
205          "updated_at": "2024-01-24T00:07:28Z",
206          "mode": "test",
207          "service": "ParcelSelect",
208          "carrier": "USPS",
209          "rate": "6.79",
210          "currency": "USD",
211          "retail_rate": "13.15",
212          "retail_currency": "USD",
213          "list_rate": "9.41",
214          "list_currency": "USD",
215          "billing_type": "easypost",
216          "delivery_days": 3,
217          "delivery_date": null,
218          "delivery_date_guaranteed": false,
219          "est_delivery_days": 3,
220          "shipment_id": "shp_8631f00640ba4d62b9131da3852a26e4",
221          "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
222        }
223      ],
224      "refund_status": null,
225      "scan_form": {
226        "id": "sf_589e52186e9249669c7806912a6ab766",
227        "object": "ScanForm",
228        "created_at": "2024-01-24T00:07:29Z",
229        "updated_at": "2024-01-24T00:07:29Z",
230        "tracking_codes": ["9405500207552011812825"],
231        "address": {
232          "id": "adr_8f5e7e74ba4c11ee8bd0ac1f6bc53342",
233          "object": "Address",
234          "created_at": "2024-01-24T00:07:28+00:00",
235          "updated_at": "2024-01-24T00:07:28+00:00",
236          "name": "EasyPost",
237          "company": null,
238          "street1": "417 Montgomery Street",
239          "street2": "5th Floor",
240          "city": "San Francisco",
241          "state": "CA",
242          "zip": "94104",
243          "country": "US",
244          "phone": "4153334445",
245          "email": "support@easypost.com",
246          "mode": "test",
247          "carrier_facility": null,
248          "residential": null,
249          "federal_tax_id": null,
250          "state_tax_id": null,
251          "verifications": {}
252        },
253        "status": "created",
254        "message": null,
255        "form_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/scan_form/20240124/e82a4cb71096604dc7bd773b1285d7e9db.pdf",
256        "form_file_type": null,
257        "batch_id": "batch_83009a1272fa48ffb1a3d29074a16960",
258        "confirmation": null
259      },
260      "selected_rate": {
261        "id": "rate_edd7e3cedd9d4aa9bd21eb23a740af7d",
262        "object": "Rate",
263        "created_at": "2024-01-24T00:07:28Z",
264        "updated_at": "2024-01-24T00:07:28Z",
265        "mode": "test",
266        "service": "Priority",
267        "carrier": "USPS",
268        "rate": "7.33",
269        "currency": "USD",
270        "retail_rate": "15.20",
271        "retail_currency": "USD",
272        "list_rate": "10.89",
273        "list_currency": "USD",
274        "billing_type": "easypost",
275        "delivery_days": 2,
276        "delivery_date": null,
277        "delivery_date_guaranteed": false,
278        "est_delivery_days": 2,
279        "shipment_id": "shp_8631f00640ba4d62b9131da3852a26e4",
280        "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
281      },
282      "tracker": {
283        "id": "trk_c64aa4ee22804cceab41586397c4b833",
284        "object": "Tracker",
285        "mode": "test",
286        "tracking_code": "9405500207552011812825",
287        "status": "pre_transit",
288        "status_detail": "status_update",
289        "created_at": "2024-01-24T00:07:28Z",
290        "updated_at": "2024-01-24T00:07:29Z",
291        "signed_by": null,
292        "weight": null,
293        "est_delivery_date": "2024-01-24T00:07:29Z",
294        "shipment_id": "shp_8631f00640ba4d62b9131da3852a26e4",
295        "carrier": "USPS",
296        "tracking_details": [
297          {
298            "object": "TrackingDetail",
299            "message": "Pre-Shipment Info Sent to USPS",
300            "description": "",
301            "status": "pre_transit",
302            "status_detail": "status_update",
303            "datetime": "2023-12-24T00:07:29Z",
304            "source": "USPS",
305            "carrier_code": "",
306            "tracking_location": {
307              "object": "TrackingLocation",
308              "city": null,
309              "state": null,
310              "country": null,
311              "zip": null
312            }
313          },
314          {
315            "object": "TrackingDetail",
316            "message": "Shipping Label Created",
317            "description": "",
318            "status": "pre_transit",
319            "status_detail": "status_update",
320            "datetime": "2023-12-24T12:44:29Z",
321            "source": "USPS",
322            "carrier_code": "",
323            "tracking_location": {
324              "object": "TrackingLocation",
325              "city": "HOUSTON",
326              "state": "TX",
327              "country": null,
328              "zip": "77063"
329            }
330          }
331        ],
332        "fees": [],
333        "carrier_detail": {
334          "object": "CarrierDetail",
335          "service": "First-Class Package Service",
336          "container_type": null,
337          "est_delivery_date_local": null,
338          "est_delivery_time_local": null,
339          "origin_location": "HOUSTON TX, 77001",
340          "origin_tracking_location": {
341            "object": "TrackingLocation",
342            "city": "HOUSTON",
343            "state": "TX",
344            "country": null,
345            "zip": "77063"
346          },
347          "destination_location": "CHARLESTON SC, 29401",
348          "destination_tracking_location": null,
349          "guaranteed_delivery_date": null,
350          "alternate_identifier": null,
351          "initial_delivery_attempt": null
352        },
353        "public_url": "https://track.easypost.com/djE6dHJrX2M2NGFhNGVlMjI4MDRjY2VhYjQxNTg2Mzk3YzRiODMz"
354      },
355      "to_address": {
356        "id": "adr_8f5bb1f5ba4c11eeb6a1ac1f6bc539aa",
357        "object": "Address",
358        "created_at": "2024-01-24T00:07:28+00:00",
359        "updated_at": "2024-01-24T00:07:28+00:00",
360        "name": "DR. STEVE BRULE",
361        "company": null,
362        "street1": "179 N HARBOR DR",
363        "street2": null,
364        "city": "REDONDO BEACH",
365        "state": "CA",
366        "zip": "90277-2506",
367        "country": "US",
368        "phone": "8573875756",
369        "email": "DR_STEVE_BRULE@GMAIL.COM",
370        "mode": "test",
371        "carrier_facility": null,
372        "residential": false,
373        "federal_tax_id": null,
374        "state_tax_id": null,
375        "verifications": {
376          "zip4": {
377            "success": true,
378            "errors": [],
379            "details": null
380          },
381          "delivery": {
382            "success": true,
383            "errors": [],
384            "details": {
385              "latitude": 33.8436,
386              "longitude": -118.39177,
387              "time_zone": "America/Los_Angeles"
388            }
389          }
390        }
391      },
392      "usps_zone": 4,
393      "return_address": {
394        "id": "adr_8f5e7e74ba4c11ee8bd0ac1f6bc53342",
395        "object": "Address",
396        "created_at": "2024-01-24T00:07:28+00:00",
397        "updated_at": "2024-01-24T00:07:28+00:00",
398        "name": "EasyPost",
399        "company": null,
400        "street1": "417 Montgomery Street",
401        "street2": "5th Floor",
402        "city": "San Francisco",
403        "state": "CA",
404        "zip": "94104",
405        "country": "US",
406        "phone": "4153334445",
407        "email": "support@easypost.com",
408        "mode": "test",
409        "carrier_facility": null,
410        "residential": null,
411        "federal_tax_id": null,
412        "state_tax_id": null,
413        "verifications": {}
414      },
415      "buyer_address": {
416        "id": "adr_8f5bb1f5ba4c11eeb6a1ac1f6bc539aa",
417        "object": "Address",
418        "created_at": "2024-01-24T00:07:28+00:00",
419        "updated_at": "2024-01-24T00:07:28+00:00",
420        "name": "DR. STEVE BRULE",
421        "company": null,
422        "street1": "179 N HARBOR DR",
423        "street2": null,
424        "city": "REDONDO BEACH",
425        "state": "CA",
426        "zip": "90277-2506",
427        "country": "US",
428        "phone": "8573875756",
429        "email": "DR_STEVE_BRULE@GMAIL.COM",
430        "mode": "test",
431        "carrier_facility": null,
432        "residential": false,
433        "federal_tax_id": null,
434        "state_tax_id": null,
435        "verifications": {
436          "zip4": {
437            "success": true,
438            "errors": [],
439            "details": null
440          },
441          "delivery": {
442            "success": true,
443            "errors": [],
444            "details": {
445              "latitude": 33.8436,
446              "longitude": -118.39177,
447              "time_zone": "America/Los_Angeles"
448            }
449          }
450        }
451      },
452      "forms": [],
453      "fees": [
454        {
455          "object": "Fee",
456          "type": "LabelFee",
457          "amount": "0.00000",
458          "charged": true,
459          "refunded": false
460        },
461        {
462          "object": "Fee",
463          "type": "PostageFee",
464          "amount": "7.33000",
465          "charged": true,
466          "refunded": false
467        }
468      ],
469      "id": "shp_8631f00640ba4d62b9131da3852a26e4",
470      "object": "Shipment"
471    }
472  ],
473  "has_more": true
474}

Retrieve a Shipment

A Shipment can be retrieved by either its id or reference. However it is recommended to use EasyPost's provided identifiers because uniqueness on reference is not enforced.

GET /shipments/:id
1curl -X GET https://api.easypost.com/v2/shipments/shp_... \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "created_at": "2024-01-24T00:07:31Z",
3  "is_return": false,
4  "messages": [],
5  "mode": "test",
6  "options": {
7    "currency": "USD",
8    "payment": {
9      "type": "SENDER"
10    },
11    "date_advance": 0
12  },
13  "reference": null,
14  "status": "unknown",
15  "tracking_code": null,
16  "updated_at": "2024-01-24T00:07:31Z",
17  "batch_id": null,
18  "batch_status": null,
19  "batch_message": null,
20  "customs_info": {
21    "id": "cstinfo_0096afa682bf443d91d2290bc95bb431",
22    "object": "CustomsInfo",
23    "created_at": "2024-01-24T00:07:31Z",
24    "updated_at": "2024-01-24T00:07:31Z",
25    "contents_explanation": "",
26    "contents_type": "merchandise",
27    "customs_certify": true,
28    "customs_signer": "Steve Brule",
29    "eel_pfc": "NOEEI 30.37(a)",
30    "non_delivery_option": "return",
31    "restriction_comments": null,
32    "restriction_type": "none",
33    "mode": "test",
34    "declaration": null,
35    "customs_items": [
36      {
37        "id": "cstitem_4cd92d282b9044e0a5fe4d430e221b04",
38        "object": "CustomsItem",
39        "created_at": "2024-01-24T00:07:31Z",
40        "updated_at": "2024-01-24T00:07:31Z",
41        "description": "T-shirt",
42        "hs_tariff_number": "123456",
43        "origin_country": "US",
44        "quantity": 1,
45        "value": "10.0",
46        "weight": 5.0,
47        "code": "123",
48        "mode": "test",
49        "manufacturer": null,
50        "currency": null,
51        "eccn": null,
52        "printed_commodity_identifier": null
53      }
54    ]
55  },
56  "from_address": {
57    "id": "adr_913347feba4c11eeb701ac1f6bc539aa",
58    "object": "Address",
59    "created_at": "2024-01-24T00:07:31+00:00",
60    "updated_at": "2024-01-24T00:07:31+00:00",
61    "name": "EasyPost",
62    "company": null,
63    "street1": "417 Montgomery Street",
64    "street2": "5th Floor",
65    "city": "San Francisco",
66    "state": "CA",
67    "zip": "94104",
68    "country": "US",
69    "phone": "4153334445",
70    "email": "support@easypost.com",
71    "mode": "test",
72    "carrier_facility": null,
73    "residential": null,
74    "federal_tax_id": null,
75    "state_tax_id": null,
76    "verifications": {}
77  },
78  "insurance": null,
79  "order_id": null,
80  "parcel": {
81    "id": "prcl_400658d40a1f40aa9871d002dfdfb68d",
82    "object": "Parcel",
83    "created_at": "2024-01-24T00:07:31Z",
84    "updated_at": "2024-01-24T00:07:31Z",
85    "length": 20.2,
86    "width": 10.9,
87    "height": 5.0,
88    "predefined_package": null,
89    "weight": 65.9,
90    "mode": "test"
91  },
92  "postage_label": null,
93  "rates": [
94    {
95      "id": "rate_3a88998080864f5dafd05f0e39655253",
96      "object": "Rate",
97      "created_at": "2024-01-24T00:07:31Z",
98      "updated_at": "2024-01-24T00:07:31Z",
99      "mode": "test",
100      "service": "Express",
101      "carrier": "USPS",
102      "rate": "49.60",
103      "currency": "USD",
104      "retail_rate": "57.40",
105      "retail_currency": "USD",
106      "list_rate": "49.60",
107      "list_currency": "USD",
108      "billing_type": "easypost",
109      "delivery_days": null,
110      "delivery_date": null,
111      "delivery_date_guaranteed": false,
112      "est_delivery_days": null,
113      "shipment_id": "shp_594234d296794803bfd0a6814a29d976",
114      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
115    },
116    {
117      "id": "rate_54f2ef16614541fda0eb4cac44155954",
118      "object": "Rate",
119      "created_at": "2024-01-24T00:07:31Z",
120      "updated_at": "2024-01-24T00:07:31Z",
121      "mode": "test",
122      "service": "Priority",
123      "carrier": "USPS",
124      "rate": "7.33",
125      "currency": "USD",
126      "retail_rate": "15.20",
127      "retail_currency": "USD",
128      "list_rate": "10.89",
129      "list_currency": "USD",
130      "billing_type": "easypost",
131      "delivery_days": 2,
132      "delivery_date": null,
133      "delivery_date_guaranteed": false,
134      "est_delivery_days": 2,
135      "shipment_id": "shp_594234d296794803bfd0a6814a29d976",
136      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
137    },
138    {
139      "id": "rate_591fb9d8f10d456ea105ea2e700c00ad",
140      "object": "Rate",
141      "created_at": "2024-01-24T00:07:31Z",
142      "updated_at": "2024-01-24T00:07:31Z",
143      "mode": "test",
144      "service": "GroundAdvantage",
145      "carrier": "USPS",
146      "rate": "6.79",
147      "currency": "USD",
148      "retail_rate": "13.15",
149      "retail_currency": "USD",
150      "list_rate": "9.41",
151      "list_currency": "USD",
152      "billing_type": "easypost",
153      "delivery_days": 3,
154      "delivery_date": null,
155      "delivery_date_guaranteed": false,
156      "est_delivery_days": 3,
157      "shipment_id": "shp_594234d296794803bfd0a6814a29d976",
158      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
159    },
160    {
161      "id": "rate_3bf9ed1c9fef437e957faeb8eb77d7f7",
162      "object": "Rate",
163      "created_at": "2024-01-24T00:07:31Z",
164      "updated_at": "2024-01-24T00:07:31Z",
165      "mode": "test",
166      "service": "First",
167      "carrier": "USPS",
168      "rate": "6.79",
169      "currency": "USD",
170      "retail_rate": "13.15",
171      "retail_currency": "USD",
172      "list_rate": "9.41",
173      "list_currency": "USD",
174      "billing_type": "easypost",
175      "delivery_days": 3,
176      "delivery_date": null,
177      "delivery_date_guaranteed": false,
178      "est_delivery_days": 3,
179      "shipment_id": "shp_594234d296794803bfd0a6814a29d976",
180      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
181    },
182    {
183      "id": "rate_bf060d1d9e4a41c6bdbef4bee91643dd",
184      "object": "Rate",
185      "created_at": "2024-01-24T00:07:31Z",
186      "updated_at": "2024-01-24T00:07:31Z",
187      "mode": "test",
188      "service": "ParcelSelect",
189      "carrier": "USPS",
190      "rate": "6.79",
191      "currency": "USD",
192      "retail_rate": "13.15",
193      "retail_currency": "USD",
194      "list_rate": "9.41",
195      "list_currency": "USD",
196      "billing_type": "easypost",
197      "delivery_days": 3,
198      "delivery_date": null,
199      "delivery_date_guaranteed": false,
200      "est_delivery_days": 3,
201      "shipment_id": "shp_594234d296794803bfd0a6814a29d976",
202      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
203    }
204  ],
205  "refund_status": null,
206  "scan_form": null,
207  "selected_rate": null,
208  "tracker": null,
209  "to_address": {
210    "id": "adr_91305d88ba4c11eea7e63cecef1b359e",
211    "object": "Address",
212    "created_at": "2024-01-24T00:07:31+00:00",
213    "updated_at": "2024-01-24T00:07:31+00:00",
214    "name": "Dr. Steve Brule",
215    "company": null,
216    "street1": "179 N Harbor Dr",
217    "street2": null,
218    "city": "Redondo Beach",
219    "state": "CA",
220    "zip": "90277",
221    "country": "US",
222    "phone": "8573875756",
223    "email": "dr_steve_brule@gmail.com",
224    "mode": "test",
225    "carrier_facility": null,
226    "residential": null,
227    "federal_tax_id": null,
228    "state_tax_id": null,
229    "verifications": {}
230  },
231  "usps_zone": 4,
232  "return_address": {
233    "id": "adr_913347feba4c11eeb701ac1f6bc539aa",
234    "object": "Address",
235    "created_at": "2024-01-24T00:07:31+00:00",
236    "updated_at": "2024-01-24T00:07:31+00:00",
237    "name": "EasyPost",
238    "company": null,
239    "street1": "417 Montgomery Street",
240    "street2": "5th Floor",
241    "city": "San Francisco",
242    "state": "CA",
243    "zip": "94104",
244    "country": "US",
245    "phone": "4153334445",
246    "email": "support@easypost.com",
247    "mode": "test",
248    "carrier_facility": null,
249    "residential": null,
250    "federal_tax_id": null,
251    "state_tax_id": null,
252    "verifications": {}
253  },
254  "buyer_address": {
255    "id": "adr_91305d88ba4c11eea7e63cecef1b359e",
256    "object": "Address",
257    "created_at": "2024-01-24T00:07:31+00:00",
258    "updated_at": "2024-01-24T00:07:31+00:00",
259    "name": "Dr. Steve Brule",
260    "company": null,
261    "street1": "179 N Harbor Dr",
262    "street2": null,
263    "city": "Redondo Beach",
264    "state": "CA",
265    "zip": "90277",
266    "country": "US",
267    "phone": "8573875756",
268    "email": "dr_steve_brule@gmail.com",
269    "mode": "test",
270    "carrier_facility": null,
271    "residential": null,
272    "federal_tax_id": null,
273    "state_tax_id": null,
274    "verifications": {}
275  },
276  "forms": [],
277  "fees": [],
278  "id": "shp_594234d296794803bfd0a6814a29d976",
279  "object": "Shipment"
280}

Converting the Label format of a Shipment

A Shipment's PostageLabel can be converted from PNG to other formats. To convert a PostageLabel, the original must be a PNG. Converting labels works best when they are 4x6 labels converted from PNG to ZPL.

GET /shipments/:id/label
1curl -X GET https://api.easypost.com/v2/shipments/shp_.../label?file_format=ZPL \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "created_at": "2024-01-24T00:07:35Z",
3  "is_return": false,
4  "messages": [],
5  "mode": "test",
6  "options": {
7    "currency": "USD",
8    "payment": {
9      "type": "SENDER"
10    },
11    "date_advance": 0
12  },
13  "reference": null,
14  "status": "unknown",
15  "tracking_code": "9434600207552011812862",
16  "updated_at": "2024-01-24T00:07:36Z",
17  "batch_id": null,
18  "batch_status": null,
19  "batch_message": null,
20  "customs_info": {
21    "id": "cstinfo_7020222e3699472186d9be5f7fe03965",
22    "object": "CustomsInfo",
23    "created_at": "2024-01-24T00:07:35Z",
24    "updated_at": "2024-01-24T00:07:35Z",
25    "contents_explanation": "",
26    "contents_type": "merchandise",
27    "customs_certify": true,
28    "customs_signer": "Steve Brule",
29    "eel_pfc": "NOEEI 30.37(a)",
30    "non_delivery_option": "return",
31    "restriction_comments": null,
32    "restriction_type": "none",
33    "mode": "test",
34    "declaration": null,
35    "customs_items": [
36      {
37        "id": "cstitem_b5d2e40ce0ce4a19aab950a848928989",
38        "object": "CustomsItem",
39        "created_at": "2024-01-24T00:07:35Z",
40        "updated_at": "2024-01-24T00:07:35Z",
41        "description": "T-shirt",
42        "hs_tariff_number": "123456",
43        "origin_country": "US",
44        "quantity": 1,
45        "value": "10.0",
46        "weight": 5.0,
47        "code": "123",
48        "mode": "test",
49        "manufacturer": null,
50        "currency": null,
51        "eccn": null,
52        "printed_commodity_identifier": null
53      }
54    ]
55  },
56  "from_address": {
57    "id": "adr_93ec5efaba4c11eeb7baac1f6bc539aa",
58    "object": "Address",
59    "created_at": "2024-01-24T00:07:35+00:00",
60    "updated_at": "2024-01-24T00:07:35+00:00",
61    "name": "EasyPost",
62    "company": null,
63    "street1": "417 Montgomery Street",
64    "street2": "5th Floor",
65    "city": "San Francisco",
66    "state": "CA",
67    "zip": "94104",
68    "country": "US",
69    "phone": "4153334445",
70    "email": "support@easypost.com",
71    "mode": "test",
72    "carrier_facility": null,
73    "residential": null,
74    "federal_tax_id": null,
75    "state_tax_id": null,
76    "verifications": {}
77  },
78  "insurance": null,
79  "order_id": null,
80  "parcel": {
81    "id": "prcl_4aa6de11e4fa44739b7e4a2b3e28ad9a",
82    "object": "Parcel",
83    "created_at": "2024-01-24T00:07:35Z",
84    "updated_at": "2024-01-24T00:07:35Z",
85    "length": 20.2,
86    "width": 10.9,
87    "height": 5.0,
88    "predefined_package": null,
89    "weight": 65.9,
90    "mode": "test"
91  },
92  "postage_label": {
93    "object": "PostageLabel",
94    "id": "pl_e5d4aec4ee23458ebcb4d29c41ee75f4",
95    "created_at": "2024-01-24T00:07:36Z",
96    "updated_at": "2024-01-24T00:07:38Z",
97    "date_advance": 0,
98    "integrated_form": "none",
99    "label_date": "2024-01-24T00:07:36Z",
100    "label_resolution": 300,
101    "label_size": "4x6",
102    "label_type": "default",
103    "label_file_type": "image/png",
104    "label_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/20240124/e8118119c07a5e44a2aee0f6189f13f80a.png",
105    "label_pdf_url": null,
106    "label_zpl_url": "https://easypost-files.s3-us-west-2.amazonaws.com/files/postage_label/20240124/af790a0077514f32b1d035d8b2795bb0.zpl",
107    "label_epl2_url": null,
108    "label_file": null
109  },
110  "rates": [
111    {
112      "id": "rate_2068707826484b3cb89fac312a15525d",
113      "object": "Rate",
114      "created_at": "2024-01-24T00:07:35Z",
115      "updated_at": "2024-01-24T00:07:35Z",
116      "mode": "test",
117      "service": "GroundAdvantage",
118      "carrier": "USPS",
119      "rate": "6.79",
120      "currency": "USD",
121      "retail_rate": "13.15",
122      "retail_currency": "USD",
123      "list_rate": "9.41",
124      "list_currency": "USD",
125      "billing_type": "easypost",
126      "delivery_days": 3,
127      "delivery_date": null,
128      "delivery_date_guaranteed": false,
129      "est_delivery_days": 3,
130      "shipment_id": "shp_1d00461199d74698b40c1c1cc55654a7",
131      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
132    },
133    {
134      "id": "rate_a1cd9d7eb69d43d084b58a01a3d433b1",
135      "object": "Rate",
136      "created_at": "2024-01-24T00:07:35Z",
137      "updated_at": "2024-01-24T00:07:35Z",
138      "mode": "test",
139      "service": "First",
140      "carrier": "USPS",
141      "rate": "6.79",
142      "currency": "USD",
143      "retail_rate": "13.15",
144      "retail_currency": "USD",
145      "list_rate": "9.41",
146      "list_currency": "USD",
147      "billing_type": "easypost",
148      "delivery_days": 3,
149      "delivery_date": null,
150      "delivery_date_guaranteed": false,
151      "est_delivery_days": 3,
152      "shipment_id": "shp_1d00461199d74698b40c1c1cc55654a7",
153      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
154    },
155    {
156      "id": "rate_8276cb6c0c6e412a8dd4cf9b03de9eed",
157      "object": "Rate",
158      "created_at": "2024-01-24T00:07:35Z",
159      "updated_at": "2024-01-24T00:07:35Z",
160      "mode": "test",
161      "service": "ParcelSelect",
162      "carrier": "USPS",
163      "rate": "6.79",
164      "currency": "USD",
165      "retail_rate": "13.15",
166      "retail_currency": "USD",
167      "list_rate": "9.41",
168      "list_currency": "USD",
169      "billing_type": "easypost",
170      "delivery_days": 3,
171      "delivery_date": null,
172      "delivery_date_guaranteed": false,
173      "est_delivery_days": 3,
174      "shipment_id": "shp_1d00461199d74698b40c1c1cc55654a7",
175      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
176    },
177    {
178      "id": "rate_0f20dca65d464d56b6d86ad06f27f408",
179      "object": "Rate",
180      "created_at": "2024-01-24T00:07:35Z",
181      "updated_at": "2024-01-24T00:07:35Z",
182      "mode": "test",
183      "service": "Express",
184      "carrier": "USPS",
185      "rate": "49.60",
186      "currency": "USD",
187      "retail_rate": "57.40",
188      "retail_currency": "USD",
189      "list_rate": "49.60",
190      "list_currency": "USD",
191      "billing_type": "easypost",
192      "delivery_days": null,
193      "delivery_date": null,
194      "delivery_date_guaranteed": false,
195      "est_delivery_days": null,
196      "shipment_id": "shp_1d00461199d74698b40c1c1cc55654a7",
197      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
198    },
199    {
200      "id": "rate_1cee068a0deb4f1283aeb9834c70bca1",
201      "object": "Rate",
202      "created_at": "2024-01-24T00:07:35Z",
203      "updated_at": "2024-01-24T00:07:35Z",
204      "mode": "test",
205      "service": "Priority",
206      "carrier": "USPS",
207      "rate": "7.33",
208      "currency": "USD",
209      "retail_rate": "15.20",
210      "retail_currency": "USD",
211      "list_rate": "10.89",
212      "list_currency": "USD",
213      "billing_type": "easypost",
214      "delivery_days": 2,
215      "delivery_date": null,
216      "delivery_date_guaranteed": false,
217      "est_delivery_days": 2,
218      "shipment_id": "shp_1d00461199d74698b40c1c1cc55654a7",
219      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
220    }
221  ],
222  "refund_status": null,
223  "scan_form": null,
224  "selected_rate": {
225    "id": "rate_2068707826484b3cb89fac312a15525d",
226    "object": "Rate",
227    "created_at": "2024-01-24T00:07:36Z",
228    "updated_at": "2024-01-24T00:07:36Z",
229    "mode": "test",
230    "service": "GroundAdvantage",
231    "carrier": "USPS",
232    "rate": "6.79",
233    "currency": "USD",
234    "retail_rate": "13.15",
235    "retail_currency": "USD",
236    "list_rate": "9.41",
237    "list_currency": "USD",
238    "billing_type": "easypost",
239    "delivery_days": 3,
240    "delivery_date": null,
241    "delivery_date_guaranteed": false,
242    "est_delivery_days": 3,
243    "shipment_id": "shp_1d00461199d74698b40c1c1cc55654a7",
244    "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
245  },
246  "tracker": {
247    "id": "trk_f82598977d4147b6829b688ff79a5f83",
248    "object": "Tracker",
249    "mode": "test",
250    "tracking_code": "9434600207552011812862",
251    "status": "pre_transit",
252    "status_detail": "status_update",
253    "created_at": "2024-01-24T00:07:37Z",
254    "updated_at": "2024-01-24T00:07:37Z",
255    "signed_by": null,
256    "weight": null,
257    "est_delivery_date": "2024-01-24T00:07:37Z",
258    "shipment_id": "shp_1d00461199d74698b40c1c1cc55654a7",
259    "carrier": "USPS",
260    "tracking_details": [
261      {
262        "object": "TrackingDetail",
263        "message": "Pre-Shipment Info Sent to USPS",
264        "description": "",
265        "status": "pre_transit",
266        "status_detail": "status_update",
267        "datetime": "2023-12-24T00:07:37Z",
268        "source": "USPS",
269        "carrier_code": "",
270        "tracking_location": {
271          "object": "TrackingLocation",
272          "city": null,
273          "state": null,
274          "country": null,
275          "zip": null
276        }
277      },
278      {
279        "object": "TrackingDetail",
280        "message": "Shipping Label Created",
281        "description": "",
282        "status": "pre_transit",
283        "status_detail": "status_update",
284        "datetime": "2023-12-24T12:44:37Z",
285        "source": "USPS",
286        "carrier_code": "",
287        "tracking_location": {
288          "object": "TrackingLocation",
289          "city": "HOUSTON",
290          "state": "TX",
291          "country": null,
292          "zip": "77063"
293        }
294      }
295    ],
296    "fees": [],
297    "carrier_detail": {
298      "object": "CarrierDetail",
299      "service": "First-Class Package Service",
300      "container_type": null,
301      "est_delivery_date_local": null,
302      "est_delivery_time_local": null,
303      "origin_location": "HOUSTON TX, 77001",
304      "origin_tracking_location": {
305        "object": "TrackingLocation",
306        "city": "HOUSTON",
307        "state": "TX",
308        "country": null,
309        "zip": "77063"
310      },
311      "destination_location": "CHARLESTON SC, 29401",
312      "destination_tracking_location": null,
313      "guaranteed_delivery_date": null,
314      "alternate_identifier": null,
315      "initial_delivery_attempt": null
316    },
317    "public_url": "https://track.easypost.com/djE6dHJrX2Y4MjU5ODk3N2Q0MTQ3YjY4MjliNjg4ZmY3OWE1Zjgz"
318  },
319  "to_address": {
320    "id": "adr_93e694b8ba4c11eea88d3cecef1b359e",
321    "object": "Address",
322    "created_at": "2024-01-24T00:07:35+00:00",
323    "updated_at": "2024-01-24T00:07:36+00:00",
324    "name": "DR. STEVE BRULE",
325    "company": null,
326    "street1": "179 N HARBOR DR",
327    "street2": null,
328    "city": "REDONDO BEACH",
329    "state": "CA",
330    "zip": "90277-2506",
331    "country": "US",
332    "phone": "8573875756",
333    "email": "DR_STEVE_BRULE@GMAIL.COM",
334    "mode": "test",
335    "carrier_facility": null,
336    "residential": false,
337    "federal_tax_id": null,
338    "state_tax_id": null,
339    "verifications": {
340      "zip4": {
341        "success": true,
342        "errors": [],
343        "details": null
344      },
345      "delivery": {
346        "success": true,
347        "errors": [],
348        "details": {
349          "latitude": 33.8436,
350          "longitude": -118.39177,
351          "time_zone": "America/Los_Angeles"
352        }
353      }
354    }
355  },
356  "usps_zone": 4,
357  "return_address": {
358    "id": "adr_93ec5efaba4c11eeb7baac1f6bc539aa",
359    "object": "Address",
360    "created_at": "2024-01-24T00:07:35+00:00",
361    "updated_at": "2024-01-24T00:07:35+00:00",
362    "name": "EasyPost",
363    "company": null,
364    "street1": "417 Montgomery Street",
365    "street2": "5th Floor",
366    "city": "San Francisco",
367    "state": "CA",
368    "zip": "94104",
369    "country": "US",
370    "phone": "4153334445",
371    "email": "support@easypost.com",
372    "mode": "test",
373    "carrier_facility": null,
374    "residential": null,
375    "federal_tax_id": null,
376    "state_tax_id": null,
377    "verifications": {}
378  },
379  "buyer_address": {
380    "id": "adr_93e694b8ba4c11eea88d3cecef1b359e",
381    "object": "Address",
382    "created_at": "2024-01-24T00:07:35+00:00",
383    "updated_at": "2024-01-24T00:07:36+00:00",
384    "name": "DR. STEVE BRULE",
385    "company": null,
386    "street1": "179 N HARBOR DR",
387    "street2": null,
388    "city": "REDONDO BEACH",
389    "state": "CA",
390    "zip": "90277-2506",
391    "country": "US",
392    "phone": "8573875756",
393    "email": "DR_STEVE_BRULE@GMAIL.COM",
394    "mode": "test",
395    "carrier_facility": null,
396    "residential": false,
397    "federal_tax_id": null,
398    "state_tax_id": null,
399    "verifications": {
400      "zip4": {
401        "success": true,
402        "errors": [],
403        "details": null
404      },
405      "delivery": {
406        "success": true,
407        "errors": [],
408        "details": {
409          "latitude": 33.8436,
410          "longitude": -118.39177,
411          "time_zone": "America/Los_Angeles"
412        }
413      }
414    }
415  },
416  "forms": [],
417  "fees": [
418    {
419      "object": "Fee",
420      "type": "LabelFee",
421      "amount": "0.00000",
422      "charged": true,
423      "refunded": false
424    },
425    {
426      "object": "Fee",
427      "type": "PostageFee",
428      "amount": "6.79000",
429      "charged": true,
430      "refunded": false
431    }
432  ],
433  "id": "shp_1d00461199d74698b40c1c1cc55654a7",
434  "object": "Shipment"
435}