API Docs

EndShipper

Important: This endpoint only works for users of the EndShipper API. If you feel this is applicable for your use case, please contact sales.

The EndShipper API is for platforms purchasing postage on behalf of their users, the EndShipper. Platforms must assert the EndShipper details, as the EndShipper is ultimately responsible for what is in the box. Multiple labels purchased for the same EndShipper must use the same EndShipper object.

EndShipper objects must be created prior to buying a Shipment. Once EndShipper objects have been created, you must keep track of their public ID in order to use them during a label buy.

Endpoints
POST
/end_shippers
POST
/shipments/:id/buy
GET
/end_shippers
GET
/end_shippers/:id
PUT
/end_shippers/:id

EndShipper object

object
string
"EndShipper"
id
string
Unique identifier, begins with "es_"
mode
string
"test" or "production"
name
string
Name of responsible person (conditionally required)
company
string
Name of responsible company (conditionally required)
street1
string
First line of the address
street2
string
Second line of the address
city
string
City the address is located in
state
string
State the address is located in
zip
string
ZIP or postal code the address is located in
country
string
Country code the address is located in. Must be "US" for EndShippers.
phone
string
Phone number to reach the person or organization
email
string
Email to reach the person or organization
EndShipper Object
{
  "id": "es_19a5071f0d224bd6a3eb372e408cdbee",
  "object": "EndShipper",
  "mode": "test",
  "created_at": "2024-01-24T00:05:44+00:00",
  "updated_at": "2024-01-24T00:05:44+00:00",
  "name": "FOO BAR",
  "company": "BAZ",
  "street1": "164 TOWNSEND ST UNIT 1",
  "street2": "",
  "city": "SAN FRANCISCO",
  "state": "CA",
  "zip": "94107-1990",
  "country": "US",
  "phone": "555 555-5555",
  "email": "FOO@EXAMPLE.COM"
}

Create an EndShipper

The EndShipper object is meant to represent the person or business entity responsible for the shipment and not necessarily the shipping location.

EndShipper objects are fully-qualified Address objects and require every field to be filled, with some exceptions:

  1. name and company — at least one of these fields must be filled; when both are present, name will take precedence
  2. street2 — this field may be left empty if the address does not include multiple lines

Request Parameters

name
i.e. Hiro Protagonist
Name of responsible person (conditionally required)
company
i.e. EasyPost
Name of responsible company (conditionally required)
street1
i.e. 417 Montgomery St
First line of the address
street2
i.e. Floor 5
Second line of the address
city
i.e. San Francisco
City the address is located in
state
i.e. CA
State the address is located in
zip
i.e. 94104
ZIP or postal code the address is located in
country
i.e. US
Country code the address is located in. Must be "US" for EndShippers.
phone
i.e. 415-123-4567
Phone number to reach the person or organization
email
i.e. example@example.com
Email to reach the person or organization
POST /end_shippers
1curl -X POST https://api.easypost.com/v2/end_shippers \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "address": {
6      "name": "FOO BAR",
7      "company": "BAZ",
8      "street1": "164 TOWNSEND STREET UNIT 1",
9      "street2": "UNIT 1",
10      "city": "SAN FRANCISCO",
11      "state": "CA",
12      "zip": "94107",
13      "country": "US",
14      "phone": "555-555-5555",
15      "email": "FOO@EXAMPLE.COM"
16    }
17  }'
Response
1{
2  "id": "es_19a5071f0d224bd6a3eb372e408cdbee",
3  "object": "EndShipper",
4  "mode": "test",
5  "created_at": "2024-01-24T00:05:44+00:00",
6  "updated_at": "2024-01-24T00:05:44+00:00",
7  "name": "FOO BAR",
8  "company": "BAZ",
9  "street1": "164 TOWNSEND ST UNIT 1",
10  "street2": "",
11  "city": "SAN FRANCISCO",
12  "state": "CA",
13  "zip": "94107-1990",
14  "country": "US",
15  "phone": "555 555-5555",
16  "email": "FOO@EXAMPLE.COM"
17}

Buy a Shipment with EndShipper

Buy a Shipment and specify an EndShipper ID in the request.

Request Parameters

