Luma
The Luma API enables shippers to buy labels, leveraging the rate shopping rules configured within the EasyPost Dashboard. By using predefined rulesets, Luma automates the rate selection process based on criteria such as transit time, cost, carrier preferences, and delivery confidence levels.
Luma supports two methods for purchasing shipments:
- One-Call Buy: Use
POST /shipments/lumato create and purchase a shipment in a single request. This method is ideal for shippers with established rulesets who want to reduce API calls. - Standard Buy: Create a shipment using
POST /shipments, then callPOST /shipments/:id/lumato evaluate the rates against the Luma ruleset and purchase the label. This method is ideal for shippers that are doing rating (creating a shipment) first, and then want to rate shop with Luma and buy a label.
Before using the Luma API, rate shopping rules must be defined in the EasyPost Dashboard. 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.
The Luma One-Call Buy endpoint enables live rating, time in transit predictions, rate shopping, and label purchase in a single API call using a predefined Luma ruleset.
The response is similar to the standard /shipments buy response, with the addition of a luma_info object that provides a detailed breakdown of the ruleset evaluation results.
See Luma Info Object for a breakdown of the response structure.
Request Parameters
The ship-to destination address for the postage label, including name, street, city, state, zip, and country.
The ship-from origin address for the postage label, including name, street, city, state, zip, and country.
Parcel size and weight details for rating and buying the postage label, including length (in), width (in), height (in), and weight (oz).
carrier_accounts
Limits the carrier account IDs for rating consideration. By default, Luma will fetch rates from all carrier_accounts enabled on the Easypost account.
persist_label
REQUIRED
i.e. True or False
By default (false), Easypost will provide a base64-encoded label. By setting value to true, Easypost will return an S3 link to a PNG label image.
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. This field is required if using a ruleset that has a required_delivery_by_date for time in transit requirements; if using time in transit days, this is not required.
POSTÂ /
1curl -X POST https://api.easypost.com/v2/shipments/luma \
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": "5744 Silverton Ave",
9 "city": "McKinney",
10 "state": "TX",
11 "zip": "75070",
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 "carrier_accounts": ["ca_1", "ca_2"],
34 "persist_label": true,
35 "ruleset_name": "required_deliver_by_date",
36 "planned_ship_date": "2025-05-14",
37 "deliver_by_date": "2025-05-16",
38 "insurance": "50.00"
39 }
40 }'Response
1{
2 "id": "shp_92521948d13a46c0a37acc02c7a8eebc",
3 "object": "Shipment",
4 "mode": "test",
5 "reference": null,
6 "to_address": {
7 "id": "adr_8a6c4e0a358f11f0aeeeac1f6bc539aa",
8 "object": "Address",
9 "created_at": "2025-05-20T15:31:46+00:00",
10 "updated_at": "2025-05-20T15:31:46+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_8a6edaed358f11f099333cecef1b359e",
30 "object": "Address",
31 "created_at": "2025-05-20T15:31:46+00:00",
32 "updated_at": "2025-05-20T15:31:46+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 "parcel": {
51 "id": "prcl_fbcd37ff5d1b46a7bf7a97c8d737c3a6",
52 "object": "Parcel",
53 "created_at": "2025-05-20T15:31:46Z",
54 "updated_at": "2025-05-20T15:31:46Z",
55 "length": 20.2,
56 "width": 10.9,
57 "height": 10.0,
58 "predefined_package": null,
59 "weight": 32.0,
60 "mode": "test"
61 },
62 "customs_info": null,
63 "forms": [],
64 "insurance": "50.00",
65 "selected_rate": {
66 "id": "rate_19ac933b051549b0927635949d7207be",
67 "object": "Rate",
68 "created_at": "2025-05-20T15:31:49Z",
69 "updated_at": "2025-05-20T15:31:49Z",
70 "mode": "test",
71 "service": "3DaySelect",
72 "carrier": "UPSDAP",
73 "rate": "38.19",
74 "currency": "USD",
75 "retail_rate": "115.86",
76 "retail_currency": "USD",
77 "list_rate": "153.36",
78 "list_currency": "USD",
79 "billing_type": "easypost",
80 "delivery_days": 3,
81 "delivery_date": "2025-05-23T23:00:00Z",
82 "delivery_date_guaranteed": false,
83 "est_delivery_days": 3,
84 "shipment_id": "shp_92521948d13a46c0a37acc02c7a8eebc",
85 "carrier_account_id": "ca_1"
86 },
87 "luma_info": {
88 "ai_results": [
89 {
90 "carrier": "USPS",
91 "meets_ruleset_requirements": false,
92 "predicted_deliver_by_date": "2025-05-27",
93 "predicted_deliver_days": 7,
94 "rate_id": "rate_0114e549b7394ce59145fa70f456b504",
95 "rate_usd": "23.85",
96 "service": "GroundAdvantage"
97 },
98 {
99 "carrier": "USPS",
100 "meets_ruleset_requirements": true,
101 "predicted_deliver_by_date": "2025-05-23",
102 "predicted_deliver_days": 3,
103 "rate_id": "rate_a99eed3f08a44ad59feb6dfcd5dea2d5",
104 "rate_usd": "135.45",
105 "service": "Express"
106 },
107 {
108 "carrier": "USPS",
109 "meets_ruleset_requirements": true,
110 "predicted_deliver_by_date": "2025-05-24",
111 "predicted_deliver_days": 4,
112 "rate_id": "rate_cead4ccaacc146a0be768ba05d748898",
113 "rate_usd": "41.44",
114 "service": "Priority"
115 },
116 {
117 "carrier": "UPSDAP",
118 "meets_ruleset_requirements": true,
119 "predicted_deliver_by_date": "2025-05-21",
120 "predicted_deliver_days": 1,
121 "rate_id": "rate_7b87f5e086ee4ca18a6396c8c50ed218",
122 "rate_usd": "94.45",
123 "service": "NextDayAir"
124 },
125 {
126 "carrier": "UPSDAP",
127 "meets_ruleset_requirements": true,
128 "predicted_deliver_by_date": "2025-05-21",
129 "predicted_deliver_days": 1,
130 "rate_id": "rate_7b221d5778c3456baab18cc14898808e",
131 "rate_usd": "124.45",
132 "service": "NextDayAirEarlyAM"
133 },
134 {
135 "carrier": "UPSDAP",
136 "meets_ruleset_requirements": true,
137 "predicted_deliver_by_date": "2025-05-21",
138 "predicted_deliver_days": 1,
139 "rate_id": "rate_2dbcf54f5fc34b82aba06311371fb380",
140 "rate_usd": "87.91",
141 "service": "NextDayAirSaver"
142 },
143 {
144 "carrier": "UPSDAP",
145 "meets_ruleset_requirements": true,
146 "predicted_deliver_by_date": "2025-05-22",
147 "predicted_deliver_days": 2,
148 "rate_id": "rate_368af0549232430fb71305d441aad6f2",
149 "rate_usd": "52.98",
150 "service": "2ndDayAir"
151 },
152 {
153 "carrier": "UPSDAP",
154 "meets_ruleset_requirements": true,
155 "predicted_deliver_by_date": "2025-05-22",
156 "predicted_deliver_days": 2,
157 "rate_id": "rate_99d99ac69d6f4d5f99983572e6dd03af",
158 "rate_usd": "60.79",
159 "service": "2ndDayAirAM"
160 },
161 {
162 "carrier": "UPSDAP",
163 "meets_ruleset_requirements": true,
164 "predicted_deliver_by_date": "2025-05-23",
165 "predicted_deliver_days": 3,
166 "rate_id": "rate_a8b60fd7f1e14dd0afcb0fe894f5492d",
167 "rate_usd": "38.19",
168 "service": "3DaySelect"
169 },
170 {
171 "carrier": "UPSDAP",
172 "meets_ruleset_requirements": false,
173 "predicted_deliver_by_date": "2025-05-28",
174 "predicted_deliver_days": 8,
175 "rate_id": "rate_da501c08b53347f4824392bc5f7a2a34",
176 "rate_usd": "25.04",
177 "service": "Ground"
178 }
179 ],
180 "matching_rule_idx": 0,
181 "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"
182 },
183 "postage_label": {
184 "object": "PostageLabel",
185 "id": "pl_7b3094b609a24032ab5b84111fa2406f",
186 "created_at": "2025-05-20T15:31:49Z",
187 "updated_at": "2025-05-20T15:31:49Z",
188 "date_advance": 0,
189 "integrated_form": "none",
190 "label_date": "2025-05-20T15:31:49Z",
191 "label_resolution": 200,
192 "label_size": "4x7",
193 "label_type": "default",
194 "label_file_type": "image/png",
195 "label_url": "https://easypost-files.s3.us-west-2.amazonaws.com/files/postage_label/20250520/e8e53bfe41c21845f2995959adb9358ef6.png",
196 "label_pdf_url": null,
197 "label_zpl_url": null,
198 "label_epl2_url": null,
199 "label_file": null
200 },
201 "messages": [],
202 "tracking_code": "1ZXXXXXXXXXXXXXXXX",
203 "fees": [
204 {
205 "object": "Fee",
206 "type": "LabelFee",
207 "amount": "0.00000",
208 "charged": true,
209 "refunded": false
210 },
211 {
212 "object": "Fee",
213 "type": "PostageFee",
214 "amount": "38.19000",
215 "charged": true,
216 "refunded": false
217 },
218 {
219 "object": "Fee",
220 "type": "InsuranceFee",
221 "amount": "0.50000",
222 "charged": true,
223 "refunded": false
224 }
225 ],
226 "tax_identifiers": null,
227 "created_at": "2025-05-20T15:31:46Z",
228 "updated_at": "2025-05-20T15:31:49Z"
229}A shipment object must be created with the following details before calling the Luma Standard Buy API:
from_address: The origin address.to_address: The destination address.parcel: 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. This field is required if using a ruleset that has a required_deliver_by_date for time in transit requirements; if using time in transit days, this is not required.
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 and a luma_info object that outlines 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.
LumaInfo 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.