POST `/ship/{rateResponseId}`

Create a shipment (label/order) from a rate response returned by Rate.

Scope: shipments:create

Path parameters

Name	Required	Description
`rateResponseId`	Yes	UUID from `rates[].rateResponseId` in the rate response

Request body

Not used. Billing is taken from the organization tied to the API key, not from the client.

Preconditions

Rate response exists and belongs to the API key’s companyId (via linked rate request).
Organization billing.type must be "account" (on-account billing). Otherwise 403.

Success response (`200`)

The response is wrapped in data:

{
  "data": {
    "status": "success",
    "title": {
      "en": "Order created",
      "fr": "Commande créée"
    },
    "metadata": {
      "orderId": "uuid-order-id",
      "orderNumber": "SOE-12345",
      "trackingNumber": "carrier-master-tracking-id",
      "labels": {
        "available": [
          {
            "code": "PDF",
            "name": {
              "en": "PDF",
              "fr": "PDF"
            },
            "url": "https://api.saveonexpress.ca/integrations/public-api/v1/labels/uuid-order-id/PDF"
          }
        ]
      }
    }
  }
}

Use metadata.orderId for Track, Labels, and Cancel.

metadata.labels (when present) lists label types available for the order. Each entry includes a url on this public API (GET with the same API key). Types depend on carrier and shipment options (e.g. PDF, ZPL, COMINV, PACKSLIP). If label discovery fails after a successful ship, the response is still status: "success" but labels may be omitted.

Business / carrier failure (`200` with error payload)

Ship returns HTTP 200 even when shipment creation fails:

{
  "data": {
    "status": "error",
    "title": {
      "en": "Create order failed",
      "fr": "Création de la commande échouée"
    },
    "messages": [
      {
        "message": { "en": "Carrier error message", "fr": "..." },
        "severity": "error"
      }
    ],
    "metadata": {}
  }
}

Always check data.status === "success" before treating the call as successful.

Error responses

HTTP	Condition
`400`	Missing `rateResponseId`
`401`	API key auth failure
`403`	Missing scope, wrong company, or organization billing is not `account`
`404`	Rate response not found
`500`	Unexpected error

Path parameters​

Request body​

Preconditions​

Success response (200)​

Business / carrier failure (200 with error payload)​

Error responses​