end_shipper_id
i.e. es_...
Unique, starts with "es_"
rate
i.e. rate_...
Rate object to purchase the Shipment with
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    "end_shipper_id": "es_..."
9  }'
Response
1{
2  "created_at": "2024-01-24T00:05:47Z",
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": "9434600207552011812534",
16  "updated_at": "2024-01-24T00:05:48Z",
17  "batch_id": null,
18  "batch_status": null,
19  "batch_message": null,
20  "customs_info": {
21    "id": "cstinfo_e46e1b49abf64d21af9701894ca1592e",
22    "object": "CustomsInfo",
23    "created_at": "2024-01-24T00:05:47Z",
24    "updated_at": "2024-01-24T00:05:47Z",
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_4ade6839412c44e68d323ab9b6c29275",
38        "object": "CustomsItem",
39        "created_at": "2024-01-24T00:05:47Z",
40        "updated_at": "2024-01-24T00:05:47Z",
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_5336fc74ba4c11ee8c01ac1f6bc539ae",
58    "object": "Address",
59    "created_at": "2024-01-24T00:05:47+00:00",
60    "updated_at": "2024-01-24T00:05:47+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_b807202b272042a6bceadbac1653bf9c",
82    "object": "Parcel",
83    "created_at": "2024-01-24T00:05:47Z",
84    "updated_at": "2024-01-24T00:05:47Z",
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_d33cf192bd1947cca390e3842621ea8f",
95    "created_at": "2024-01-24T00:05:48Z",
96    "updated_at": "2024-01-24T00:05:48Z",
97    "date_advance": 0,
98    "integrated_form": "none",
99    "label_date": "2024-01-24T00:05:48Z",
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/e887f23d5484034c05a7634f4c1617945e.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_eeb032afda0546898a29814903a3330f",
113      "object": "Rate",
114      "created_at": "2024-01-24T00:05:47Z",
115      "updated_at": "2024-01-24T00:05:47Z",
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_a76316cb113f4779adddd86cae7c8008",
131      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
132    },
133    {
134      "id": "rate_4278234a11e4480daaf4f385ee56de74",
135      "object": "Rate",
136      "created_at": "2024-01-24T00:05:47Z",
137      "updated_at": "2024-01-24T00:05:47Z",
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_a76316cb113f4779adddd86cae7c8008",
153      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
154    },
155    {
156      "id": "rate_3682234a6c724f38ac06919651071676",
157      "object": "Rate",
158      "created_at": "2024-01-24T00:05:47Z",
159      "updated_at": "2024-01-24T00:05:47Z",
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_a76316cb113f4779adddd86cae7c8008",
175      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
176    },
177    {
178      "id": "rate_c35c6e7b71b745b0a4b4545a93d011b7",
179      "object": "Rate",
180      "created_at": "2024-01-24T00:05:47Z",
181      "updated_at": "2024-01-24T00:05:47Z",
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_a76316cb113f4779adddd86cae7c8008",
197      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
198    },
199    {
200      "id": "rate_4c638f260a6c4747981a3960db495d82",
201      "object": "Rate",
202      "created_at": "2024-01-24T00:05:47Z",
203      "updated_at": "2024-01-24T00:05:47Z",
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_a76316cb113f4779adddd86cae7c8008",
219      "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
220    }
221  ],
222  "refund_status": null,
223  "scan_form": null,
224  "selected_rate": {
225    "id": "rate_3682234a6c724f38ac06919651071676",
226    "object": "Rate",
227    "created_at": "2024-01-24T00:05:48Z",
228    "updated_at": "2024-01-24T00:05:48Z",
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_a76316cb113f4779adddd86cae7c8008",
244    "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
245  },
246  "tracker": {
247    "id": "trk_6a77d0aa61ca487c83a84b750a068a52",
248    "object": "Tracker",
249    "mode": "test",
250    "tracking_code": "9434600207552011812534",
251    "status": "unknown",
252    "status_detail": "unknown",
253    "created_at": "2024-01-24T00:05:48Z",
254    "updated_at": "2024-01-24T00:05:48Z",
255    "signed_by": null,
256    "weight": null,
257    "est_delivery_date": null,
258    "shipment_id": "shp_a76316cb113f4779adddd86cae7c8008",
259    "carrier": "USPS",
260    "tracking_details": [],
261    "fees": [],
262    "carrier_detail": null,
263    "public_url": "https://track.easypost.com/djE6dHJrXzZhNzdkMGFhNjFjYTQ4N2M4M2E4NGI3NTBhMDY4YTUy"
264  },
265  "to_address": {
266    "id": "adr_5334b436ba4c11eeb963ac1f6bc53342",
267    "object": "Address",
268    "created_at": "2024-01-24T00:05:47+00:00",
269    "updated_at": "2024-01-24T00:05:47+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_5336fc74ba4c11ee8c01ac1f6bc539ae",
305    "object": "Address",
306    "created_at": "2024-01-24T00:05:47+00:00",
307    "updated_at": "2024-01-24T00:05:47+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_5334b436ba4c11eeb963ac1f6bc53342",
327    "object": "Address",
328    "created_at": "2024-01-24T00:05:47+00:00",
329    "updated_at": "2024-01-24T00:05:47+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  "id": "shp_a76316cb113f4779adddd86cae7c8008",
380  "object": "Shipment"
381}

