Pagination
Most "retrieve all" responses from EasyPost are paginated.
Records are returned in descending order (most recent first), and the has_more attribute indicates whether or not additional pages can be requested.
The request accepts a variety of parameters which can be used to modify the scope.
The recommended way of paginating is to use either the before_id/after_id or start_datetime/end_datetime parameters to specify where the next page begins.
You can also use the optional page_size parameter to specify how many records you would like per page. We limit the number of records per page to 100, and most endpoints default to 20.
Support for these parameters vary by endpoint.
If you need to retrieve a successive page when the has_more key is present, make another "retrieve all" request and set the before_id to the ID of the last item returned.
For example, let's say you have 140 Shipment objects and are trying to interact with all of them.
If you make a call to retrieve all Shipments with the page_size set to 20, you would need to loop through 7 pages, each with 20 results.
To get to the next page of results, you would need to set before_id to the response['shipments'][19]['id'].
You would continue to request each additional page while specifying the id of the last Shipment of the previous request until the has_more attribute is false, indicating that all results have been retrieved.
Request Parameters
collection
i.e. shipments
A collection that contains a results page
page_size
i.e. 30
The number of records to return on each page. The maximum value is 100, and default is 20.
Paginate shipment objects
1# Get first page of results
2curl -X GET "https://api.easypost.com/v2/shipments?page_size=5" \
3 -u "EASYPOST_API_KEY":
4
5# Provide the ID of the last element of the previous page in the before_id param
6curl -X GET "https://api.easypost.com/v2/shipments?page_size=5&before_id=shp_..." \
7 -u "EASYPOST_API_KEY":Response
1{
2 "shipments": [
3 {
4 "id": "shp_eeefedc2fed747cbbfe36cc57912de38",
5 "created_at": "2025-05-09T20:38:26Z",
6 "is_return": false,
7 "messages": [],
8 "mode": "test",
9 "options": {
10 "currency": "USD",
11 "payment": {
12 "type": "SENDER"
13 },
14 "date_advance": 0
15 },
16 "reference": null,
17 "status": "unknown",
18 "tracking_code": "9405500208303109884045",
19 "updated_at": "2025-05-09T20:38:46Z",
20 "batch_id": "batch_a4009ed84d1549378d45f46c177ee3b3",
21 "batch_status": "postage_purchased",
22 "batch_message": null,
23 "customs_info": {
24 "id": "cstinfo_25122162ad6f4ca69e5674735876e000",
25 "object": "CustomsInfo",
26 "created_at": "2025-05-09T20:38:26Z",
27 "updated_at": "2025-05-09T20:38:26Z",
28 "contents_explanation": "",
29 "contents_type": "merchandise",
30 "customs_certify": true,
31 "customs_signer": "Steve Brule",
32 "eel_pfc": "NOEEI 30.37(a)",
33 "non_delivery_option": "return",
34 "restriction_comments": null,
35 "restriction_type": "none",
36 "mode": "test",
37 "declaration": null,
38 "customs_items": [
39 {
40 "id": "cstitem_7cd9d14b9bf448cd98ce1b158ec59fc7",
41 "object": "CustomsItem",
42 "created_at": "2025-05-09T20:38:26Z",
43 "updated_at": "2025-05-09T20:38:26Z",
44 "description": "T-shirt",
45 "hs_tariff_number": "123456",
46 "origin_country": "US",
47 "quantity": 1,
48 "value": "10.0",
49 "weight": 5.0,
50 "code": "123",
51 "mode": "test",
52 "manufacturer": null,
53 "currency": null,
54 "eccn": null,
55 "printed_commodity_identifier": null
56 }
57 ]
58 },
59 "from_address": {
60 "id": "adr_8eb88cfb2d1511f093c4ac1f6bc539ae",
61 "object": "Address",
62 "created_at": "2025-05-09T20:38:26+00:00",
63 "updated_at": "2025-05-09T20:38:26+00:00",
64 "name": "EasyPost",
65 "company": null,
66 "street1": "417 Montgomery Street",
67 "street2": "5th Floor",
68 "city": "San Francisco",
69 "state": "CA",
70 "zip": "94104",
71 "country": "US",
72 "phone": "4153334445",
73 "email": "support@easypost.com",
74 "mode": "test",
75 "carrier_facility": null,
76 "residential": null,
77 "federal_tax_id": null,
78 "state_tax_id": null,
79 "verifications": {}
80 },
81 "insurance": null,
82 "order_id": null,
83 "parcel": {
84 "id": "prcl_a5943f0a8cf343db94596c29173884ea",
85 "object": "Parcel",
86 "created_at": "2025-05-09T20:38:26Z",
87 "updated_at": "2025-05-09T20:38:26Z",
88 "length": 20.2,
89 "width": 10.9,
90 "height": 5.0,
91 "predefined_package": null,
92 "weight": 65.9,
93 "mode": "test"
94 },
95 "postage_label": {
96 "object": "PostageLabel",
97 "id": "pl_46b14e2a694d4e51b7848d0c0253de10",
98 "created_at": "2025-05-09T20:38:46Z",
99 "updated_at": "2025-05-09T20:38:46Z",
100 "date_advance": 0,
101 "integrated_form": "none",
102 "label_date": "2025-05-09T20:38:46Z",
103 "label_resolution": 300,
104 "label_size": "4x6",
105 "label_type": "default",
106 "label_file_type": "image/png",
107 "label_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/20250509/e84aa1236dfe714e43b7ba9b3181e810ac.png",
108 "label_pdf_url": null,
109 "label_zpl_url": null,
110 "label_epl2_url": null,
111 "label_file": null
112 },
113 "rates": [
114 {
115 "id": "rate_2dec153687ba44c19cd0aed677598413",
116 "object": "Rate",
117 "created_at": "2025-05-09T20:38:46Z",
118 "updated_at": "2025-05-09T20:38:46Z",
119 "mode": "test",
120 "service": "Express",
121 "carrier": "USPS",
122 "rate": "51.20",
123 "currency": "USD",
124 "retail_rate": "59.25",
125 "retail_currency": "USD",
126 "list_rate": "51.20",
127 "list_currency": "USD",
128 "billing_type": "easypost",
129 "delivery_days": 2,
130 "delivery_date": null,
131 "delivery_date_guaranteed": false,
132 "est_delivery_days": 2,
133 "shipment_id": "shp_eeefedc2fed747cbbfe36cc57912de38",
134 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
135 },
136 {
137 "id": "rate_9c5e9c646272483e94f1a518d5a89800",
138 "object": "Rate",
139 "created_at": "2025-05-09T20:38:46Z",
140 "updated_at": "2025-05-09T20:38:46Z",
141 "mode": "test",
142 "service": "Priority",
143 "carrier": "USPS",
144 "rate": "11.01",
145 "currency": "USD",
146 "retail_rate": "15.40",
147 "retail_currency": "USD",
148 "list_rate": "11.01",
149 "list_currency": "USD",
150 "billing_type": "easypost",
151 "delivery_days": 2,
152 "delivery_date": null,
153 "delivery_date_guaranteed": false,
154 "est_delivery_days": 2,
155 "shipment_id": "shp_eeefedc2fed747cbbfe36cc57912de38",
156 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
157 },
158 {
159 "id": "rate_0cfd20d81c784e15b760d45f431d9a91",
160 "object": "Rate",
161 "created_at": "2025-05-09T20:38:46Z",
162 "updated_at": "2025-05-09T20:38:46Z",
163 "mode": "test",
164 "service": "GroundAdvantage",
165 "carrier": "USPS",
166 "rate": "8.20",
167 "currency": "USD",
168 "retail_rate": "13.85",
169 "retail_currency": "USD",
170 "list_rate": "9.74",
171 "list_currency": "USD",
172 "billing_type": "easypost",
173 "delivery_days": 3,
174 "delivery_date": null,
175 "delivery_date_guaranteed": false,
176 "est_delivery_days": 3,
177 "shipment_id": "shp_eeefedc2fed747cbbfe36cc57912de38",
178 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
179 }
180 ],
181 "refund_status": null,
182 "scan_form": null,
183 "selected_rate": {
184 "id": "rate_9c5e9c646272483e94f1a518d5a89800",
185 "object": "Rate",
186 "created_at": "2025-05-09T20:38:46Z",
187 "updated_at": "2025-05-09T20:38:46Z",
188 "mode": "test",
189 "service": "Priority",
190 "carrier": "USPS",
191 "rate": "11.01",
192 "currency": "USD",
193 "retail_rate": "15.40",
194 "retail_currency": "USD",
195 "list_rate": "11.01",
196 "list_currency": "USD",
197 "billing_type": "easypost",
198 "delivery_days": 2,
199 "delivery_date": null,
200 "delivery_date_guaranteed": false,
201 "est_delivery_days": 2,
202 "shipment_id": "shp_eeefedc2fed747cbbfe36cc57912de38",
203 "carrier_account_id": "ca_9685a1198a75477885a3cdca37559bac"
204 },
205 "tracker": {
206 "id": "trk_56aff5f7e5fd48eca0a119c107ad82b1",
207 "object": "Tracker",
208 "mode": "test",
209 "tracking_code": "9405500208303109884045",
210 "status": "pre_transit",
211 "status_detail": "status_update",
212 "created_at": "2025-05-09T20:38:46Z",
213 "updated_at": "2025-05-09T20:38:47Z",
214 "signed_by": null,
215 "weight": null,
216 "est_delivery_date": "2025-05-09T20:38:47Z",
217 "shipment_id": "shp_eeefedc2fed747cbbfe36cc57912de38",
218 "carrier": "USPS",
219 "tracking_details": [
220 {
221 "object": "TrackingDetail",
222 "message": "Pre-Shipment Info Sent to USPS",
223 "description": "",
224 "status": "pre_transit",
225 "status_detail": "status_update",
226 "datetime": "2025-04-09T20:38:47Z",
227 "source": "USPS",
228 "carrier_code": "",
229 "tracking_location": {
230 "object": "TrackingLocation",
231 "city": null,
232 "state": null,
233 "country": null,
234 "zip": null
235 },
236 "est_delivery_date": null
237 },
238 {
239 "object": "TrackingDetail",
240 "message": "Shipping Label Created",
241 "description": "",
242 "status": "pre_transit",
243 "status_detail": "status_update",
244 "datetime": "2025-04-10T09:15:47Z",
245 "source": "USPS",
246 "carrier_code": "",
247 "tracking_location": {
248 "object": "TrackingLocation",
249 "city": "HOUSTON",
250 "state": "TX",
251 "country": null,
252 "zip": "77063"
253 },
254 "est_delivery_date": null
255 }
256 ],
257 "fees": [],
258 "carrier_detail": {
259 "object": "CarrierDetail",
260 "service": "First-Class Package Service",
261 "container_type": null,
262 "est_delivery_date_local": null,
263 "est_delivery_time_local": null,
264 "origin_location": "HOUSTON TX, 77001",
265 "origin_tracking_location": {
266 "object": "TrackingLocation",
267 "city": "HOUSTON",
268 "state": "TX",
269 "country": null,
270 "zip": "77063"
271 },
272 "destination_location": "CHARLESTON SC, 29401",
273 "destination_tracking_location": null,
274 "guaranteed_delivery_date": null,
275 "alternate_identifier": null,
276 "initial_delivery_attempt": null
277 },
278 "public_url": "https://track.easypost.com/djE6dHJrXzU2YWZmNWY3ZTVmZDQ4ZWNhMGExMTljMTA3YWQ4MmIx"
279 },
280 "to_address": {
281 "id": "adr_8eb6ce262d1511f0ac32ac1f6bc539aa",
282 "object": "Address",
283 "created_at": "2025-05-09T20:38:26+00:00",
284 "updated_at": "2025-05-09T20:38:46+00:00",
285 "name": "DR. STEVE BRULE",
286 "company": null,
287 "street1": "179 N HARBOR DR",
288 "street2": null,
289 "city": "REDONDO BEACH",
290 "state": "CA",
291 "zip": "90277-2506",
292 "country": "US",
293 "phone": "8573875756",
294 "email": "DR_STEVE_BRULE@GMAIL.COM",
295 "mode": "test",
296 "carrier_facility": null,
297 "residential": false,
298 "federal_tax_id": null,
299 "state_tax_id": null,
300 "verifications": {
301 "zip4": {
302 "success": true,
303 "errors": [],
304 "details": null
305 },
306 "delivery": {
307 "success": true,
308 "errors": [],
309 "details": {
310 "latitude": 33.8436,
311 "longitude": -118.39177,
312 "time_zone": "America/Los_Angeles"
313 }
314 }
315 }
316 },
317 "usps_zone": 4,
318 "return_address": {
319 "id": "adr_8eb88cfb2d1511f093c4ac1f6bc539ae",
320 "object": "Address",
321 "created_at": "2025-05-09T20:38:26+00:00",
322 "updated_at": "2025-05-09T20:38:26+00:00",
323 "name": "EasyPost",
324 "company": null,
325 "street1": "417 Montgomery Street",
326 "street2": "5th Floor",
327 "city": "San Francisco",
328 "state": "CA",
329 "zip": "94104",
330 "country": "US",
331 "phone": "4153334445",
332 "email": "support@easypost.com",
333 "mode": "test",
334 "carrier_facility": null,
335 "residential": null,
336 "federal_tax_id": null,
337 "state_tax_id": null,
338 "verifications": {}
339 },
340 "buyer_address": {
341 "id": "adr_8eb6ce262d1511f0ac32ac1f6bc539aa",
342 "object": "Address",
343 "created_at": "2025-05-09T20:38:26+00:00",
344 "updated_at": "2025-05-09T20:38:46+00:00",
345 "name": "DR. STEVE BRULE",
346 "company": null,
347 "street1": "179 N HARBOR DR",
348 "street2": null,
349 "city": "REDONDO BEACH",
350 "state": "CA",
351 "zip": "90277-2506",
352 "country": "US",
353 "phone": "8573875756",
354 "email": "DR_STEVE_BRULE@GMAIL.COM",
355 "mode": "test",
356 "carrier_facility": null,
357 "residential": false,
358 "federal_tax_id": null,
359 "state_tax_id": null,
360 "verifications": {
361 "zip4": {
362 "success": true,
363 "errors": [],
364 "details": null
365 },
366 "delivery": {
367 "success": true,
368 "errors": [],
369 "details": {
370 "latitude": 33.8436,
371 "longitude": -118.39177,
372 "time_zone": "America/Los_Angeles"
373 }
374 }
375 }
376 },
377 "forms": [],
378 "fees": [
379 {
380 "object": "Fee",
381 "type": "PostageFee",
382 "amount": "11.01000",
383 "charged": true,
384 "refunded": false
385 }
386 ],
387 "object": "Shipment"
388 }
389 ],
390 "has_more": false
391}