Orders — API Reference | Mailhub Developers

Create, list, retrieve, and update the fulfilment status of orders. An order's own `status` (Created, Packed, LabelCreated, Fulfilled, …) tracks fulfilment progress and is distinct from a shipment's tracking-oriented `status` field, which stays `Unknown` until real tracking is implemented — the two must not be conflated when reading a response. Create an Order with Rates creates the same public Order resource, then immediately requests Rates for each created Shipment.

Operations

GET `/api/v1/orders`

List orders

Returns a paginated list of orders for the authenticated account. Supports optional filtering by search term, date range, statuses, and sources. Each order reports a `source` indicating where it came from: `Manual` (created in the Mailhub app), `API` (created through this integration API), or `Shopify` (imported from a connected store). The `sources` filter takes the numeric values of those names — 1 `Manual`, 2 `API`, 3 `Shopify` — and is repeated to match several, e.g. `?sources=2&sources=3`. Omit it to return orders from every source.

Authentication: JWTBearerAuth, Bearer http, JWT

Parameters

Name	In	Type	Required	Description
`search`	query	`string`	optional	Example: `John Recipient`
`sortByNewest`	query	`boolean`	optional	Example: `true`
`dateFrom`	query	`string (date-time)`	optional	Example: `2026-01-01T00:00:00Z`
`dateTo`	query	`string (date-time)`	optional	Example: `2026-12-31T23:59:59Z`
`statuses`	query	`OrderStatus[]`	optional	Example: `7`
`sources`	query	`OrderSourceCode[]`	optional	Example: `2`
`pageNumber`	query	`integer (int32)`	optional	Example: `1`
`pageSize`	query	`integer (int32)`	optional	Example: `20`
`X-SubAccount-Id`	header	`string (uuid)`	optional	Optional. If present, filters the returned orders to this sub-account only; omit to list all of the account's orders regardless of sub-account. Example: `3a7d9e21-6b48-4c15-9f2e-7d0c5b83a614`

Responses

Status	Description	Body
`200`	Orders retrieved successfully	`application/json` — `ListOrdersResponseEnvelope`
`400`	The request could not be read as sent — for example an `X-SubAccount-Id` header that is not a GUID.	`application/json` — `ErrorEnvelope`
`401`	Not authenticated	`application/json` — `ErrorEnvelope`
`403`	Authenticated, but not with an Open API integration token. Sent without a body.	No response body.
`404`	The sub-account given in `X-SubAccount-Id` does not exist or belongs to another account.	`application/json` — `ErrorEnvelope`
`409`	The sub-account given in `X-SubAccount-Id` is not active.	`application/json` — `ErrorEnvelope`
`422`	Validation errors	`application/json` — `ErrorEnvelope`
`500`	The request could not be completed because of an unexpected server-side failure.	`application/json` — `ErrorEnvelope`

POST `/api/v1/orders`

Create an Order

Creates one Order containing one or more Shipments and returns the created Order. This standard creation flow does not request shipping Rates during the create operation.

Authentication: JWTBearerAuth, Bearer http, JWT

Parameters

Name	In	Type	Required	Description
`X-SubAccount-Id`	header	`string (uuid)`	optional	Optional. If present, tags the newly created order (and its shipments) with this sub-account. Example: `3a7d9e21-6b48-4c15-9f2e-7d0c5b83a614`
`Idempotency-Key`	header	`string`	optional	Optional. Identifies one creation attempt. Repeating a request with the same value returns the Order the first attempt created instead of creating a second one, which makes a request that timed out safe to repeat. Choose a new value for a genuinely new Order. The key is scoped to the account, not the sub-account: repeating it under a different X-SubAccount-Id still returns the first Order. Maximum 200 characters. Keys beginning with `ingestion:` are reserved for orders imported from a connected store and are rejected, whatever their casing. Example: `order-2026-09-07-0001`

Request body (required)

application/json — CreateOrderRequest

{
  "fromAddress": {
    "name": "Jane Sender",
    "street1": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "country": "US",
    "phone": "5125550100"
  },
  "toAddress": {
    "name": "John Recipient",
    "street1": "456 Oak Ave",
    "city": "Denver",
    "state": "CO",
    "zip": "80202",
    "country": "US",
    "phone": "3035550100"
  },
  "shipments": [
    {
      "parcel": {
        "weight": 16,
        "length": 10,
        "width": 8,
        "height": 4
      }
    }
  ]
}

Responses

Status	Description	Body
`201`	Order created successfully	`application/json` — `CreateOrderResponseEnvelope`
`400`	A required part of the request is missing: `fromAddress`, `toAddress`, `shipments`, or a shipment's `parcel`	`application/json` — `ErrorEnvelope`
`401`	Not authenticated	`application/json` — `ErrorEnvelope`
`403`	Authenticated, but not with an Open API integration token. Sent without a body.	No response body.
`404`	The sub-account given in `X-SubAccount-Id` does not exist or belongs to another account.	`application/json` — `ErrorEnvelope`
`409`	The sub-account given in `X-SubAccount-Id` is not active.	`application/json` — `ErrorEnvelope`
`415`	The request was sent with a `Content-Type` other than `application/json`. Answered by middleware ahead of authentication, so it is reachable on every write operation.	`application/json` — `ErrorEnvelope`
`422`	The addresses were readable but not usable — an address failed validation	`application/json` — `ErrorEnvelope`
`500`	The request could not be completed because of an unexpected server-side failure.	`application/json` — `ErrorEnvelope`

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

