Luma
The Luma API enables shippers to manage and execute rate shopping rules configured within the EasyPost Dashboard. By leveraging predefined rulesets, Luma automates the rate selection process based on criteria such as transit time, cost, carrier preferences, and confidence levels.
Endpoints
Before using the Luma API, rate shopping rules must be defined. These rules determine how rates are selected based on specific criteria. Work with an EasyPost Luma contact to configure rulesets that may include:
- Days in Transit: Maximum number of transit days desired.
- Confidence: Confidence level for delivery within the specified Days in Transit.
- Maximum Cost: Maximum dollar amount allowed for the shipment.
- Included Carriers: Array of carriers eligible for selection.
Once rulesets are established, they are configured on the backend by an EasyPost Account Manager.
A shipment object must be created with the following details before calling the Luma API:
from_address: The origin address.to_address: The destination address.parceldetails: Package weight, dimensions, and other relevant information.
This step returns all available carrier rates associated with the EasyPost account.
After creating the shipment, pass the shipment_id into the Luma API to purchase a label based on the predefined ruleset.
Request Parameters
ruleset_name
REQUIRED
i.e. "required_deliver_by_date"
The name of the predefined ruleset to apply.
planned_ship_date
REQUIRED
i.e. "YYYY-MM-DD"
The date the shipment is expected to enter the mailstream, crucial for accurate transit time estimates.
deliver_by_date
i.e. "YYYY-MM-DD"
The date the shipment should be delivered.
POST /
1curl -X POST https://api.easypost.com/v2/shipments/shp_.../luma \
2 -u "EASYPOST_API_KEY": \
3 -H 'Content-Type: application/json' \
4 -d '{
5 "ruleset_name": "ruleset_name",
6 "planned_ship_date": "YYYY-MM-DD"
7 "deliver_by_date": "YYYY-MM-DD"
8 }'Response
1{
2 "id": "shp_bfd562faaf674045930c81e750679f5d",
3 "object": "Shipment",
4 "mode": "test",
5 "reference": null,
6 "to_address": {
7 "id": "adr_2a1743b7e40411ef9106ac1f6bc53342",
8 "object": "Address",
9 "created_at": "2025-02-05T21:00:00+00:00",
10 "updated_at": "2025-02-05T21:00:00+00:00",
11 "name": "Archmage Luma",
12 "company": null,
13 "street1": "1234 Adam Irwin Way",
14 "street2": null,
15 "city": "Campbell",
16 "state": "CA",
17 "zip": "95008",
18 "country": "US",
19 "phone": null,
20 "email": null,
21 "mode": "test",
22 "carrier_facility": null,
23 "residential": null,
24 "federal_tax_id": null,
25 "state_tax_id": null,
26 "verifications": {}
27 },
28 "from_address": {
29 "id": "adr_2a1972ffe40411ef964fac1f6bc539aa",
30 "object": "Address",
31 "created_at": "2025-02-05T21:00:00+00:00",
32 "updated_at": "2025-02-05T21:00:00+00:00",
33 "name": "Golf Gear - East",
34 "company": null,
35 "street1": "4823 55th Ave",
36 "street2": null,
37 "city": "Flushing",
38 "state": "NY",
39 "zip": "11378",
40 "country": "US",
41 "phone": null,
42 "email": null,
43 "mode": "test",
44 "carrier_facility": null,
45 "residential": null,
46 "federal_tax_id": null,
47 "state_tax_id": null,
48 "verifications": {}
49 },
50 "return_address": {
51 "id": "adr_2a1972ffe40411ef964fac1f6bc539aa",
52 "object": "Address",
53 "created_at": "2025-02-05T21:00:00+00:00",
54 "updated_at": "2025-02-05T21:00:00+00:00",
55 "name": "Golf Gear - East",
56 "company": null,
57 "street1": "4823 55th Ave",
58 "street2": null,
59 "city": "Flushing",
60 "state": "NY",
61 "zip": "11378",
62 "country": "US",
63 "phone": null,
64 "email": null,
65 "mode": "test",
66 "carrier_facility": null,
67 "residential": null,
68 "federal_tax_id": null,
69 "state_tax_id": null,
70 "verifications": {}
71 },
72 "buyer_address": {
73 "id": "adr_2a1743b7e40411ef9106ac1f6bc53342",
74 "object": "Address",
75 "created_at": "2025-02-05T21:00:00+00:00",
76 "updated_at": "2025-02-05T21:00:00+00:00",
77 "name": "Archmage Luma",
78 "company": null,
79 "street1": "1234 Adam Irwin Way",
80 "street2": null,
81 "city": "Campbell",
82 "state": "CA",
83 "zip": "95008",
84 "country": "US",
85 "phone": null,
86 "email": null,
87 "mode": "test",
88 "carrier_facility": null,
89 "residential": null,
90 "federal_tax_id": null,
91 "state_tax_id": null,
92 "verifications": {}
93 },
94 "parcel": {
95 "id": "prcl_8a879698fbf749c0969bc917eea122c2",
96 "object": "Parcel",
97 "created_at": "2025-02-05T21:00:00Z",
98 "updated_at": "2025-02-05T21:00:00Z",
99 "length": 20.2,
100 "width": 10.9,
101 "height": 10.0,
102 "predefined_package": null,
103 "weight": 32.0,
104 "mode": "test"
105 },
106 "customs_info": null,
107 "scan_form": null,
108 "forms": [],
109 "insurance": null,
110 "rates": [
111 {
112 "id": "rate_878246b64dfc4acdaae144632071ebbf",
113 "object": "Rate",
114 "created_at": "2025-02-05T21:00:05Z",
115 "updated_at": "2025-02-05T21:00:05Z",
116 "mode": "test",
117 "service": "Express",
118 "carrier": "USPS",
119 "rate": "135.45",
120 "currency": "USD",
121 "retail_rate": "155.70",
122 "retail_currency": "USD",
123 "list_rate": "135.45",
124 "list_currency": "USD",
125 "billing_type": "easypost",
126 "delivery_days": 1,
127 "delivery_date": null,
128 "delivery_date_guaranteed": false,
129 "est_delivery_days": 1,
130 "shipment_id": "shp_bfd562faaf674045930c81e750679f5d",
131 "carrier_account_id": "ca_63f2fd4a402f4a23baeb1ba30f19b6e5"
132 },
133 {
134 "id": "rate_c5ea42853ee34db5a3b739a30c1d1e7d",
135 "object": "Rate",
136 "created_at": "2025-02-05T21:00:05Z",
137 "updated_at": "2025-02-05T21:00:05Z",
138 "mode": "test",
139 "service": "Priority",
140 "carrier": "USPS",
141 "rate": "41.44",
142 "currency": "USD",
143 "retail_rate": "72.90",
144 "retail_currency": "USD",
145 "list_rate": "51.81",
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_bfd562faaf674045930c81e750679f5d",
153 "carrier_account_id": "ca_63f2fd4a402f4a23baeb1ba30f19b6e5"
154 },
155 {
156 "id": "rate_3041c849fcfb4eca8e7140ce8ac68ac2",
157 "object": "Rate",
158 "created_at": "2025-02-05T21:00:05Z",
159 "updated_at": "2025-02-05T21:00:05Z",
160 "mode": "test",
161 "service": "GroundAdvantage",
162 "carrier": "USPS",
163 "rate": "23.85",
164 "currency": "USD",
165 "retail_rate": "48.00",
166 "retail_currency": "USD",
167 "list_rate": "24.98",
168 "list_currency": "USD",
169 "billing_type": "easypost",
170 "delivery_days": 5,
171 "delivery_date": null,
172 "delivery_date_guaranteed": false,
173 "est_delivery_days": 5,
174 "shipment_id": "shp_bfd562faaf674045930c81e750679f5d",
175 "carrier_account_id": "ca_63f2fd4a402f4a23baeb1ba30f19b6e5"
176 },
177 {
178 "id": "rate_ecc1a08e97e349dc83645663e02e8ce6",
179 "object": "Rate",
180 "created_at": "2025-02-05T21:00:05Z",
181 "updated_at": "2025-02-05T21:00:05Z",
182 "mode": "test",
183 "service": "NextDayAir",
184 "carrier": "UPSDAP",
185 "rate": "94.45",
186 "currency": "USD",
187 "retail_rate": "266.88",
188 "retail_currency": "USD",
189 "list_rate": "311.62",
190 "list_currency": "USD",
191 "billing_type": "easypost",
192 "delivery_days": 1,
193 "delivery_date": "2025-02-06T10:30:00Z",
194 "delivery_date_guaranteed": true,
195 "est_delivery_days": 1,
196 "shipment_id": "shp_bfd562faaf674045930c81e750679f5d",
197 "carrier_account_id": "ca_55e6449f04bb44529fd5d7bc373cbde1"
198 },
199 {
200 "id": "rate_9de47a58578943f692779ba1ef649db0",
201 "object": "Rate",
202 "created_at": "2025-02-05T21:00:05Z",
203 "updated_at": "2025-02-05T21:00:05Z",
204 "mode": "test",
205 "service": "NextDayAirEarlyAM",
206 "carrier": "UPSDAP",
207 "rate": "124.45",
208 "currency": "USD",
209 "retail_rate": "302.35",
210 "retail_currency": "USD",
211 "list_rate": "347.10",
212 "list_currency": "USD",
213 "billing_type": "easypost",
214 "delivery_days": 1,
215 "delivery_date": "2025-02-06T08:30:00Z",
216 "delivery_date_guaranteed": true,
217 "est_delivery_days": 1,
218 "shipment_id": "shp_bfd562faaf674045930c81e750679f5d",
219 "carrier_account_id": "ca_55e6449f04bb44529fd5d7bc373cbde1"
220 },
221 {
222 "id": "rate_3a017a1f045a44088baba60cacaacae4",
223 "object": "Rate",
224 "created_at": "2025-02-05T21:00:05Z",
225 "updated_at": "2025-02-05T21:00:05Z",
226 "mode": "test",
227 "service": "NextDayAirSaver",
228 "carrier": "UPSDAP",
229 "rate": "87.91",
230 "currency": "USD",
231 "retail_rate": "252.70",
232 "retail_currency": "USD",
233 "list_rate": "284.52",
234 "list_currency": "USD",
235 "billing_type": "easypost",
236 "delivery_days": 1,
237 "delivery_date": "2025-02-06T23:00:00Z",
238 "delivery_date_guaranteed": true,
239 "est_delivery_days": 1,
240 "shipment_id": "shp_bfd562faaf674045930c81e750679f5d",
241 "carrier_account_id": "ca_55e6449f04bb44529fd5d7bc373cbde1"
242 },
243 {
244 "id": "rate_5c552ee17b764ebe8b3e040e23acc161",
245 "object": "Rate",
246 "created_at": "2025-02-05T21:00:05Z",
247 "updated_at": "2025-02-05T21:00:05Z",
248 "mode": "test",
249 "service": "2ndDayAir",
250 "carrier": "UPSDAP",
251 "rate": "52.98",
252 "currency": "USD",
253 "retail_rate": "161.42",
254 "retail_currency": "USD",
255 "list_rate": "189.48",
256 "list_currency": "USD",
257 "billing_type": "easypost",
258 "delivery_days": 2,
259 "delivery_date": "2025-02-07T23:00:00Z",
260 "delivery_date_guaranteed": false,
261 "est_delivery_days": 2,
262 "shipment_id": "shp_bfd562faaf674045930c81e750679f5d",
263 "carrier_account_id": "ca_55e6449f04bb44529fd5d7bc373cbde1"
264 },
265 {
266 "id": "rate_00697bb80a6a4690a4adc1fa821d0549",
267 "object": "Rate",
268 "created_at": "2025-02-05T21:00:05Z",
269 "updated_at": "2025-02-05T21:00:05Z",
270 "mode": "test",
271 "service": "2ndDayAirAM",
272 "carrier": "UPSDAP",
273 "rate": "60.79",
274 "currency": "USD",
275 "retail_rate": "188.62",
276 "retail_currency": "USD",
277 "list_rate": "218.38",
278 "list_currency": "USD",
279 "billing_type": "easypost",
280 "delivery_days": 2,
281 "delivery_date": "2025-02-07T10:30:00Z",
282 "delivery_date_guaranteed": true,
283 "est_delivery_days": 2,
284 "shipment_id": "shp_bfd562faaf674045930c81e750679f5d",
285 "carrier_account_id": "ca_55e6449f04bb44529fd5d7bc373cbde1"
286 },
287 {
288 "id": "rate_8d6d3b28b62d43e8bf137f7f63588807",
289 "object": "Rate",
290 "created_at": "2025-02-05T21:00:05Z",
291 "updated_at": "2025-02-05T21:00:05Z",
292 "mode": "test",
293 "service": "3DaySelect",
294 "carrier": "UPSDAP",
295 "rate": "38.19",
296 "currency": "USD",
297 "retail_rate": "117.35",
298 "retail_currency": "USD",
299 "list_rate": "144.22",
300 "list_currency": "USD",
301 "billing_type": "easypost",
302 "delivery_days": 3,
303 "delivery_date": "2025-02-10T23:00:00Z",
304 "delivery_date_guaranteed": false,
305 "est_delivery_days": 3,
306 "shipment_id": "shp_bfd562faaf674045930c81e750679f5d",
307 "carrier_account_id": "ca_55e6449f04bb44529fd5d7bc373cbde1"
308 },
309 {
310 "id": "rate_ec4000010aa74083bcf7af34d77cd69f",
311 "object": "Rate",
312 "created_at": "2025-02-05T21:00:05Z",
313 "updated_at": "2025-02-05T21:00:05Z",
314 "mode": "test",
315 "service": "Ground",
316 "carrier": "UPSDAP",
317 "rate": "24.02",
318 "currency": "USD",
319 "retail_rate": "48.72",
320 "retail_currency": "USD",
321 "list_rate": "35.25",
322 "list_currency": "USD",
323 "billing_type": "easypost",
324 "delivery_days": 5,
325 "delivery_date": "2025-02-12T23:00:00Z",
326 "delivery_date_guaranteed": false,
327 "est_delivery_days": 5,
328 "shipment_id": "shp_bfd562faaf674045930c81e750679f5d",
329 "carrier_account_id": "ca_55e6449f04bb44529fd5d7bc373cbde1"
330 },
331 {
332 "id": "rate_81be930fa6824faa9f75ce474db8c329",
333 "object": "Rate",
334 "created_at": "2025-02-05T21:00:05Z",
335 "updated_at": "2025-02-05T21:00:05Z",
336 "mode": "test",
337 "service": "SMART_POST",
338 "carrier": "FedExDefault",
339 "rate": "47.99",
340 "currency": "USD",
341 "retail_rate": null,
342 "retail_currency": null,
343 "list_rate": "47.99",
344 "list_currency": "USD",
345 "billing_type": "easypost",
346 "delivery_days": 6,
347 "delivery_date": null,
348 "delivery_date_guaranteed": false,
349 "est_delivery_days": 6,
350 "shipment_id": "shp_bfd562faaf674045930c81e750679f5d",
351 "carrier_account_id": "ca_0de5ae06741e4c30a828c4b826d04126"
352 },
353 {
354 "id": "rate_8c590b2c9f9f42fa8986b19e0180d5bd",
355 "object": "Rate",
356 "created_at": "2025-02-05T21:00:05Z",
357 "updated_at": "2025-02-05T21:00:05Z",
358 "mode": "test",
359 "service": "PRIORITY_OVERNIGHT",
360 "carrier": "FedExDefault",
361 "rate": "289.00",
362 "currency": "USD",
363 "retail_rate": null,
364 "retail_currency": null,
365 "list_rate": "289.00",
366 "list_currency": "USD",
367 "billing_type": "easypost",
368 "delivery_days": 1,
369 "delivery_date": "2025-02-06T10:30:00Z",
370 "delivery_date_guaranteed": true,
371 "est_delivery_days": 1,
372 "shipment_id": "shp_bfd562faaf674045930c81e750679f5d",
373 "carrier_account_id": "ca_0de5ae06741e4c30a828c4b826d04126"
374 },
375 {
376 "id": "rate_f6cba61f30714f7fb779b7b157c0c619",
377 "object": "Rate",
378 "created_at": "2025-02-05T21:00:05Z",
379 "updated_at": "2025-02-05T21:00:05Z",
380 "mode": "test",
381 "service": "STANDARD_OVERNIGHT",
382 "carrier": "FedExDefault",
383 "rate": "264.87",
384 "currency": "USD",
385 "retail_rate": null,
386 "retail_currency": null,
387 "list_rate": "264.87",
388 "list_currency": "USD",
389 "billing_type": "easypost",
390 "delivery_days": 1,
391 "delivery_date": "2025-02-06T17:00:00Z",
392 "delivery_date_guaranteed": true,
393 "est_delivery_days": 1,
394 "shipment_id": "shp_bfd562faaf674045930c81e750679f5d",
395 "carrier_account_id": "ca_0de5ae06741e4c30a828c4b826d04126"
396 },
397 {
398 "id": "rate_9a64fd048d644d8daaece83c92b49ae8",
399 "object": "Rate",
400 "created_at": "2025-02-05T21:00:05Z",
401 "updated_at": "2025-02-05T21:00:05Z",
402 "mode": "test",
403 "service": "FEDEX_2_DAY_AM",
404 "carrier": "FedExDefault",
405 "rate": "202.16",
406 "currency": "USD",
407 "retail_rate": null,
408 "retail_currency": null,
409 "list_rate": "202.16",
410 "list_currency": "USD",
411 "billing_type": "easypost",
412 "delivery_days": 2,
413 "delivery_date": "2025-02-07T10:30:00Z",
414 "delivery_date_guaranteed": true,
415 "est_delivery_days": 2,
416 "shipment_id": "shp_bfd562faaf674045930c81e750679f5d",
417 "carrier_account_id": "ca_0de5ae06741e4c30a828c4b826d04126"
418 },
419 {
420 "id": "rate_4fb6b986d5e242b39dcfd47bff29b74d",
421 "object": "Rate",
422 "created_at": "2025-02-05T21:00:05Z",
423 "updated_at": "2025-02-05T21:00:05Z",
424 "mode": "test",
425 "service": "FEDEX_GROUND",
426 "carrier": "FedExDefault",
427 "rate": "36.75",
428 "currency": "USD",
429 "retail_rate": null,
430 "retail_currency": null,
431 "list_rate": "36.75",
432 "list_currency": "USD",
433 "billing_type": "easypost",
434 "delivery_days": 5,
435 "delivery_date": "2025-02-12T23:59:00Z",
436 "delivery_date_guaranteed": true,
437 "est_delivery_days": 5,
438 "shipment_id": "shp_bfd562faaf674045930c81e750679f5d",
439 "carrier_account_id": "ca_0de5ae06741e4c30a828c4b826d04126"
440 }
441 ],
442 "selected_rate": {
443 "id": "rate_3a017a1f045a44088baba60cacaacae4",
444 "object": "Rate",
445 "created_at": "2025-02-05T21:01:36Z",
446 "updated_at": "2025-02-05T21:01:36Z",
447 "mode": "test",
448 "service": "NextDayAirSaver",
449 "carrier": "UPSDAP",
450 "rate": "87.91",
451 "currency": "USD",
452 "retail_rate": "252.70",
453 "retail_currency": "USD",
454 "list_rate": "284.52",
455 "list_currency": "USD",
456 "billing_type": "easypost",
457 "delivery_days": 1,
458 "delivery_date": "2025-02-06T23:00:00Z",
459 "delivery_date_guaranteed": true,
460 "est_delivery_days": 1,
461 "shipment_id": "shp_bfd562faaf674045930c81e750679f5d",
462 "carrier_account_id": "ca_55e6449f04bb44529fd5d7bc373cbde1"
463 },
464 "luma_info": {
465 "ai_results": [
466 {
467 "carrier": "USPS",
468 "meets_ruleset_requirements": false,
469 "predicted_deliver_by_date": "2025-02-11",
470 "predicted_deliver_days": 5,
471 "rate_id": "rate_878246b64dfc4acdaae144632071ebbf",
472 "rate_usd": "135.45",
473 "service": "Express"
474 },
475 {
476 "carrier": "USPS",
477 "meets_ruleset_requirements": false,
478 "predicted_deliver_by_date": "2025-02-12",
479 "predicted_deliver_days": 6,
480 "rate_id": "rate_c5ea42853ee34db5a3b739a30c1d1e7d",
481 "rate_usd": "41.44",
482 "service": "Priority"
483 },
484 {
485 "carrier": "USPS",
486 "meets_ruleset_requirements": false,
487 "predicted_deliver_by_date": "2025-02-13",
488 "predicted_deliver_days": 7,
489 "rate_id": "rate_3041c849fcfb4eca8e7140ce8ac68ac2",
490 "rate_usd": "23.85",
491 "service": "GroundAdvantage"
492 },
493 {
494 "carrier": "UPSDAP",
495 "meets_ruleset_requirements": true,
496 "predicted_deliver_by_date": "2025-02-07",
497 "predicted_deliver_days": 1,
498 "rate_id": "rate_ecc1a08e97e349dc83645663e02e8ce6",
499 "rate_usd": "94.45",
500 "service": "NextDayAir"
501 },
502 {
503 "carrier": "UPSDAP",
504 "meets_ruleset_requirements": true,
505 "predicted_deliver_by_date": "2025-02-10",
506 "predicted_deliver_days": 4,
507 "rate_id": "rate_9de47a58578943f692779ba1ef649db0",
508 "rate_usd": "124.45",
509 "service": "NextDayAirEarlyAM"
510 },
511 {
512 "carrier": "UPSDAP",
513 "meets_ruleset_requirements": true,
514 "predicted_deliver_by_date": "2025-02-10",
515 "predicted_deliver_days": 4,
516 "rate_id": "rate_3a017a1f045a44088baba60cacaacae4",
517 "rate_usd": "87.91",
518 "service": "NextDayAirSaver"
519 },
520 {
521 "carrier": "UPSDAP",
522 "meets_ruleset_requirements": false,
523 "predicted_deliver_by_date": "2025-02-11",
524 "predicted_deliver_days": 5,
525 "rate_id": "rate_5c552ee17b764ebe8b3e040e23acc161",
526 "rate_usd": "52.98",
527 "service": "2ndDayAir"
528 },
529 {
530 "carrier": "UPSDAP",
531 "meets_ruleset_requirements": false,
532 "predicted_deliver_by_date": "2025-02-11",
533 "predicted_deliver_days": 5,
534 "rate_id": "rate_00697bb80a6a4690a4adc1fa821d0549",
535 "rate_usd": "60.79",
536 "service": "2ndDayAirAM"
537 },
538 {
539 "carrier": "UPSDAP",
540 "meets_ruleset_requirements": false,
541 "predicted_deliver_by_date": "2025-02-12",
542 "predicted_deliver_days": 6,
543 "rate_id": "rate_8d6d3b28b62d43e8bf137f7f63588807",
544 "rate_usd": "38.19",
545 "service": "3DaySelect"
546 },
547 {
548 "carrier": "UPSDAP",
549 "meets_ruleset_requirements": false,
550 "predicted_deliver_by_date": "2025-02-14",
551 "predicted_deliver_days": 8,
552 "rate_id": "rate_ec4000010aa74083bcf7af34d77cd69f",
553 "rate_usd": "24.02",
554 "service": "Ground"
555 },
556 {
557 "carrier": "FedExDefault",
558 "meets_ruleset_requirements": false,
559 "predicted_deliver_by_date": "2025-02-15",
560 "predicted_deliver_days": 9,
561 "rate_id": "rate_81be930fa6824faa9f75ce474db8c329",
562 "rate_usd": "47.99",
563 "service": "SMART_POST"
564 },
565 {
566 "carrier": "FedExDefault",
567 "meets_ruleset_requirements": true,
568 "predicted_deliver_by_date": "2025-02-10",
569 "predicted_deliver_days": 4,
570 "rate_id": "rate_8c590b2c9f9f42fa8986b19e0180d5bd",
571 "rate_usd": "289.00",
572 "service": "PRIORITY_OVERNIGHT"
573 },
574 {
575 "carrier": "FedExDefault",
576 "meets_ruleset_requirements": true,
577 "predicted_deliver_by_date": "2025-02-10",
578 "predicted_deliver_days": 4,
579 "rate_id": "rate_f6cba61f30714f7fb779b7b157c0c619",
580 "rate_usd": "264.87",
581 "service": "STANDARD_OVERNIGHT"
582 },
583 {
584 "carrier": "FedExDefault",
585 "meets_ruleset_requirements": false,
586 "predicted_deliver_by_date": "2025-02-11",
587 "predicted_deliver_days": 5,
588 "rate_id": "rate_9a64fd048d644d8daaece83c92b49ae8",
589 "rate_usd": "202.16",
590 "service": "FEDEX_2_DAY_AM"
591 },
592 {
593 "carrier": "FedExDefault",
594 "meets_ruleset_requirements": false,
595 "predicted_deliver_by_date": "2025-02-13",
596 "predicted_deliver_days": 7,
597 "rate_id": "rate_4fb6b986d5e242b39dcfd47bff29b74d",
598 "rate_usd": "36.75",
599 "service": "FEDEX_GROUND"
600 }
601 ],
602 "matching_rule_idx": 0,
603 "ruleset_description": "Buy the cheapest rate that satisfies all of the following:\nRule 0\n - Deliver by user input day of deliver_by_date - Transit day confidence >= 90\nOtherwise buy the cheapest rate"
604 },
605 "postage_label": {
606 "object": "PostageLabel",
607 "id": "pl_340971cbfef442d2b69479abad916751",
608 "created_at": "2025-02-05T21:01:36Z",
609 "updated_at": "2025-02-05T21:01:37Z",
610 "date_advance": 0,
611 "integrated_form": "none",
612 "label_date": "2025-02-05T21:01:36Z",
613 "label_resolution": 200,
614 "label_size": "4x7",
615 "label_type": "default",
616 "label_file_type": "image/png",
617 "label_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/20250205/e82ceb24e620684ea7829d0f6866c2ba5f.png",
618 "label_pdf_url": null,
619 "label_zpl_url": null,
620 "label_epl2_url": null,
621 "label_file": null
622 },
623 "messages": [
624 {
625 "carrier": "DhlEcs",
626 "carrier_account_id": "ca_05d8d447abcb4993907c0c367390f100",
627 "type": "rate_error",
628 "message": "shipment.options.merchant_id is required"
629 }
630 ],
631 "options": {
632 "currency": "USD",
633 "payment": {
634 "type": "SENDER"
635 },
636 "date_advance": 0
637 },
638 "is_return": null,
639 "tracking_code": "1ZXXXXXXXXXXXXXXXX",
640 "usps_zone": 8,
641 "status": "unknown",
642 "tracker": {
643 "id": "trk_e656c26250b047abad274f8ae1db0fc3",
644 "object": "Tracker",
645 "mode": "test",
646 "tracking_code": "1ZXXXXXXXXXXXXXXXX",
647 "status": "unknown",
648 "status_detail": "unknown",
649 "created_at": "2025-02-05T21:01:37Z",
650 "updated_at": "2025-02-05T21:01:37Z",
651 "signed_by": null,
652 "weight": null,
653 "est_delivery_date": null,
654 "shipment_id": "shp_bfd562faaf674045930c81e750679f5d",
655 "carrier": "UPSDAP",
656 "tracking_details": [],
657 "fees": [],
658 "carrier_detail": null,
659 "public_url": "https://track.easypost.com/djE6dHJrX2U2NTZjMjYyNTBiMDQ3YWJhZDI3NGY4YWUxZGIwZmMz"
660 },
661 "fees": [
662 {
663 "object": "Fee",
664 "type": "LabelFee",
665 "amount": "0.00000",
666 "charged": true,
667 "refunded": false
668 },
669 {
670 "object": "Fee",
671 "type": "PostageFee",
672 "amount": "87.91000",
673 "charged": true,
674 "refunded": false
675 }
676 ],
677 "refund_status": null,
678 "batch_id": null,
679 "batch_status": null,
680 "batch_message": null,
681 "tax_identifiers": null,
682 "created_at": "2025-02-05T21:00:00Z",
683 "updated_at": "2025-02-05T21:01:37Z"
684}The response includes standard shipment purchase details along with a luma_info section, which provides insight into the ruleset logic used to select the final rate.
ruleset_description
string
Describes the logic used to select the rate.
matching_rule_idx
integer
The index position of the applied rule within the ruleset (starting from 0).
ai_results
array
List of all fetched rates and their evaluation against the ruleset
ai_results[].carrier
string
Carrier associated with the rate (e.g., USPS, FedEx).
ai_results[].service
string
Carrier service level used for the rate (e.g., Express, Ground).
ai_results[].rate_id
string
The ID of the specific rate.
ai_results[].rate_usd
string
Total cost of the rate in USD
ai_results[].predicted_deliver_by_date
string
Date the SmartRate AI predicts the package will be delivered.
ai_results[].predicted_deliver_days
integer
Number of calendar days SmartRate AI predicts for delivery, factoring in weekends and carrier operations
ai_results[].meets_ruleset_requirements
boolean
Indicates whether the rate meets the ruleset's transit time, cost, and carrier conditions.
Luma Info Object
{
"luma_info": {
"ai_results": [
{
"carrier": "USPS",
"meets_ruleset_requirements": false,
"predicted_deliver_by_date": "2025-02-11",
"predicted_deliver_days": 5,
"rate_id": "rate_878246b64dfc4acdaae144632071ebbf",
"rate_usd": "135.45",
"service": "Express"
},
{
"carrier": "USPS",
"meets_ruleset_requirements": false,
"predicted_deliver_by_date": "2025-02-12",
"predicted_deliver_days": 6,
"rate_id": "rate_c5ea42853ee34db5a3b739a30c1d1e7d",
"rate_usd": "41.44",
"service": "Priority"
},
{
"carrier": "USPS",
"meets_ruleset_requirements": false,
"predicted_deliver_by_date": "2025-02-13",
"predicted_deliver_days": 7,
"rate_id": "rate_3041c849fcfb4eca8e7140ce8ac68ac2",
"rate_usd": "23.85",
"service": "GroundAdvantage"
},
{
"carrier": "UPSDAP",
"meets_ruleset_requirements": true,
"predicted_deliver_by_date": "2025-02-07",
"predicted_deliver_days": 1,
"rate_id": "rate_ecc1a08e97e349dc83645663e02e8ce6",
"rate_usd": "94.45",
"service": "NextDayAir"
},
{
"carrier": "UPSDAP",
"meets_ruleset_requirements": true,
"predicted_deliver_by_date": "2025-02-10",
"predicted_deliver_days": 4,
"rate_id": "rate_9de47a58578943f692779ba1ef649db0",
"rate_usd": "124.45",
"service": "NextDayAirEarlyAM"
},
{
"carrier": "UPSDAP",
"meets_ruleset_requirements": true,
"predicted_deliver_by_date": "2025-02-10",
"predicted_deliver_days": 4,
"rate_id": "rate_3a017a1f045a44088baba60cacaacae4",
"rate_usd": "87.91",
"service": "NextDayAirSaver"
},
{
"carrier": "UPSDAP",
"meets_ruleset_requirements": false,
"predicted_deliver_by_date": "2025-02-11",
"predicted_deliver_days": 5,
"rate_id": "rate_5c552ee17b764ebe8b3e040e23acc161",
"rate_usd": "52.98",
"service": "2ndDayAir"
},
{
"carrier": "UPSDAP",
"meets_ruleset_requirements": false,
"predicted_deliver_by_date": "2025-02-11",
"predicted_deliver_days": 5,
"rate_id": "rate_00697bb80a6a4690a4adc1fa821d0549",
"rate_usd": "60.79",
"service": "2ndDayAirAM"
},
{
"carrier": "UPSDAP",
"meets_ruleset_requirements": false,
"predicted_deliver_by_date": "2025-02-12",
"predicted_deliver_days": 6,
"rate_id": "rate_8d6d3b28b62d43e8bf137f7f63588807",
"rate_usd": "38.19",
"service": "3DaySelect"
},
{
"carrier": "UPSDAP",
"meets_ruleset_requirements": false,
"predicted_deliver_by_date": "2025-02-14",
"predicted_deliver_days": 8,
"rate_id": "rate_ec4000010aa74083bcf7af34d77cd69f",
"rate_usd": "24.02",
"service": "Ground"
},
{
"carrier": "FedExDefault",
"meets_ruleset_requirements": false,
"predicted_deliver_by_date": "2025-02-15",
"predicted_deliver_days": 9,
"rate_id": "rate_81be930fa6824faa9f75ce474db8c329",
"rate_usd": "47.99",
"service": "SMART_POST"
},
{
"carrier": "FedExDefault",
"meets_ruleset_requirements": true,
"predicted_deliver_by_date": "2025-02-10",
"predicted_deliver_days": 4,
"rate_id": "rate_8c590b2c9f9f42fa8986b19e0180d5bd",
"rate_usd": "289.00",
"service": "PRIORITY_OVERNIGHT"
},
{
"carrier": "FedExDefault",
"meets_ruleset_requirements": true,
"predicted_deliver_by_date": "2025-02-10",
"predicted_deliver_days": 4,
"rate_id": "rate_f6cba61f30714f7fb779b7b157c0c619",
"rate_usd": "264.87",
"service": "STANDARD_OVERNIGHT"
},
{
"carrier": "FedExDefault",
"meets_ruleset_requirements": false,
"predicted_deliver_by_date": "2025-02-11",
"predicted_deliver_days": 5,
"rate_id": "rate_9a64fd048d644d8daaece83c92b49ae8",
"rate_usd": "202.16",
"service": "FEDEX_2_DAY_AM"
},
{
"carrier": "FedExDefault",
"meets_ruleset_requirements": false,
"predicted_deliver_by_date": "2025-02-13",
"predicted_deliver_days": 7,
"rate_id": "rate_4fb6b986d5e242b39dcfd47bff29b74d",
"rate_usd": "36.75",
"service": "FEDEX_GROUND"
}
],
"matching_rule_idx": 0,
"ruleset_description": "Buy the cheapest rate that satisfies all of the following:\nRule 0\n - Deliver by user input day of deliver_by_date - Transit day confidence >= 90\nOtherwise buy the cheapest rate"
}
}To test the Luma API without incurring charges:
- Use the Test API Key to execute the same buying logic on test shipments.
- This test environment mirrors production logic, returning the rate that would be selected based on the chosen ruleset.
For more details on Luma, refer to the Luma section of the EasyPost Help Center.