Create an Order with Rates

POST/api/v2/orders Open this operation in the API Reference.

Mailhub provides two Order creation operations. Use standard Order creation when you want to create the Order first and request Rates later. Use Create an Order with Rates when you want Mailhub to create the Order and immediately request Rates for its Shipments in the same API call.

Compare the creation choices

Behavior	POST /api/v1/orders	POST /api/v2/orders
Creates	One Order	One Order
Request body	Order fields at the top level	Required top-level order wrapper
Rates during creation	No	Yes, for each created Shipment
Success response	201 created Order	200 created Order plus shipmentRates
Typical next step	Request Shipment Rates	Select a returned Rate
Label purchase	Separate	Separate

Both operations create the same public Order resource. The create-and-rate operation uses the same underlying Order-creation workflow, then requests Rates for each created Shipment. One Order can contain one or more Shipments.

Request

The request accepts exactly one Order under the required order property. It is one Order per request, not a batch operation, and does not accept an orders array.

{
  "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}}
    ]
  }
}

See Create an Order for the verified address and parcel requirements.

Read the response

The order in a successful 200 response is the created Order. shipmentRates is grouped by Shipment: each entry identifies a created Shipment and contains that Shipment's returned Rate results. Your application chooses a returned rate.id; Mailhub does not select a Rate or buy a Label in this operation.

Use the selected Rate with Buy label. That remains a separate operation. Do not infer a preferred Rate from response order.

Complete success response

Every field below is one the public contract declares for this operation. The carrier, serviceCode, and serviceName values are illustrative — see Carrier Availability.

{
  "success": true,
  "data": {
    "status": "created",
    "order": {
      "id": "5f2c1a10-2b3d-4e5f-8a9b-0c1d2e3f4a5b",
      "status": "Created",
      "isReturn": false,
      "createdAt": "2026-08-20T14:31:07.482Z",
      "updatedAt": "2026-08-20T14:31:07.482Z",
      "fromAddress": {
        "id": "8c5e0f14-7a2b-4d36-9e81-2f6a4b90c7d3",
        "name": "Jane Sender",
        "company": null,
        "street1": "123 Main St",
        "street2": null,
        "city": "Austin",
        "state": "TX",
        "zip": "78701",
        "country": "US",
        "phone": "5125550100",
        "email": null,
        "residential": null,
        "federalTaxId": null,
        "stateTaxId": null,
        "carrierFacility": null,
        "createdAt": "2026-08-20T14:31:07.482Z",
        "updatedAt": "2026-08-20T14:31:07.482Z"
      },
      "toAddress": {
        "id": "2d90a7b6-3f18-4e52-8c47-6b1d0e35f9a2",
        "name": "John Recipient",
        "company": null,
        "street1": "456 Oak Ave",
        "street2": null,
        "city": "Denver",
        "state": "CO",
        "zip": "80202",
        "country": "US",
        "phone": "3035550100",
        "email": null,
        "residential": null,
        "federalTaxId": null,
        "stateTaxId": null,
        "carrierFacility": null,
        "createdAt": "2026-08-20T14:31:07.482Z",
        "updatedAt": "2026-08-20T14:31:07.482Z"
      },
      "shipments": [
        {
          "id": "b91a2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
          "status": "Created",
          "isReturn": false,
          "createdAt": "2026-08-20T14:31:07.482Z",
          "updatedAt": "2026-08-20T14:31:07.482Z",
          "fromAddress": {
            "id": "8c5e0f14-7a2b-4d36-9e81-2f6a4b90c7d3",
            "name": "Jane Sender",
            "company": null,
            "street1": "123 Main St",
            "street2": null,
            "city": "Austin",
            "state": "TX",
            "zip": "78701",
            "country": "US",
            "phone": "5125550100",
            "email": null,
            "residential": null,
            "federalTaxId": null,
            "stateTaxId": null,
            "carrierFacility": null,
            "createdAt": "2026-08-20T14:31:07.482Z",
            "updatedAt": "2026-08-20T14:31:07.482Z"
          },
          "toAddress": {
            "id": "2d90a7b6-3f18-4e52-8c47-6b1d0e35f9a2",
            "name": "John Recipient",
            "company": null,
            "street1": "456 Oak Ave",
            "street2": null,
            "city": "Denver",
            "state": "CO",
            "zip": "80202",
            "country": "US",
            "phone": "3035550100",
            "email": null,
            "residential": null,
            "federalTaxId": null,
            "stateTaxId": null,
            "carrierFacility": null,
            "createdAt": "2026-08-20T14:31:07.482Z",
            "updatedAt": "2026-08-20T14:31:07.482Z"
          },
          "parcel": {
            "id": "7e41b3c8-5d69-4a02-9b7f-1c8e2a604d5b",
            "weight": 16,
            "length": 10,
            "width": 8,
            "height": 4,
            "predefinedPackage": null,
            "createdAt": "2026-08-20T14:31:07.482Z",
            "updatedAt": "2026-08-20T14:31:07.482Z"
          }
        }
      ]
    },
    "shipmentRates": [
      {
        "shipmentId": "b91a2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
        "rates": [
          {
            "id": "c4a1b2d3-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
            "carrier": "USPS",
            "carrierCode": null,
            "serviceCode": "<carrier-specific service code>",
            "serviceName": "USPS Ground Advantage",
            "rate": 8.42,
            "currency": "USD",
            "listRate": 9.1,
            "listCurrency": "USD",
            "retailRate": 11.3,
            "retailCurrency": "USD",
            "deliveryDays": 3,
            "estDeliveryDays": 3,
            "deliveryDateGuaranteed": false,
            "estimatedDeliveryDate": "2026-08-23T00:00:00Z",
            "billingType": null,
            "mailClass": null,
            "zone": null,
            "sku": null,
            "rateIndicator": null,
            "processingCategory": null,
            "destinationEntryFacilityType": null
          }
        ],
        "carrierResponses": [
          {"carrier": "USPS", "success": true, "errorCode": null, "errorMessage": null}
        ],
        "errors": []
      }
    ],
    "errors": []
  },
  "errors": null
}

Three errors arrays appear in this response and they are not the same thing:

Field	On a 200
errors (envelope)	null — the envelope's own failure list.
data.errors	[].
data.shipmentRates[].errors	Can carry entries. One Shipment can fail to rate while another returns Rates, and the request still succeeds.

Read data.shipmentRates[].errors and carrierResponses per Shipment before treating a 200 as complete for every Shipment in the Order.

Optional fields are shown as null rather than omitted so the shape is unambiguous; the exact set a carrier populates varies. See API Conventions for the envelope rules.

No-Rate 422 outcome

Do not blindly retry a no-Rate 422

A 422 can mean invalid input or that no created Shipment returned a Rate. In the no-Rate case, the Order may already have been created. The public API does not define a safe automatic retry or reconciliation workflow for this outcome.

The public response does not promise an Order identifier or recovery sequence for this ambiguous state-changing outcome.

Next steps

• Create an Order and Get Rates in One Call — the same operation as a copyable request sequence.
• Select a Rate
• Buy a Label
• Retries and Ambiguous Outcomes