Retrieve all EndShippers

List the EndShippers that have been created.

Request Parameters

after_id
i.e. es_...
Optional pagination parameter. Only records created after the given ID will be included. May not be used with before_id.
page_size
i.e. 20
The number of records to return on each page. The maximum value is 100, and default is 20.
GET /end_shippers
1curl -X GET "https://api.easypost.com/v2/end_shippers?page_size=5" \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "end_shippers": [
3    {
4      "id": "es_4e6fc3267bb14aab926fda9e5a764b4b",
5      "object": "EndShipper",
6      "mode": "test",
7      "created_at": "2022-10-17T17:16:53+00:00",
8      "updated_at": "2022-10-17T17:16:53+00:00",
9      "name": "FOO BAR",
10      "company": "BAZ",
11      "street1": "164 TOWNSEND ST UNIT 1",
12      "street2": null,
13      "city": "SAN FRANCISCO",
14      "state": "CA",
15      "zip": "94107-1990",
16      "country": "US",
17      "phone": "555 555-5555",
18      "email": "FOO@EXAMPLE.COM"
19    }
20  ],
21  "has_more": true
22}

Retrieve an EndShipper

Similar to retrieving a list of EndShippers, you can retrieve an individual EndShipper.

GET /end_shippers/:id
1curl -X GET https://api.easypost.com/v2/end_shippers/es_... \
2  -u "EASYPOST_API_KEY":
Response
1{
2  "id": "es_4377f46538594bf7a99ee851e3f6902d",
3  "object": "EndShipper",
4  "mode": "test",
5  "created_at": "2024-01-24T00:05:45+00:00",
6  "updated_at": "2024-01-24T00:05:45+00:00",
7  "name": "FOO BAR",
8  "company": "BAZ",
9  "street1": "164 TOWNSEND ST UNIT 1",
10  "street2": null,
11  "city": "SAN FRANCISCO",
12  "state": "CA",
13  "zip": "94107-1990",
14  "country": "US",
15  "phone": "555 555-5555",
16  "email": "FOO@EXAMPLE.COM"
17}

Update an EndShipper

An EndShipper object may be updated using the EndShipper API. All required fields for creating an EndShipper are required in an update request. Partial updates are not supported.

Request Parameters

name
i.e. Hiro Protagonist
Name of responsible person (conditionally required)
company
i.e. EasyPost
Name of responsible company (conditionally required)
street1
i.e. 417 Montgomery St
First line of the address
street2
i.e. Floor 5
Second line of the address (optional)
city
i.e. San Francisco
City the address is located in
state
i.e. CA
State the address is located in
zip
i.e. 94104
ZIP or postal code the address is located in
country
i.e. US
Country code the address is located in. Must be "US" for EndShippers.
phone
i.e. 415-123-4567
Phone number to reach the person or organization
email
i.e. example@example.com
Email to reach the person or organization
PUT /end_shippers/:id
1curl -X PUT https://api.easypost.com/v2/end_shippers/es_... \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "address": {
6      "name": "NEW NAME",
7      "company": "BAZ",
8      "street1": "164 TOWNSEND STREET UNIT 1",
9      "street2": "UNIT 1",
10      "city": "SAN FRANCISCO",
11      "state": "CA",
12      "zip": "94107",
13      "country": "US",
14      "phone": "555-555-5555",
15      "email": "FOO@EXAMPLE.COM"
16    }
17  }'
Response
1{
2  "id": "es_f5ecda57a5aa4c4d9fe5e831366a3913",
3  "object": "EndShipper",
4  "mode": "test",
5  "created_at": "2024-01-24T00:05:46+00:00",
6  "updated_at": "2024-01-24T00:05:46+00:00",
7  "name": "NEW NAME",
8  "company": "BAZ",
9  "street1": "164 TOWNSEND ST UNIT 1",
10  "street2": "",
11  "city": "SAN FRANCISCO",
12  "state": "CA",
13  "zip": "94107-1990",
14  "country": "US",
15  "phone": "555-555-5555",
16  "email": "FOO@EXAMPLE.COM"
17}