Get order

Returns detailed information about a single order including shipment and package details. shipment.labelAssets carries one entry per printable format, each with a temporary pre-signed url when the asset has been generated. The link downloads the file directly from storage with no API token, expires (24 hours by default) and cannot be revoked before it does — treat it as a credential. This endpoint is the way to obtain fresh links after earlier ones lapse: request the order again.

Authentication: JWTBearerAuth, Bearer http, JWT

Parameters

Name	In	Type	Required	Description
`orderId`	path	`string (guid)`	required	Example: `5f2c1a10-2b3d-4e5f-8a9b-0c1d2e3f4a5b`
`X-SubAccount-Id`	header	`string (uuid)`	optional	Optional. If present, the order must belong to this sub-account; omit to look up orders across the authenticated account. Example: `3a7d9e21-6b48-4c15-9f2e-7d0c5b83a614`

Responses

Status	Description	Body
`200`	Order retrieved successfully	`application/json` — `GetOrderResponseEnvelope`
`400`	The request could not be read as sent — for example an `X-SubAccount-Id` header that is not a GUID.	`application/json` — `ErrorEnvelope`
`401`	Not authenticated	`application/json` — `ErrorEnvelope`
`403`	Authenticated, but not with an Open API integration token. Sent without a body.	No response body.
`404`	Order not found	`application/json` — `ErrorEnvelope`
`409`	The sub-account given in `X-SubAccount-Id` is not active.	`application/json` — `ErrorEnvelope`
`500`	The request could not be completed because of an unexpected server-side failure.	`application/json` — `ErrorEnvelope`

PATCH `/api/v1/orders/{orderId}/status`

Update order status

Changes the order status using order workflow rules.

Authentication: JWTBearerAuth, Bearer http, JWT

Parameters

Name	In	Type	Required	Description
`orderId`	path	`string (guid)`	required	Example: `5f2c1a10-2b3d-4e5f-8a9b-0c1d2e3f4a5b`
`X-SubAccount-Id`	header	`string (uuid)`	optional	Optional but has no effect on this operation: the order is looked up and updated by account only, regardless of which sub-account it is tagged with or which sub-account this header specifies. Example: `3a7d9e21-6b48-4c15-9f2e-7d0c5b83a614`

Request body (required)

application/json — UpdateOrderStatusRequest

{
  "status": 7,
  "reason": "Packed and ready to ship",
  "source": "warehouse-scanner"
}

Responses

Status	Description	Body
`200`	Order status updated successfully.	`application/json` — `UpdateOrderStatusResponseEnvelope`
`400`	Bad request.	`application/json` — `ErrorEnvelope`
`401`	The request carries no usable credential: missing, malformed, expired, or revoked.	`application/json` — `ErrorEnvelope`
`403`	Authenticated, but not with an Open API integration token. Sent without a body.	No response body.
`404`	Order not found.	`application/json` — `ErrorEnvelope`
`409`	Status transition is not allowed.	`application/json` — `ErrorEnvelope`
`415`	The request was sent with a `Content-Type` other than `application/json`. Answered by middleware ahead of authentication, so it is reachable on every write operation.	`application/json` — `ErrorEnvelope`
`422`	The requested status, or the resume status it needs, is not usable.	`application/json` — `ErrorEnvelope`
`500`	The request could not be completed because of an unexpected server-side failure.	`application/json` — `ErrorEnvelope`

POST `/api/v2/orders`

Create an Order with Rates

Creates one Order using the same Order-creation workflow as POST /api/v1/orders, then immediately requests Rates for each created Shipment. The response returns the created Order and Rates grouped by Shipment. Use the V1 operation when you want to create the Order first and request Rates later. Use this operation when you want creation and initial rating in one request. This operation creates one Order per request, not a batch endpoint, and Label purchase remains a separate step.

Authentication: JWTBearerAuth, Bearer http, JWT

Parameters

Name	In	Type	Required	Description
`X-SubAccount-Id`	header	`string (uuid)`	optional	Optional. If present, tags the newly created order (and its shipments) with this sub-account — the same behavior as POST /api/v1/orders, since this operation creates through the same path. Example: `3a7d9e21-6b48-4c15-9f2e-7d0c5b83a614`
`Idempotency-Key`	header	`string`	optional	Optional. Identifies one creation attempt. Repeating a request with the same value returns the Order the first attempt created instead of creating a second one, which makes a request that timed out safe to repeat. Choose a new value for a genuinely new Order. The key is scoped to the account, not the sub-account: repeating it under a different X-SubAccount-Id still returns the first Order. Maximum 200 characters. Keys beginning with `ingestion:` are reserved for orders imported from a connected store and are rejected, whatever their casing. Example: `order-2026-09-07-0001`

