Overview

This guide outlines how to use the OneRail API to determine shipping rates for a potential delivery and progressively update an order using partial updates. These actions are crucial for dynamically pricing deliveries and managing the delivery workflow efficiently.

The use of the /delivery/get-rates endpoint allows organizations to create draft delivery orders based on rate information retrieved from eligible carriers. Subsequently, partial updates ensure that as more accurate data (like final costs or carrier assignments) becomes available, it can be reflected without re-submitting the entire delivery payload.

Delivery Creation Flow Using Get Rates and Partial Updates

/delivery/get-rates

This endpoint fetches delivery rates from available carriers based on the provided delivery details. It's influenced by the configuration of logistics partners (LPs) and organizational settings, such as package definitions.

• Only carriers that respond successfully are considered; unresponsive carriers are excluded from the results.
• The returned rates can be used to create a draft order and present options to the end user.
• LP configuration is managed via the shipper's contract settings and LP shopping logic.

For full implementation details, refer to: Swagger - Get Rates

/order/{orderID}/partial-update

After obtaining the lowest cost provider, this endpoint is used to update an existing draft delivery with finalized information, such as carrier selection, price breakdown, or label generation.

• Label generation timing is critical; if required immediately, the update request should include a flag for requestLabel: true.
• Enables fine-tuned control of delivery progression from quote to dispatch-ready.
• Ideal for systems where order creation and fulfillment occur in stages.

For full implementation details, refer to: Swagger - Partial Update

End-to-End Workflow

1. Rate Shopping: Use /delivery/get-rates to preview potential delivery options and pricing.
2. Create Draft Delivery: Based on preferred rates, initiate a delivery object with partial information (e.g., without labels or final costs).
3. Update Delivery: As decisions are finalized, use /delivery/partial-update to reflect carrier choice, update costs, and trigger label generation.
4. Finalize Dispatch: Once all fields are populated, transition the delivery state to READY_TO_DISPATCH.

Benefits

• Decouples pricing from final delivery submission.
• Reduces overhead in carrier rate comparisons.
• Supports agile fulfillment scenarios with dynamic updates.