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

1. Rate response exists and belongs to the API key’s companyId (via linked rate request).
2. 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": "1234567890",
      "trackingUrl": "https://www.fedex.com/fedextrack/?trknbr=1234567890",
      "trackingUrlTemplate": "https://www.fedex.com/fedextrack/?trknbr={trackingCode}",
      "labels": {
        "available": [
          {
            "code": "PDF",
            "name": {
              "en": "PDF",
              "fr": "PDF"
            },
            "url": "https://api.{env}.saveonexpress.ca/integrations/public-api/v1/labels/uuid-order-id/PDF"
          }
        ]
      }
    }
  }
}

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

Field	Type	Description
orderId	string	Order UUID — use for Track, Labels, Cancel
orderNumber	string	Human-readable order number
trackingNumber	string	Carrier master tracking number
trackingUrl	string	Ready-to-use carrier tracking link. Prefer this — no client-side substitution required. Omitted when the carrier has no template or tracking number is missing.
trackingUrlTemplate	string	Carrier URL pattern with {trackingCode} placeholder. Included when a template exists for the carrier.
labels	object	Available label types (when present)

Tracking links: After a successful ship, use metadata.trackingUrl directly for customer-facing tracking. trackingUrlTemplate is provided for reference when you need the pattern; substitute {trackingCode} with trackingNumber only if trackingUrl is absent.

Supported carrier codes for tracking URLs: canpar-express, purolator-freight, purolator-express, gls-freight, gls-parcel, day-ross-freight, federal-express, fedex-freight, dhl-express, canada-post, nationex, ups-parcel.

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