Request body (required)

application/json — CreateOrderV2Request

{
  "order": {
    "fromAddress": {
      "name": "Jane Sender",
      "street1": "123 Main St",
      "city": "Austin",
      "state": "TX",
      "zip": "78701",
      "country": "US",
      "phone": "5125550100"
    },
    "toAddress": {
      "name": "John Recipient",
      "street1": "456 Oak Ave",
      "city": "Denver",
      "state": "CO",
      "zip": "80202",
      "country": "US",
      "phone": "3035550100"
    },
    "shipments": [
      {
        "parcel": {
          "weight": 16,
          "length": 10,
          "width": 8,
          "height": 4
        }
      }
    ]
  }
}

Responses

Status	Description	Body
`200`	Order created with at least one carrier rate	`application/json` — `CreateOrderV2ResponseEnvelope`
`400`	The request could not be read as sent — for example an `X-SubAccount-Id` header that is not a GUID.	`application/json` — `ErrorEnvelope`
`401`	Not authenticated	`application/json` — `ErrorEnvelope`
`403`	Authenticated, but not with an Open API integration token. Sent without a body.	No response body.
`404`	The sub-account given in `X-SubAccount-Id` does not exist or belongs to another account.	`application/json` — `ErrorEnvelope`
`409`	The sub-account given in `X-SubAccount-Id` is not active.	`application/json` — `ErrorEnvelope`
`415`	The request was sent with a `Content-Type` other than `application/json`. Answered by middleware ahead of authentication, so it is reachable on every write operation.	`application/json` — `ErrorEnvelope`
`422`	Invalid Order input, or the carrier rejected the shipment for a reason the caller can correct. If no created Shipment returned a Rate, the Order may already have been created before this response is returned. Send an Idempotency-Key header and repeat the same request with the same key to find out: the first attempt's Order is returned rather than a second one being created.	`application/json` — `ErrorEnvelope`
`500`	No rates could be produced and the failure could not be classified	`application/json` — `ErrorEnvelope`
`503`	No rates could be produced because a carrier is temporarily unavailable. Nothing to correct; retry later	`application/json` — `ErrorEnvelope`

Schemas

The public schemas the operations above reference. Each is listed once; a type name in the tables above links to its fields here.

`ApiError`

One thing that went wrong.

Field	Type	Required	Description
`code`	`string`	required	Machine-readable error identifier, dotted and stable — for example Order.NotFound. Branch on this rather than on message.
`message`	`string`	required	Readable explanation of the failure. Wording may change; do not parse it.
`metaData`	`object` nullable	optional	Extra detail about this particular failure. Its shape depends on code.

`CarrierRateResult`

The outcome of asking one carrier for rates. Present for every carrier that was asked, so a carrier that returned nothing can be told apart from a carrier that was never contacted.

Field	Type	Required	Description
`carrier`	`string`	required	The carrier that was asked for rates.
`errorCode`	`string` nullable	required	Machine-readable reason the carrier returned no rates.
`errorMessage`	`string` nullable	required	Readable explanation of why the carrier returned no rates.
`success`	`boolean`	required	Whether that carrier returned rates.

`CreateOrderRequest`

An order to create. Accepts either the wrapped form — { "order": { … } } — or the flat form, { "fromAddress": …, "toAddress": …, "shipments": [ … ] }. Send one or the other; when both are present the wrapped order wins.

Field	Type	Required	Description
`fromAddress`	`OrderAddressRequest` nullable	optional	Flat payload: { "fromAddress": …, "toAddress": …, "shipments": … }.
`order`	`OrderRequest` nullable	optional	Wrapped payload: { "order": { "fromAddress": … } }.
`shipments`	`OrderShipmentRequest[]` nullable	optional	Packages to ship, in the flat form of the payload. One shipment per package.
`toAddress`	`OrderAddressRequest` nullable	optional

`CreateOrderResponse`

An order as Mailhub recorded it, with the addresses and shipments it now owns.

Field	Type	Required	Description
`createdAt`	`string (date-time)`	required	UTC instant the order was created. Format: `date-time`
`fromAddress`	`OrderAddressResponse`	required
`id`	`string`	required	Identifier of the created order. Use it on the order retrieval and status operations.
`isReturn`	`boolean`	required	Whether the order is a return shipment back to the sender.
`shipments`	`OrderShipmentResponse[]`	required	The packages recorded on the order, one entry per shipment sent in the request.
`status`	`OrderStatus`	required	Order status as its numeric OrderStatus value — a newly created order reads 0 (Created). The full set is listed on the OrderStatus schema, and the order retrieval, list and status-update operations use these same numbers.
`toAddress`	`OrderAddressResponse`	required
`updatedAt`	`string (date-time)`	required	UTC instant the order was last modified. Format: `date-time`

`CreateOrderResponseEnvelope`

