Overview
Luma Simulator uses historical shipping data to estimate potential shipping savings with EasyPost rates. To run a simulation, shipment data must be provided in the Package Level Detail (PLD) format.
The PLD file contains package-level information such as carrier, service level, shipment cost, origin and destination, shipment date, and parcel dimensions.
Use the requirements in this guide when preparing PLD data for a Luma simulation.
Prerequisites
Before preparing the PLD file:
- Gather historical shipment-level data for the volume being evaluated.
- Include all required PLD fields.
- Verify that shipment rates include applicable surcharges.
- Use the supported formats and values described below.
PLD File Fields
The following fields are supported in the PLD file and should be included in the order shown below:
| Field | Description | Required |
shipment_id |
Unique identifier for the shipment. A tracking code or sequential row number, such as 1, 2, 3, can also be used. | Yes |
carrier |
Carrier used for the shipment. | Yes |
service_level |
Service level used for the shipment. | Yes |
rate |
Shipment rate, including surcharges, in USD. | Yes |
to_zip |
Five-digit destination ZIP code. | Yes |
from_zip |
Five-digit origin ZIP code. | Yes |
to_country_code |
ISO country code for the destination address. | Yes |
from_country_code |
ISO country code for the origin address. | Yes |
ship_date |
Date the package was shipped. | Yes |
parcel_weight |
Actual parcel weight in ounces. | Yes |
parcel_length |
Parcel length in inches. | Yes |
parcel_width |
Parcel width in inches. | Yes |
parcel_height |
Parcel height in inches. | Yes |
to_state |
State code for the destination address. | No |
from_state |
State code for the origin address. | No |
days_in_transit |
Total number of days the shipment was in transit. | No |
delivery_date |
Date the package was delivered. | No |
to_address_residential |
Indicates whether the destination address is residential. | No |
signature_type |
Signature requirement associated with the shipment. | No |
hazmat_type |
Hazardous materials category associated with the shipment. | No |
Date Formats
The ship_date field supports the following formats:
YYYY-MM-DD HH:MM:SSYYYY-MM-DDMM/DD/YYYYMM/DD/YYYYYY/MM/DD
Use a consistent date format throughout the PLD file whenever possible.
Signature Types
The signature_type field supports the following values:
no_signatureadult_restrictedadultrestrictedsignature
If no value is provided, the default is no_signature.
Hazardous Materials Types
The hazmat_type field supports the following values:
lithiumno_hazmathazmatlimited_quantity
If no value is provided, the default is no_hazmat.
Best Practices
- Include shipment data from the past 90 days to help ensure rates are current.
- Verify that
rateincludes applicable shipment surcharges. - Use actual parcel weight and dimensions, not estimated values.
- Keep carrier and service-level values consistent throughout the file.
- Include
days_in_transitanddelivery_datewhen available. These fields can provide additional information when evaluating alternative service levels. - Review the file for missing required values before submitting it for simulation.
FAQs
Q: What is Package Level Detail?
Package Level Detail (PLD) is shipment-level data that describes individual packages, including the carrier, service level, cost, route, shipment date, and parcel characteristics.
Luma Simulator uses this information to evaluate historical shipment volume against EasyPost shipping rates.
Q: Are all PLD fields required?
No. Fields marked as required must be included for each shipment. Optional fields can be provided when the information is available.
Q: Why should delivery and transit information be included?
Delivery dates and days in transit can provide additional context when evaluating whether alternative, lower-cost service levels could meet similar delivery requirements.
Q: Does the shipment rate need to include surcharges?
Yes. The rate value should represent the shipment cost including surcharges.