Luma Guide

Luma is EasyPost’s AI-powered rate shopping engine that enables shippers to automatically purchase shipping labels based on predefined business logic. When purchasing labels, shippers often need to balance speed, cost, and carrier preferences. Luma automates this decision-making process using predefined rules and AI predictions. This reduces manual configuration and ensures consistency in label selection.

Luma supports two methods for purchasing shipments:

1. One-Call Buy: Use POST /shipments/luma to create and purchase a shipment in a single request. This method is ideal for shippers with established rulesets who want to reduce API calls.
2. Standard Buy: Create a shipment using POST /shipments, then call POST /shipments/:id/luma to 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 to buy a label.

1. Sign up for an EasyPost account or log in to an existing account.
2. Add and configure carrier accounts via EasyPost API or the EasyPost Dashboard. Only rates from connected carriers will be evaluated by Luma.
3. Sign up for Luma.

Luma Select is the decision engine behind the Luma API. It evaluates carrier rates against a set of rules and selects the most appropriate shipping label. Rulesets are created in the EasyPost Dashboard and executed via the API.

• Delivery Settings: Specifies a required delivery date or predefined delivery range (e.g., 2-Day Shipping). A delivery date must be included during shipment creation when this rule is used.
• Delivery Confidence: Indicates the required confidence level for on-time delivery based on historical performance data.
  • Standard (75%)
  • High (90%)
  • Very High (95%)
• Carriers Used: Restricts selection to carriers configured on the EasyPost account.
• Cost Threshold: Defines the maximum acceptable rate.
• Contingency Plan: Establishes a fallback carrier/service (e.g., USPS Ground Advantage) if no eligible rate satisfies the rules.

For help managing rules through the EasyPost Dashboard, see the Luma Select Help Center article.

• Automated Rate Selection: Eliminates manual logic and reduces errors by enforcing rules consistently.
• AI-Powered Predictions: Uses AI to optimize based on on-time delivery probability.
• Fallback Logic: Ensures a label is returned, even when ideal conditions are not met.
• Improved Efficiency: Reduces effort and improves carrier performance insight.

Use the One-Call Buy method to create and purchase a shipment in a single request. This approach reduces the number of API calls required.

Before calling the Luma API, a ruleset must be defined. Work with an EasyPost account manager to configure rules based on:

• Days in Transit: Maximum number of transit days desired.
• Confidence: AI-predicted confidence that the shipment will arrive on time.
• Maximum Cost: Maximum dollar amount allowed for the shipment.
• Included Carriers: Specify which carriers to consider for the shipment.

Example Logic:

“If FedEx or UPS can deliver within 3 days with 85% confidence and under $20, choose the cheapest rate. Otherwise, default to the cheapest available option.”

Each ruleset is assigned a ruleset_name and configured by EasyPost.

Send a request to POST /shipments/luma with a complete shipment object in the request body. The object must include:

• to_address
• from_address
• parcel
• ruleset_name
• planned_ship_date
• deliver_by_date (optional)
• insurance (optional)
• persist_label (optional)

The response includes all shipment data, the selected rate, the postage label (or base64-encoded label if persist_label is false), and a luma_info object with rule evaluation details.

For request parameters and examples, refer to the Luma API Docs.

Before calling the Luma API, a ruleset must be defined. Work with an EasyPost account manager to configure rules based on:

• Days in Transit: Maximum number of transit days desired.
• Confidence: AI-predicted confidence that the shipment will arrive on time.
• Maximum Cost: Maximum dollar amount allowed for the shipment.
• Included Carriers: Specify which carriers to consider for the shipment.

Example Logic:

“If FedEx or UPS can deliver within 3 days with 85% confidence and under $20, choose the cheapest rate. Otherwise, default to the cheapest available option.”

Each ruleset is assigned a ruleset_name and configured by EasyPost.

Use the standard create shipment endpoint. Include:

• to_address
• from_address`
• parcel
• Any required options (e.g., delivery_date if used in ruleset logic)

The response returns a shipment_id, which will be used in the Luma API call.

After creating the shipment, pass the shipment_id into the Luma API to purchase a label based on the ruleset_name provided.

For detailed parameters and examples, see the Luma API Docs.

The Luma Promise endpoint evaluates shipping options based on a predefined ruleset without purchasing a label. This rating-only call returns the selected rate, predicted delivery date, and cost based on the defined business logic.

Send a request to POST /shipments/luma/promise with the following fields in the request body:

• to_address
• from_address
• parcel
• ruleset_name (required)
• planned_ship_date (required)
• delivery_by_date (optional)

The response includes:

• The selected rate that satisfies the ruleset.
• luma_predicted_delivery_by_date
• A breakdown of all evaluated rates (ai_results).

For detailed request and response examples, refer to the Luma API Docs.

The Luma response includes all fields returned by a typical buy request (selected rate, label URLs, carrier info), as well as a luma_info object that details how the rate was selected.

Review the Luma Info Object for detailed information.

1. Use a Test API key to avoid purchasing labels.
2. Create a test shipment.
3. Execute the Luma API call.
4. Review luma_info to verify logic is working as expected.

• Luma - API Docs
• Help Center - Luma