The envelope every JSON operation answers with: a success flag and either a result or errors.

Field	Type	Required	Description
`data`	`CreateOrderResponse` nullable	required	The operation's result. Absent when the call failed.
`errors`	`ApiError[]` nullable	required	What went wrong. Absent when the call succeeded.
`success`	`boolean`	required	Whether the operation succeeded. When false, read errors.

`CreateOrderV2Request`

An order to create and immediately fetch rates for.

Field	Type	Required	Description
`order`	`OrderRequest`	required

`CreateOrderV2Response`

The created order together with the rates fetched for its shipments.

Field	Type	Required	Description
`errors`	`ApiError[]`	required	Failures that did not stop the order being created — a rate lookup that failed, for example.
`order`	`CreateOrderResponse` nullable	required	The order that was created.
`shipmentRates`	`CreateOrderV2ShipmentRates[]`	required	Rates fetched for each shipment on the new order, one entry per shipment.
`status`	`string`	required	Fixed acknowledgement returned on a successful combined create-and-rate call — always the string created. It is not an order status: the order's own lifecycle value is the numeric OrderStatus on order.status. A call that produced no rates at all fails instead of returning this response. Allowed values: `created`

`CreateOrderV2ResponseEnvelope`

The envelope every JSON operation answers with: a success flag and either a result or errors.

Field	Type	Required	Description
`data`	`CreateOrderV2Response` nullable	required	The operation's result. Absent when the call failed.
`errors`	`ApiError[]` nullable	required	What went wrong. Absent when the call succeeded.
`success`	`boolean`	required	Whether the operation succeeded. When false, read errors.

`CreateOrderV2ShipmentRates`

The rates available for one shipment on the order.

Field	Type	Required	Description
`carrierResponses`	`CarrierRateResult[]`	required	One entry per carrier that was asked, including the ones that returned nothing, so a missing carrier can be told apart from a carrier that declined.
`errors`	`ApiError[]`	required	Failures encountered while rating this shipment.
`rates`	`RateQuote[]`	required	The rates available for this shipment. Buy one by sending its id to the label operation.
`shipmentId`	`string`	required	Identifier of the shipment these rates belong to.

`ErrorEnvelope`

The envelope every JSON operation answers with: a success flag and either a result or errors.

Field	Type	Required	Description
`data`	`object` nullable	required	The operation's result. Absent when the call failed.
`errors`	`ApiError[]`	required	What went wrong. Absent when the call succeeded.
`success`	`boolean`	required	Whether the operation succeeded. When false, read errors.

`GetOrderResponse`

One order, with its recipient, destination and most recent shipment.

Field	Type	Required	Description
`customer`	`OrderCustomer`	required
`destination`	`OrderDestination`	required
`id`	`string (guid)`	required	Identifier of the order. Format: `guid`
`labelId`	`string (guid)` nullable	required	Identifier of the most recent label bought for the order, when one exists. Format: `guid`
`orderDate`	`string (date-time)`	required	UTC instant the order was created. Format: `date-time`
`shipment`	`OrderShipmentSummary` nullable	required	The order's most recent shipment, when it has one. An order with no shipment yet has none.
`shipmentId`	`string (guid)` nullable	required	Identifier of the order's most recent shipment, when it has one. Format: `guid`
`status`	`OrderStatus`	required

`GetOrderResponseEnvelope`

The envelope every JSON operation answers with: a success flag and either a result or errors.

Field	Type	Required	Description
`data`	`GetOrderResponse` nullable	required	The operation's result. Absent when the call failed.
`errors`	`ApiError[]` nullable	required	What went wrong. Absent when the call succeeded.
`success`	`boolean`	required	Whether the operation succeeded. When false, read errors.

`LabelStatus`

State of a purchased label, published as the numeric value: 0 = Unknown — no label state recorded. 1 = Created — bought and live at the carrier. 2 = Printed — printed; still live, and still blocks a second purchase for the shipment. 3 = Cancelled — cancelled at the carrier, which returns its order to Packed. 4 = Error — the purchase failed and no usable label exists. This is the label's own state: not the shipment's tracking status, and not the per-format rendering progress reported by labelProcessingStatus.

Allowed values: 0, 1, 2, 3, 4

Type integer.

`ListOrdersResponse`

Type object.

`ListOrdersResponseEnvelope`

The envelope every JSON operation answers with: a success flag and either a result or errors.

Field	Type	Required	Description
`data`	`ListOrdersResponse` nullable	required	The operation's result. Absent when the call failed.
`errors`	`ApiError[]` nullable	required	What went wrong. Absent when the call succeeded.
`success`	`boolean`	required	Whether the operation succeeded. When false, read errors.

`OrderAddressRequest`

A postal address supplied on an order.

