How to Use Orchestrate Orders Endpoint

Overview

The Rate and Ship endpoint is designed to fully automate the order fulfillment process in a single step. When provided with order details, this endpoint will automatically:

• Create a custom order.
• Apply your configured eHub automations.
• Fetch available carrier rates based on your criteria.
• Purchase the cheapest available shipping label.
• Return the purchased label directly in the response.

Endpoint:
POST /api/v2/orchestrate/order_stores/:order_store_id/orders/rate_and_ship

Required eHub Ship Automations

For the Rate and Ship endpoint to successfully purchase and return a label, you must have specific automations configured within the eHub Ship UI. Without these, the endpoint will fail to generate a shipment.

Please ensure the following five requirements are met:

1. Rate Shop Rule: A rule must be assigned through automation to dictate how the system determines the cheapest rate.
2. From Address: A valid origin address must be assigned to the shipment.Through automation or default fulfillment location.
3. Label Format: A default label format must be configured within the fulfillment location in the Ship UI.
4. Weight: The package weight must either be passed through the API request payload or set up via eHub Ship's automation rules.
5. Package Type: The package type and dimensions must be defined, either through the API request payload or configured via eHub Ship's automation rules.

Retries and Duplicate Prevention

• Unique Order Numbers: The order number must be unique for every request.
• Safe Retries: If a previous request fails due to network issues, disconnects, or timeouts, you can safely resend the exact same payload.
• Duplicate Detection: The system will detect a duplicate order number. Instead of creating a duplicate order or purchasing a second label, it will safely return the previously purchased label.

Response Structure

When a label is successfully purchased, the record automatically moves from pending shipments to shipments. The label details are then attached directly to the shipment record.

Key label information available in the response includes:

• Shipping Service: Details the carrier and service level selected (shipments.shipping_service).
• Shipping Cost: The cost of the purchased label (shipments.parcels.shipping_cost).
• Postage Label: The generated shipping label, provided as a URL or base64 encoded image (shipments.parcels.postage_label).