Order-to-Label Workflow

The current integration scope uses an Order as the top-level fulfilment resource. An Order contains one or more Shipments. Shipment identifiers are used to request Rates and purchase a Label.

Order
└── Shipment
    ├── Rates
    └── Label

Find an order

GET/api/v1/orders GET/api/v1/orders/{orderId}

List Orders to find existing workflow state, or retrieve one Order by its ID. GET /api/v1/orders accepts search, sortByNewest, dateFrom, dateTo, statuses, pageNumber, and pageSize as optional query parameters and returns a paged envelope — see Make Your First Request for a worked example. Full field-level schemas are in the API Reference.

Standard Order workflow

1. 1

   Authenticate

   Obtain an access token before making protected integration requests.

2. 2

   Create an Order

   Create an Order and read back its Order and Shipment identifiers.

3. 3

   Request Rates

   Request available Rate options for the Shipment — this works regardless of the Order’s status.

4. 4

   Select a Rate

   Keep the selected Rate identifier for label purchase.

5. 5

   Purchase a Label

   Purchase a Label for the Shipment using the selected Rate. The Order automatically becomes LabelCreated.

6. 6

   Download the Label

   Save or stream the non-JSON file response securely.

7. 7

   Mark the Order Fulfilled

   Update the Order once the shipment has been handed to the carrier.

Packed is optional, not a required gate

Earlier revisions of this guide described Packed as a required step before Rates or Label purchase. Neither operation checks for it: Rates has no Order-status precondition at all, and Label purchase only rejects Orders that are already Cancelled, already LabelCreated, or Returned. Use Update Order Status to record Packed (or any other status) whenever it reflects your real warehouse progress — it is good practice, not a technical requirement.

Fulfilled is enforced: it is only reachable from LabelCreated, so mark it only after a Label has been purchased (see Update Order Status for the full supported-transition table).

Optional cancellation branch

If a purchased Label needs to be cancelled, follow Cancel a Label. Cancellation is an explicit workflow branch, not a required final step, and returns the Order to Packed.

Alternative: create with rates in one call

The workflow above starts with standard Order creation. For one Order, Create an Order with Rates combines creation and initial rating in one request. It remains one Order per request and does not change the separate Label workflow.

Guides

• Create an Order
• Create an Order with Rates
• Update Order Status
• Get Shipping Rates
• Buy a Label
• Download a Label
• Cancel a Label

Working with USPS? See USPS with Mailhub for carrier context on the same sequence.

State-changing tests

Before state-changing Sandbox tests, confirm carrier test mode, wallet or test-fund readiness, label-purchase safety, and cleanup or cancellation behavior. Production label purchase can involve real cost.