Field	Type	Required	Description
`carrierFacility`	`string` nullable	optional	Carrier facility this address refers to, when the shipment is dropped at or collected from a named facility rather than the street address.
`city`	`string`	required	City or locality.
`company`	`string` nullable	optional	Company name at the address.
`country`	`string`	required	Two-letter ISO 3166-1 alpha-2 country code, for example US.
`email`	`string` nullable	optional	Contact email address.
`federalTaxId`	`string` nullable	optional	Federal tax identifier of the party at this address, used on customs paperwork for international shipments.
`name`	`string` nullable	optional	Contact name at the address.
`phone`	`string`	required	Contact phone number. FedEx and DHL reject shipments whose addresses carry no phone number, so supply one whenever those carriers may be used.
`residential`	`boolean` nullable	optional	Whether the address is residential. Carriers price residential delivery differently, so an incorrect value can change the rates you are quoted.
`state`	`string`	required	State, province or region. For US addresses, the two-letter state code.
`stateTaxId`	`string` nullable	optional	State tax identifier of the party at this address, used on customs paperwork for international shipments.
`street1`	`string`	required	First street line — house or building number and street.
`street2`	`string` nullable	optional	Second street line: apartment, suite, unit or floor.
`zip`	`string`	required	Postal or ZIP code.

`OrderAddressResponse`

A postal address as Mailhub stored it.

Field	Type	Required	Description
`carrierFacility`	`string` nullable	required	Carrier facility this address refers to, when one was supplied.
`city`	`string`	required	City or locality.
`company`	`string` nullable	required	Company name at the address.
`country`	`string`	required	Two-letter ISO 3166-1 alpha-2 country code, for example US.
`createdAt`	`string (date-time)`	required	UTC instant the address record was created. Format: `date-time`
`email`	`string` nullable	required	Contact email address.
`federalTaxId`	`string` nullable	required	Federal tax identifier recorded for customs paperwork.
`id`	`string`	required	Identifier of the stored address record.
`name`	`string` nullable	required	Contact name at the address.
`phone`	`string` nullable	required	Contact phone number.
`residential`	`boolean` nullable	required	Whether the address is residential.
`state`	`string`	required	State, province or region. For US addresses, the two-letter state code.
`stateTaxId`	`string` nullable	required	State tax identifier recorded for customs paperwork.
`street1`	`string`	required	First street line — house or building number and street.
`street2`	`string` nullable	required	Second street line: apartment, suite, unit or floor.
`updatedAt`	`string (date-time)`	required	UTC instant the address record was last modified. Format: `date-time`
`zip`	`string`	required	Postal or ZIP code.

`OrderCustomer`

Who the order is going to.

Field	Type	Required	Description
`email`	`string` nullable	required	Recipient email recorded on the destination address.
`name`	`string` nullable	required	Recipient name recorded on the destination address.
`phone`	`string` nullable	required	Recipient phone recorded on the destination address.

`OrderDestination`

Where the order is going.

Field	Type	Required	Description
`city`	`string`	required	Destination city or locality.
`country`	`string`	required	Destination country as a two-letter ISO 3166-1 alpha-2 code.
`state`	`string` nullable	required	Destination state, province or region.
`street1`	`string` nullable	required	First street line of the destination address.
`street2`	`string` nullable	required	Second street line of the destination address.
`zip`	`string` nullable	required	Destination postal or ZIP code.

`OrderLabelAsset`

A label asset and, when it has been generated, a temporary link that downloads it directly from storage without an API token.

Field	Type	Required	Description
`format`	`string`	required	The label file format this entry describes: PDF, ZPL203DPI, ZPL300DPI or ZPL600DPI. Allowed values: `PDF`, `ZPL300DPI`, `ZPL203DPI`, `ZPL600DPI`
`status`	`string`	required	completed when the file exists and url is filled in, processing while it is still being rendered. Every listed format is eventually produced, so processing means "come back", not "unavailable". Allowed values: `completed`, `processing`
`url`	`string` nullable	required	Time-limited link that downloads the file directly, without an API token. It expires; request the order again for a fresh one.

`OrderListItem`

One order in a list page — enough to identify it and show where it is going.

Field	Type	Required	Description
`carrier`	`string` nullable	required	Name of the carrier on the rate that was bought.
`customerName`	`string` nullable	required	Recipient name recorded on the destination address.
`destinationCity`	`string`	required	Destination city or locality.
`destinationCountry`	`string`	required	Destination country as a two-letter ISO 3166-1 alpha-2 code.
`destinationZip`	`string` nullable	required	Destination postal or ZIP code.
`id`	`string (guid)`	required	Identifier of the order. Pass it to the order retrieval operation for the full record. Format: `guid`
`labelId`	`string (guid)` nullable	required	Identifier of the most recent label bought for the order, when one exists. Format: `guid`
`orderDate`	`string (date-time)`	required	UTC instant the order was created. Format: `date-time`
`serviceLevel`	`string` nullable	required	Human-readable name of the service on the rate that was bought, for example USPS Priority Mail. Note that the single-order operation returns the carrier's raw service code in its field of the same name; the two are not interchangeable.
`shipDate`	`string (date-time)` nullable	required	Date the label was mailed on, falling back to the instant the label was created when the carrier supplied no mailing date. Format: `date-time`
`shipmentId`	`string (guid)` nullable	required	Identifier of the order's most recent shipment, when it has one. Format: `guid`
`source`	`OrderSource`	required
`status`	`OrderStatus`	required
`trackingNumber`	`string` nullable	required	Carrier tracking number for the shipment, once a label has been bought.

`OrderListPage`

One page of results, with enough counters to walk the rest.

Field	Type	Required	Description
`hasNext`	`boolean`	required	Whether a page follows this one.
`hasPrevious`	`boolean`	required	Whether a page precedes this one.
`items`	`OrderListItem[]`	required	The entries on this page.
`pageNumber`	`integer (int32)`	required	Which page this is, counting from 1. Format: `int32`
`pageSize`	`integer (int32)`	required	Maximum number of entries a page may hold. Format: `int32`
`totalItemsCount`	`integer (int32)`	required	Total number of entries across all pages, not just this one. Format: `int32`
`totalPages`	`integer (int32)`	required	How many pages the full result set spans. Format: `int32`

`OrderPackage`

Dimensions and weight recorded for the shipment.

Field	Type	Required	Description
`height`	`number (decimal)` nullable	required	Shortest side of the package in inches, as supplied on the order. Format: `decimal`
`length`	`number (decimal)` nullable	required	Longest side of the package in inches, as supplied on the order. Format: `decimal`
`predefinedPackage`	`string` nullable	required	Carrier-defined packaging named on the order, when dimensions were not given.
`weight`	`number (decimal)` nullable	required	Package weight in pounds. Format: `decimal`
`width`	`number (decimal)` nullable	required	Second-longest side of the package in inches, as supplied on the order. Format: `decimal`

`OrderParcelRequest`

The physical package. Give explicit dimensions, or name a carrier predefinedPackage.

Field	Type	Required	Description
`height`	`number (decimal)` nullable	optional	Shortest side of the package, in inches. Format: `decimal`
`length`	`number (decimal)` nullable	optional	Longest side of the package, in inches. Supply length, width and height together, or supply predefinedPackage instead. Dimensions are sent to every carrier in inches. Format: `decimal`
`predefinedPackage`	`string` nullable	optional	Carrier-defined packaging to use instead of explicit dimensions, for example a flat-rate box. The accepted values depend on the carrier.
`weight`	`number (decimal)`	required	Package weight in pounds. Format: `decimal`
`width`	`number (decimal)` nullable	optional	Second-longest side of the package, in inches. Format: `decimal`

`OrderParcelResponse`

The physical package recorded for a shipment.

Field	Type	Required	Description
`createdAt`	`string (date-time)`	required	UTC instant the parcel record was created. Format: `date-time`
`height`	`number (decimal)` nullable	required	Shortest side of the package in inches, as supplied on the order. Format: `decimal`
`id`	`string`	required	Identifier of the stored parcel record.
`length`	`number (decimal)` nullable	required	Longest side of the package in inches, as supplied on the order. Format: `decimal`
`predefinedPackage`	`string` nullable	required	Carrier-defined packaging named on the order, when dimensions were not given.
`updatedAt`	`string (date-time)`	required	UTC instant the parcel record was last modified. Format: `date-time`
`weight`	`number (decimal)`	required	Package weight in pounds. Format: `decimal`
`width`	`number (decimal)` nullable	required	Second-longest side of the package in inches, as supplied on the order. Format: `decimal`

`OrderRequest`

The order itself: where it ships from, where it ships to, and the packages it contains.

Field	Type	Required	Description
`fromAddress`	`OrderAddressRequest`	required
`shipments`	`OrderShipmentRequest[]`	required	Packages to ship. One shipment per package; each is rated and labelled on its own.
`toAddress`	`OrderAddressRequest`	required

`OrderShipmentRequest`

One package within an order. Each shipment is rated and labelled independently.

Field	Type	Required	Description
`parcel`	`OrderParcelRequest`	required

`OrderShipmentResponse`

One package on the order, as Mailhub recorded it.

Field	Type	Required	Description
`createdAt`	`string (date-time)`	required	UTC instant the shipment was created. Format: `date-time`
`fromAddress`	`OrderAddressResponse`	required
`id`	`string`	required	Identifier of the shipment. Use it on the rate and label-purchase operations.
`isReturn`	`boolean`	required	Whether the shipment is a return back to the sender.
`parcel`	`OrderParcelResponse`	required
`status`	`string`	required	Shipment status as the enum member name. Values are Unknown, PreTransit, InTransit, OutForDelivery, Delivered, AvailableForPickup, ReturnToSender, Failure, Cancelled and Error. Carrier tracking is not yet wired in, so in practice this reads Unknown. Allowed values: `Unknown`, `PreTransit`, `InTransit`, `OutForDelivery`, `Delivered`, `AvailableForPickup`, `ReturnToSender`, `Failure`, `Cancelled`, `Error`
`toAddress`	`OrderAddressResponse`	required
`updatedAt`	`string (date-time)`	required	UTC instant the shipment was last modified. Format: `date-time`

`OrderShipmentSummary`

The order's most recent shipment and the label bought for it, if any.

Field	Type	Required	Description
`carrier`	`string` nullable	required	Name of the carrier on the rate that was bought.
`labelAssets`	`OrderLabelAsset[]`	required	One entry per printable label format, each with a temporary download link when the asset exists. The links expire, so this is also how to obtain fresh ones after the links returned at purchase time have lapsed: request the order again — there is no refresh call.
`labelId`	`string (guid)` nullable	required	Identifier of the most recent label bought for this shipment, when one exists. Format: `guid`
`labelStatus`	`LabelStatus` nullable	required	Status of the most recent label: 0 = Unknown, 1 = Created, 2 = Printed, 3 = Cancelled, 4 = Error.
`package`	`OrderPackage` nullable	required	Dimensions and weight recorded for the shipment.
`serviceLevel`	`string` nullable	required	The carrier's own service code for the rate that was bought, for example Priority or GroundAdvantage — the raw code, not a display name. Note that the order list operation returns a human-readable service name in its field of the same name; the two are not interchangeable.
`shipDate`	`string (date-time)` nullable	required	Date the label was mailed on, falling back to the instant the label was created when the carrier supplied no mailing date. Format: `date-time`
`shipmentId`	`string (guid)`	required	Identifier of the shipment. Format: `guid`
`trackingNumber`	`string` nullable	required	Carrier tracking number for the shipment, once a label has been bought.

`OrderSource`

Where an order came from, in the product's own vocabulary.

Allowed values: Manual, API, Shopify

Type string.

`OrderSourceCode`

Where an order came from, in the product's own vocabulary.

Allowed values: 1, 2, 3

Type integer.

`OrderStatus`

Where an order stands in the fulfilment workflow, published as the numeric value: 0 = Created — saved and workable; a label can be bought from here. 1 = Requested — reserved for e-commerce intake; no path sets it yet. 2 = OnHold — paused, and not shippable while paused; resuming returns it to the status it was held from. 3 = Cancelled — cancelled before a label was bought; terminal. 4 = Fulfilled — handed over to the carrier. 5 = Processing — being prepared. 6 = Picked — items picked. 7 = Packed — packed and ready for a label; also where an order lands when its label is cancelled. 8 = LabelCreated — a label is live at the carrier. Set by the purchase itself, never accepted from a caller. 9 = Returned — returned after fulfilment; terminal. 10 = Error — a failure state the system sets for itself; rejected if a caller tries to set it. 11 = Draft — a wizard draft: persisted, but omitted from order list results until it is saved or labelled.

Allowed values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11

Type integer.

`RateQuote`

One priced shipping option for a package: which carrier and service, what it costs and how fast it is expected to be. Returned by the rate and combined create-and-rate operations.

Field	Type	Required	Description
`billingType`	`string` nullable	required	How the carrier bills this rate, in the carrier's own vocabulary.
`carrier`	`string`	required	The carrier offering the rate, for example USPS or UPS.
`carrierCode`	`string` nullable	required	The carrier's own account or brand code, when the carrier supplies one.
`currency`	`string`	required	Currency of rate, as an ISO 4217 three-letter code. The set of codes a carrier may return is not constrained by this contract.
`deliveryDateGuaranteed`	`boolean`	required	Whether the carrier guarantees the delivery date rather than estimating it.
`deliveryDays`	`integer (int32)`	required	Carrier-supplied transit estimate, in days. This is not a commitment: every carrier integration fills deliveryDays and estDeliveryDays from one quantity, so the two always carry the same number on a given rate. 0 means the carrier supplied no transit time for this rate, not same-day delivery. The day basis is the carrier's own — UPS reports business days in transit, USPS a span derived from its quoted delivery window — so do not compare the number across carriers. Read deliveryDateGuaranteed for whether anything is guaranteed. Format: `int32`
`destinationEntryFacilityType`	`string` nullable	required	USPS destination entry facility the price assumes, when the carrier is USPS.
`estDeliveryDays`	`integer (int32)`	required	Carrier-supplied transit estimate, in days. Currently always equal to deliveryDays: both are filled from the same carrier quantity on every integration, and neither is a separate estimated-versus-committed figure. 0 means the carrier supplied no transit time. Format: `int32`
`estimatedDeliveryDate`	`string (date-time)` nullable	required	Date the carrier expects to deliver on. null when the carrier supplied no date, which is the common case for carriers that report transit days instead. The label-purchase response republishes this same value under the name selectedRate.deliveryDate. Format: `date-time`
`id`	`string (guid)` nullable	required	Identifier of this rate. Send it as rate.id to the label operation to buy this exact option; a rate cannot be reconstructed from its other fields. Format: `guid`
`listCurrency`	`string` nullable	required	Currency of listRate, as an ISO 4217 three-letter code.
`listRate`	`number (decimal)` nullable	required	The carrier's published list price for the same service, when the carrier publishes one. Like retailRate, a comparison figure rather than the charged amount. Format: `decimal`
`mailClass`	`string` nullable	required	USPS mail class for the rate, when the carrier is USPS.
`processingCategory`	`string` nullable	required	USPS processing category for the package, when the carrier is USPS.
`rate`	`number (decimal)`	required	The amount your account is charged if this rate is bought. Format: `decimal`
`rateIndicator`	`string` nullable	required	USPS rate indicator describing how the price was derived, when the carrier is USPS.
`retailCurrency`	`string` nullable	required	Currency of retailRate, as an ISO 4217 three-letter code.
`retailRate`	`number (decimal)` nullable	required	The carrier's over-the-counter retail price for the same service, when the carrier publishes one. It is a comparison figure, not what you are charged. Format: `decimal`
`serviceCode`	`string`	required	The carrier's own code for the service, for example GroundAdvantage. This is the machine value; serviceName is the readable one.
`serviceName`	`string`	required	Readable name of the service, for example USPS Ground Advantage. Suitable for display; match on serviceCode rather than on this.
`sku`	`string` nullable	required	The carrier's own product code for this rate, when it supplies one.
`zone`	`string` nullable	required	Carrier delivery zone between origin and destination, when the carrier reports one.

`UpdateOrderStatusRequest`

Moves an order to a new status.

Field	Type	Required	Description
`reason`	`string` nullable	optional	Free-text note explaining why the status was changed. Recorded on the order's status history.
`source`	`string` nullable	optional	Free-text label for what triggered the change, recorded alongside the reason. This is your own annotation and does not affect how Mailhub processes the order.
`status`	`OrderStatus`	optional

`UpdateOrderStatusResponse`

The status change that was applied: previousStatus is where the order was, currentStatus is where it is now.

Field	Type	Required	Description
`currentStatus`	`OrderStatus`	required
`orderId`	`string (guid)`	required	Identifier of the order whose status changed. Format: `guid`
`previousStatus`	`OrderStatus`	required
`updatedAt`	`string (date-time)`	required	UTC instant the change was applied. Format: `date-time`

`UpdateOrderStatusResponseEnvelope`

The envelope every JSON operation answers with: a success flag and either a result or errors.

Field	Type	Required	Description
`data`	`UpdateOrderStatusResponse` nullable	required	The operation's result. Absent when the call failed.
`errors`	`ApiError[]` nullable	required	What went wrong. Absent when the call succeeded.
`success`	`boolean`	required	Whether the operation succeeded. When false, read errors.

Operations

GET /api/v1/orders

Parameters

Responses

POST /api/v1/orders

Parameters

Request body (required)

Responses

GET /api/v1/orders/{orderId}

Parameters

Responses

PATCH /api/v1/orders/{orderId}/status

Parameters

Request body (required)

Responses

POST /api/v2/orders

Parameters

Request body (required)

Responses

Schemas

ApiError

CarrierRateResult

CreateOrderRequest

CreateOrderResponse

CreateOrderResponseEnvelope

CreateOrderV2Request

CreateOrderV2Response

CreateOrderV2ResponseEnvelope

CreateOrderV2ShipmentRates

ErrorEnvelope

GetOrderResponse

GetOrderResponseEnvelope

LabelStatus

ListOrdersResponse

ListOrdersResponseEnvelope

OrderAddressRequest

OrderAddressResponse

OrderCustomer

OrderDestination

OrderLabelAsset

OrderListItem

OrderListPage

OrderPackage

OrderParcelRequest

OrderParcelResponse

OrderRequest

OrderShipmentRequest

OrderShipmentResponse

OrderShipmentSummary

OrderSource

OrderSourceCode

OrderStatus

RateQuote

UpdateOrderStatusRequest

UpdateOrderStatusResponse

UpdateOrderStatusResponseEnvelope

GET `/api/v1/orders`

POST `/api/v1/orders`

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

PATCH `/api/v1/orders/{orderId}/status`

POST `/api/v2/orders`

`ApiError`

`CarrierRateResult`

`CreateOrderRequest`

`CreateOrderResponse`

`CreateOrderResponseEnvelope`

`CreateOrderV2Request`

`CreateOrderV2Response`

`CreateOrderV2ResponseEnvelope`

`CreateOrderV2ShipmentRates`

`ErrorEnvelope`

`GetOrderResponse`

`GetOrderResponseEnvelope`

`LabelStatus`

`ListOrdersResponse`

`ListOrdersResponseEnvelope`

`OrderAddressRequest`

`OrderAddressResponse`

`OrderCustomer`

`OrderDestination`

`OrderLabelAsset`

`OrderListItem`

`OrderListPage`

`OrderPackage`

`OrderParcelRequest`

`OrderParcelResponse`

`OrderRequest`

`OrderShipmentRequest`

`OrderShipmentResponse`

`OrderShipmentSummary`

`OrderSource`

`OrderSourceCode`

`OrderStatus`

`RateQuote`

`UpdateOrderStatusRequest`

`UpdateOrderStatusResponse`

`UpdateOrderStatusResponseEnvelope`