{
  "openapi": "3.0.3",
  "info": {
    "title": "OminiShip Open API",
    "version": "1.0.0",
    "description": "OminiShip Open API v1. For the full guide (quick start, customer order number rules, cancellation approval, test keys and the error code table), see OPEN_API_GUIDE.en.md in the same directory.\n\n- One key is bound to one customer; requests do not pass a customer id.\n- All 7 endpoints are POST + application/json.\n- Every reply that passes through our service is the envelope { success, code, message, data, requestId }; the 404 / 429 / 504 returned by the gateway itself are the exception.\n- Amounts are strings with two decimal places, in USD.\n- Requests with a test key (zsk_test_…) never touch a carrier and never charge you.\n- You generate and revoke keys yourself in the OminiShip dashboard under Settings → API Keys (at most 2 active keys of each type; the full key is shown only once).",
    "x-changelog": [
      {
        "date": "2026-10-19",
        "version": "1.0.0",
        "changes": "First release of v1."
      },
      {
        "date": "2026-10-20",
        "version": "1.0.0",
        "changes": "Keys are now generated, viewed and revoked by you in the OminiShip dashboard under Settings → API Keys (no more requests by email); the advice for API_KEY_REVOKED was updated accordingly. Endpoints and reply format unchanged."
      },
      {
        "date": "2026-10-27",
        "version": "1.0.0",
        "changes": "Added the English edition of this spec (English descriptions, identical structure). Endpoints and reply format unchanged."
      },
      {
        "date": "2026-10-31",
        "version": "1.0.0",
        "changes": "Rates (shipments[].serviceCodeGroup) and create orders (orders[].serviceCodeGroup) can rate / order by a service code group's name, using the cheapest service in the group; a group rate returns one rate, with serviceCode / carrier / service set to null and without saying which service it is. The serviceCode of CreateOrderItem is now one of two with serviceCodeGroup. New error codes SERVICE_CODE_GROUP_NOT_FOUND and SERVICE_CODE_GROUP_EMPTY. Requests and replies that only use serviceCode are unchanged."
      },
      {
        "date": "2026-11-04",
        "version": "1.0.0",
        "changes": "One tracking number per package: an order with several packages (quantity counted) is split into several independent orders when created, each with 1 package, with the customer order number as the group number; added PackageGroupResult (one result when create / info / labels / cancel act on the whole group by its customer order number), Rate.packageRates (rates package by package) and packageIndex / packageCount on split orders; for an order with several packages the balance must cover all of them before anything is bought (otherwise the whole item gets INSUFFICIENT_BALANCE with required / shortfall and nothing is created); maxCharge cannot be used yet with several packages in one order; at most 50 packages per shipment, and the 200-combination limit counts different package sizes. Requests and replies with only one package are unchanged."
      },
      {
        "date": "2026-11-14",
        "version": "1.0.0",
        "changes": "Limits now count packages (= orders): create takes at most 500 packages per request in all (quantity counted; an item that fails validation counts 0; an item with more than 50 packages counts 50 and is still refused itself); order info 100, labels 500 / 20 / 100 (by format) and cancel 500 count the orders the identifiers name, and a customerOrderNo naming a split group counts every order of the group. Over the limit, the whole request is a 400 BATCH_TOO_LARGE and nothing is done (no order created, no charge, no label read, no cancellation submitted); ErrorData adds maxPackages (the package / order limit) and packages (this request's count; null when only the item count is over). The item limits are unchanged; requests within the limits and their replies are unchanged."
      },
      {
        "date": "2026-11-16",
        "version": "1.0.0",
        "changes": "Two new read-only endpoints: POST /v1/balance (balance, reserved, frozen, available amount, credit; available is the very figure the create-orders endpoint checks) and POST /v1/orders/list (every order of the customer bound to the key, oldest first by creation time, page by page with nextCursor, for reconciliation and incremental sync). New error code INVALID_CURSOR. Requests and replies of the other endpoints are unchanged."
      },
      {
        "date": "2026-11-18",
        "version": "1.0.0",
        "changes": "When a US shipTo address (shipTo.country empty / US / USA) has a shipTo.phone that is filled in but is not exactly 10 digits (no +1, extension, spaces, dashes or parentheses), rates and orders are refused: new error code RECEIVER_PHONE_INVALID (errors[] points at shipTo.phone; nothing is rated, created or charged). Creating a draft (confirm: false) and resending a number to get back the order it already has are not affected; shipFrom and non-US addresses are not checked. Other requests and replies are unchanged."
      }
    ]
  },
  "servers": [
    {
      "url": "https://openapi.ominiship.com",
      "description": "Production (test keys and live keys use the same base URL)"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "rates",
      "description": "Rates"
    },
    {
      "name": "orders",
      "description": "Orders"
    },
    {
      "name": "account",
      "description": "Account"
    }
  ],
  "paths": {
    "/v1/rates": {
      "post": {
        "operationId": "getRates",
        "tags": [
          "rates"
        ],
        "summary": "Batch rates",
        "description": "1..100 items per request; leave out serviceCode = rate every service you can use; you can also give serviceCodeGroup (a service code group's name) to get the one lowest price in the group; \"items × services\" combinations ≤ 200 (above that the whole request gets 400 BATCH_TOO_LARGE and no carrier is asked). Fully synchronous, replies within about 20 seconds; services not rated in time go into unavailable (RATE_TIMEOUT, retryable). Getting rates is free.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RatesRequest"
              },
              "examples": {
                "twoShipments": {
                  "summary": "One item rates every service, one names a service (wrong postal code)",
                  "value": {
                    "unitSystem": "imperial",
                    "shipments": [
                      {
                        "ref": "quote-1",
                        "shipFrom": {
                          "name": "Warehouse A",
                          "company": "Acme Fulfillment",
                          "phone": "9095550100",
                          "email": "ops@example.com",
                          "address1": "1000 E Example Ave",
                          "address2": "Dock 3",
                          "city": "Ontario",
                          "state": "CA",
                          "postalCode": "91761",
                          "country": "US"
                        },
                        "shipTo": {
                          "name": "Jane Doe",
                          "phone": "2125550100",
                          "address1": "350 5th Ave",
                          "address2": "Apt 2",
                          "city": "New York",
                          "state": "NY",
                          "postalCode": "10118",
                          "country": "US",
                          "residential": true
                        },
                        "packages": [
                          {
                            "weight": 2.5,
                            "length": 10,
                            "width": 8,
                            "height": 4,
                            "quantity": 1
                          }
                        ]
                      },
                      {
                        "ref": "quote-2",
                        "serviceCode": "e2a7d913-5c40-4b8e-a1f6-0d9c3b7e5a21",
                        "shipFrom": {
                          "name": "Warehouse A",
                          "company": "Acme Fulfillment",
                          "phone": "9095550100",
                          "email": "ops@example.com",
                          "address1": "1000 E Example Ave",
                          "address2": "Dock 3",
                          "city": "Ontario",
                          "state": "CA",
                          "postalCode": "91761",
                          "country": "US"
                        },
                        "shipTo": {
                          "name": "Jane Doe",
                          "phone": "2125550100",
                          "address1": "350 5th Ave",
                          "address2": "Apt 2",
                          "city": "New York",
                          "state": "NY",
                          "postalCode": "1011",
                          "country": "US",
                          "residential": true
                        },
                        "packages": [
                          {
                            "weight": 2.5,
                            "length": 10,
                            "width": 8,
                            "height": 4,
                            "quantity": 1
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Processed. Check data.results[i].success item by item.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RatesResponse"
                },
                "examples": {
                  "mixed": {
                    "summary": "One success, one with an invalid field",
                    "value": {
                      "success": true,
                      "code": "OK",
                      "message": "Processed 2 item(s).",
                      "data": {
                        "summary": {
                          "total": 2,
                          "succeeded": 1,
                          "failed": 1
                        },
                        "results": [
                          {
                            "index": 0,
                            "success": true,
                            "code": "OK",
                            "message": "",
                            "retryable": false,
                            "ref": "quote-1",
                            "rates": [
                              {
                                "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                                "carrier": "usps",
                                "service": "usps_ground_advantage",
                                "totalCharge": "6.92",
                                "currency": "USD"
                              },
                              {
                                "serviceCode": "e2a7d913-5c40-4b8e-a1f6-0d9c3b7e5a21",
                                "carrier": "fedex",
                                "service": "fedex_ground",
                                "totalCharge": "9.87",
                                "currency": "USD"
                              }
                            ],
                            "unavailable": []
                          },
                          {
                            "index": 1,
                            "success": false,
                            "code": "INVALID_SHIPMENT",
                            "message": "The shipment is invalid; see errors for the fields to fix.",
                            "retryable": false,
                            "ref": "quote-2",
                            "rates": [],
                            "unavailable": [],
                            "errors": [
                              {
                                "field": "shipments[1].shipTo.postalCode",
                                "code": "INVALID_VALUE",
                                "message": "For a US address, postalCode must be 12345 or 12345-6789."
                              }
                            ]
                          }
                        ]
                      },
                      "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                    }
                  },
                  "noRate": {
                    "summary": "The carrier gave no rate",
                    "value": {
                      "success": true,
                      "code": "OK",
                      "message": "Processed 1 item(s).",
                      "data": {
                        "summary": {
                          "total": 1,
                          "succeeded": 0,
                          "failed": 1
                        },
                        "results": [
                          {
                            "index": 0,
                            "success": false,
                            "code": "NO_RATE",
                            "message": "The carrier returned no rate for this package. See carrierMessage for the carrier's own words.",
                            "retryable": false,
                            "ref": "quote-1",
                            "rates": [],
                            "unavailable": [
                              {
                                "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                                "code": "NO_RATE",
                                "message": "The carrier returned no rate for this package. See carrierMessage for the carrier's own words.",
                                "retryable": false,
                                "carrierMessage": "Package weight exceeds the maximum for this service."
                              }
                            ]
                          }
                        ]
                      },
                      "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/orders/create": {
      "post": {
        "operationId": "createOrders",
        "tags": [
          "orders"
        ],
        "summary": "Batch create orders",
        "description": "1..500 items per request. confirm = true (default) creates the order + charges + buys the label; false creates a draft only. Accepted first, labels bought in the background: when 20 or fewer items pass validation, it waits up to 15 seconds to bring back the outcomes already known, and the rest are PROCESSING (success is true; poll with /v1/orders/info). Idempotent by customer order number: resending the same number only returns that order and never charges you again. Each item gives serviceCode or serviceCodeGroup, exactly one of them. The packages of all items together (quantity counted) must be 500 or fewer; otherwise the whole request is a 400 BATCH_TOO_LARGE (data.maxPackages / data.packages), and nothing is created or charged.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOrdersRequest"
              },
              "examples": {
                "threeOrders": {
                  "summary": "Two valid items, one missing the city",
                  "value": {
                    "unitSystem": "imperial",
                    "confirm": true,
                    "orders": [
                      {
                        "customerOrderNo": "WMS-10001",
                        "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                        "shipDate": "2026-10-20",
                        "maxCharge": "25.00",
                        "shipFrom": {
                          "name": "Warehouse A",
                          "company": "Acme Fulfillment",
                          "phone": "9095550100",
                          "email": "ops@example.com",
                          "address1": "1000 E Example Ave",
                          "address2": "Dock 3",
                          "city": "Ontario",
                          "state": "CA",
                          "postalCode": "91761",
                          "country": "US"
                        },
                        "shipTo": {
                          "name": "Jane Doe",
                          "phone": "2125550100",
                          "address1": "350 5th Ave",
                          "address2": "Apt 2",
                          "city": "New York",
                          "state": "NY",
                          "postalCode": "10118",
                          "country": "US",
                          "residential": true
                        },
                        "packages": [
                          {
                            "weight": 2.5,
                            "length": 10,
                            "width": 8,
                            "height": 4,
                            "quantity": 1
                          }
                        ],
                        "references": {
                          "reference1": "PO-7781"
                        }
                      },
                      {
                        "customerOrderNo": "WMS-10002",
                        "serviceCode": "e2a7d913-5c40-4b8e-a1f6-0d9c3b7e5a21",
                        "shipFrom": {
                          "name": "Warehouse A",
                          "company": "Acme Fulfillment",
                          "phone": "9095550100",
                          "email": "ops@example.com",
                          "address1": "1000 E Example Ave",
                          "address2": "Dock 3",
                          "city": "Ontario",
                          "state": "CA",
                          "postalCode": "91761",
                          "country": "US"
                        },
                        "shipTo": {
                          "name": "Jane Doe",
                          "phone": "2125550100",
                          "address1": "350 5th Ave",
                          "address2": "Apt 2",
                          "city": "New York",
                          "state": "NY",
                          "postalCode": "10118",
                          "country": "US",
                          "residential": true
                        },
                        "packages": [
                          {
                            "weight": 12,
                            "length": 16,
                            "width": 12,
                            "height": 10,
                            "quantity": 1
                          }
                        ]
                      },
                      {
                        "customerOrderNo": "WMS-10003",
                        "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                        "shipFrom": {
                          "name": "Warehouse A",
                          "company": "Acme Fulfillment",
                          "phone": "9095550100",
                          "email": "ops@example.com",
                          "address1": "1000 E Example Ave",
                          "address2": "Dock 3",
                          "city": "Ontario",
                          "state": "CA",
                          "postalCode": "91761",
                          "country": "US"
                        },
                        "shipTo": {
                          "name": "Jane Doe",
                          "phone": "2125550100",
                          "address1": "350 5th Ave",
                          "address2": "Apt 2",
                          "city": "",
                          "state": "NY",
                          "postalCode": "10118",
                          "country": "US",
                          "residential": true
                        },
                        "packages": [
                          {
                            "weight": 2.5,
                            "length": 10,
                            "width": 8,
                            "height": 4,
                            "quantity": 1
                          }
                        ]
                      }
                    ]
                  }
                },
                "splitOrder": {
                  "summary": "One order with 3 packages (split into 3 orders)",
                  "value": {
                    "unitSystem": "imperial",
                    "orders": [
                      {
                        "customerOrderNo": "WMS-10005",
                        "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                        "shipFrom": {
                          "name": "Warehouse A",
                          "address1": "1000 E Example Ave",
                          "city": "Ontario",
                          "state": "CA",
                          "postalCode": "91761"
                        },
                        "shipTo": {
                          "name": "Jane Doe",
                          "address1": "350 5th Ave",
                          "city": "New York",
                          "state": "NY",
                          "postalCode": "10118"
                        },
                        "packages": [
                          {
                            "weight": 12,
                            "length": 16,
                            "width": 12,
                            "height": 10,
                            "quantity": 2
                          },
                          {
                            "weight": 2.5,
                            "length": 10,
                            "width": 8,
                            "height": 4
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Processed. Check data.results[i].success item by item.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateOrdersResponse"
                },
                "examples": {
                  "mixed": {
                    "summary": "Label bought / processing / invalid field",
                    "value": {
                      "success": true,
                      "code": "OK",
                      "message": "Processed 3 item(s).",
                      "data": {
                        "summary": {
                          "total": 3,
                          "succeeded": 2,
                          "failed": 1
                        },
                        "results": [
                          {
                            "index": 0,
                            "success": true,
                            "code": "OK",
                            "message": "",
                            "retryable": false,
                            "replayed": false,
                            "customerOrderNo": "WMS-10001",
                            "orderNo": "ORD-20261019-000123",
                            "status": "CREATED",
                            "statusReason": null,
                            "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                            "carrier": "usps",
                            "service": "usps_ground_advantage",
                            "totalCharge": "6.92",
                            "currency": "USD",
                            "trackingNumber": "9400111899223344556677",
                            "labelReady": true,
                            "labelStatus": "READY",
                            "labelUrl": "https://example.com/labels/ORD-20261019-000123?signature=abc123",
                            "labelUrlExpiresAt": "2026-10-19T09:00:00Z",
                            "trackingStatus": "PRE_SHIPMENT",
                            "trackingUpdatedAt": null,
                            "cancel": null,
                            "createdAt": "2026-10-19T08:00:00Z",
                            "submittedAt": "2026-10-19T08:00:03Z"
                          },
                          {
                            "index": 1,
                            "success": true,
                            "code": "OK",
                            "message": "",
                            "retryable": false,
                            "replayed": false,
                            "customerOrderNo": "WMS-10002",
                            "orderNo": "ORD-20261019-000124",
                            "status": "PROCESSING",
                            "statusReason": {
                              "code": "ORDER_PROCESSING",
                              "message": "We are buying this label. Check again shortly; do not resend with a new customerOrderNo.",
                              "carrierCode": null,
                              "carrierMessage": null,
                              "quotedCharge": null
                            },
                            "serviceCode": "e2a7d913-5c40-4b8e-a1f6-0d9c3b7e5a21",
                            "carrier": "fedex",
                            "service": "fedex_ground",
                            "totalCharge": null,
                            "currency": "USD",
                            "trackingNumber": null,
                            "labelReady": false,
                            "labelStatus": "NOT_CREATED",
                            "labelUrl": null,
                            "labelUrlExpiresAt": null,
                            "trackingStatus": null,
                            "trackingUpdatedAt": null,
                            "cancel": null,
                            "createdAt": "2026-10-19T08:00:00Z",
                            "submittedAt": null
                          },
                          {
                            "index": 2,
                            "success": false,
                            "code": "INVALID_ORDER",
                            "message": "The order is invalid; see errors for the fields to fix. Nothing was created — fix it and send it again (the same customerOrderNo may be used).",
                            "retryable": false,
                            "customerOrderNo": "WMS-10003",
                            "errors": [
                              {
                                "field": "orders[2].shipTo.city",
                                "code": "REQUIRED",
                                "message": "This field is required."
                              }
                            ]
                          }
                        ]
                      },
                      "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                    }
                  },
                  "failed": {
                    "summary": "Insufficient balance (nothing bought, nothing charged)",
                    "value": {
                      "success": true,
                      "code": "OK",
                      "message": "Processed 1 item(s).",
                      "data": {
                        "summary": {
                          "total": 1,
                          "succeeded": 0,
                          "failed": 1
                        },
                        "results": [
                          {
                            "index": 0,
                            "success": false,
                            "code": "INSUFFICIENT_BALANCE",
                            "message": "Your available balance (balance minus amounts reserved for orders in progress or frozen by us) is not enough for this label. Nothing was bought or charged; top up, or ask us to unfreeze, then resend the same request unchanged.",
                            "retryable": true,
                            "replayed": false,
                            "customerOrderNo": "WMS-10004",
                            "orderNo": "ORD-20261019-000125",
                            "status": "FAILED",
                            "statusReason": {
                              "code": "INSUFFICIENT_BALANCE",
                              "message": "Your available balance (balance minus amounts reserved for orders in progress or frozen by us) is not enough for this label. Nothing was bought or charged; top up, or ask us to unfreeze, then resend the same request unchanged.",
                              "carrierCode": null,
                              "carrierMessage": null,
                              "quotedCharge": null
                            },
                            "serviceCode": "e2a7d913-5c40-4b8e-a1f6-0d9c3b7e5a21",
                            "carrier": "fedex",
                            "service": "fedex_ground",
                            "totalCharge": null,
                            "currency": "USD",
                            "trackingNumber": null,
                            "labelReady": false,
                            "labelStatus": "NOT_CREATED",
                            "labelUrl": null,
                            "labelUrlExpiresAt": null,
                            "trackingStatus": null,
                            "trackingUpdatedAt": null,
                            "cancel": null,
                            "createdAt": "2026-10-19T08:00:00Z",
                            "submittedAt": null
                          }
                        ]
                      },
                      "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                    }
                  },
                  "split": {
                    "summary": "All 3 packages have their labels bought: one result with 3 orders in orders[]",
                    "value": {
                      "success": true,
                      "code": "OK",
                      "message": "Processed 1 item(s).",
                      "data": {
                        "summary": {
                          "total": 1,
                          "succeeded": 1,
                          "failed": 0
                        },
                        "results": [
                          {
                            "index": 0,
                            "success": true,
                            "code": "OK",
                            "message": "",
                            "retryable": false,
                            "replayed": false,
                            "customerOrderNo": "WMS-10005",
                            "packageCount": 3,
                            "orders": [
                              {
                                "packageIndex": 1,
                                "success": true,
                                "code": "OK",
                                "message": "",
                                "retryable": false,
                                "replayed": false,
                                "customerOrderNo": "WMS-10005",
                                "orderNo": "ORD-20261104-000201",
                                "status": "CREATED",
                                "statusReason": null,
                                "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                                "carrier": "usps",
                                "service": "usps_ground_advantage",
                                "totalCharge": "14.20",
                                "currency": "USD",
                                "trackingNumber": "9400111899223344556601",
                                "labelReady": true,
                                "labelStatus": "READY",
                                "labelUrl": null,
                                "labelUrlExpiresAt": null,
                                "trackingStatus": "PRE_SHIPMENT",
                                "trackingUpdatedAt": null,
                                "cancel": null,
                                "createdAt": "2026-11-04T08:00:00Z",
                                "submittedAt": "2026-11-04T08:00:04Z",
                                "packageCount": 3
                              },
                              {
                                "packageIndex": 2,
                                "success": true,
                                "code": "OK",
                                "message": "",
                                "retryable": false,
                                "replayed": false,
                                "customerOrderNo": "WMS-10005",
                                "orderNo": "ORD-20261104-000202",
                                "status": "CREATED",
                                "statusReason": null,
                                "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                                "carrier": "usps",
                                "service": "usps_ground_advantage",
                                "totalCharge": "14.20",
                                "currency": "USD",
                                "trackingNumber": "9400111899223344556602",
                                "labelReady": true,
                                "labelStatus": "READY",
                                "labelUrl": null,
                                "labelUrlExpiresAt": null,
                                "trackingStatus": "PRE_SHIPMENT",
                                "trackingUpdatedAt": null,
                                "cancel": null,
                                "createdAt": "2026-11-04T08:00:00Z",
                                "submittedAt": "2026-11-04T08:00:04Z",
                                "packageCount": 3
                              },
                              {
                                "packageIndex": 3,
                                "success": true,
                                "code": "OK",
                                "message": "",
                                "retryable": false,
                                "replayed": false,
                                "customerOrderNo": "WMS-10005",
                                "orderNo": "ORD-20261104-000203",
                                "status": "CREATED",
                                "statusReason": null,
                                "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                                "carrier": "usps",
                                "service": "usps_ground_advantage",
                                "totalCharge": "6.92",
                                "currency": "USD",
                                "trackingNumber": "9400111899223344556603",
                                "labelReady": true,
                                "labelStatus": "READY",
                                "labelUrl": null,
                                "labelUrlExpiresAt": null,
                                "trackingStatus": "PRE_SHIPMENT",
                                "trackingUpdatedAt": null,
                                "cancel": null,
                                "createdAt": "2026-11-04T08:00:00Z",
                                "submittedAt": "2026-11-04T08:00:04Z",
                                "packageCount": 3
                              }
                            ]
                          }
                        ]
                      },
                      "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/orders/info": {
      "post": {
        "operationId": "getOrdersInfo",
        "tags": [
          "orders"
        ],
        "summary": "Batch order info",
        "description": "1..100 items per request, each with one of three: customerOrderNo / orderNo / trackingNumber. Only finds the orders of the customer bound to the key (including orders that customer placed by hand in the dashboard); someone else's order and an order that does not exist get exactly the same reply (ORDER_NOT_FOUND). The carrier is not queried in real time. A customerOrderNo naming a split group counts every order of the group: 100 orders or fewer in all; otherwise the whole request is a 400 BATCH_TOO_LARGE and nothing is read.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrdersInfoRequest"
              },
              "examples": {
                "threeRefs": {
                  "summary": "One of each identifier type",
                  "value": {
                    "orders": [
                      {
                        "customerOrderNo": "WMS-10001"
                      },
                      {
                        "orderNo": "ORD-20261019-000124"
                      },
                      {
                        "trackingNumber": "1Z999AA10123456784"
                      }
                    ]
                  }
                },
                "splitGroup": {
                  "summary": "Look up an order with several packages by its customer order number",
                  "value": {
                    "orders": [
                      {
                        "customerOrderNo": "WMS-10005"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Processed. Check data.results[i].success item by item.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrdersInfoResponse"
                },
                "examples": {
                  "mixed": {
                    "summary": "Two found, one not found",
                    "value": {
                      "success": true,
                      "code": "OK",
                      "message": "Processed 3 item(s).",
                      "data": {
                        "summary": {
                          "total": 3,
                          "succeeded": 2,
                          "failed": 1
                        },
                        "results": [
                          {
                            "index": 0,
                            "success": true,
                            "code": "OK",
                            "message": "",
                            "retryable": false,
                            "customerOrderNo": "WMS-10001",
                            "orderNo": "ORD-20261019-000123",
                            "status": "CREATED",
                            "statusReason": null,
                            "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                            "carrier": "usps",
                            "service": "usps_ground_advantage",
                            "totalCharge": "6.92",
                            "currency": "USD",
                            "trackingNumber": "9400111899223344556677",
                            "labelReady": true,
                            "labelStatus": "READY",
                            "labelUrl": "https://example.com/labels/ORD-20261019-000123?signature=abc123",
                            "labelUrlExpiresAt": "2026-10-19T09:00:00Z",
                            "trackingStatus": "PRE_SHIPMENT",
                            "trackingUpdatedAt": null,
                            "cancel": null,
                            "createdAt": "2026-10-19T08:00:00Z",
                            "submittedAt": "2026-10-19T08:00:03Z"
                          },
                          {
                            "index": 1,
                            "success": true,
                            "code": "OK",
                            "message": "",
                            "retryable": false,
                            "customerOrderNo": "WMS-10002",
                            "orderNo": "ORD-20261019-000124",
                            "status": "PROCESSING",
                            "statusReason": {
                              "code": "ORDER_PROCESSING",
                              "message": "We are buying this label. Check again shortly; do not resend with a new customerOrderNo.",
                              "carrierCode": null,
                              "carrierMessage": null,
                              "quotedCharge": null
                            },
                            "serviceCode": "e2a7d913-5c40-4b8e-a1f6-0d9c3b7e5a21",
                            "carrier": "fedex",
                            "service": "fedex_ground",
                            "totalCharge": null,
                            "currency": "USD",
                            "trackingNumber": null,
                            "labelReady": false,
                            "labelStatus": "NOT_CREATED",
                            "labelUrl": null,
                            "labelUrlExpiresAt": null,
                            "trackingStatus": null,
                            "trackingUpdatedAt": null,
                            "cancel": null,
                            "createdAt": "2026-10-19T08:00:00Z",
                            "submittedAt": null
                          },
                          {
                            "index": 2,
                            "success": false,
                            "code": "ORDER_NOT_FOUND",
                            "message": "No order of yours matches this identifier.",
                            "retryable": false,
                            "trackingNumber": "1Z999AA10123456784"
                          }
                        ]
                      },
                      "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                    }
                  },
                  "ambiguous": {
                    "summary": "The tracking number matches more than one order",
                    "value": {
                      "success": true,
                      "code": "OK",
                      "message": "Processed 1 item(s).",
                      "data": {
                        "summary": {
                          "total": 1,
                          "succeeded": 0,
                          "failed": 1
                        },
                        "results": [
                          {
                            "index": 0,
                            "success": false,
                            "code": "AMBIGUOUS_TRACKING_NUMBER",
                            "message": "This tracking number matches more than one of your orders. Use customerOrderNo or orderNo instead (the candidates are listed in orderNos).",
                            "retryable": false,
                            "trackingNumber": "9400111899223344556677",
                            "orderNos": [
                              "ORD-20261019-000123",
                              "ORD-20261019-000188"
                            ]
                          }
                        ]
                      },
                      "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                    }
                  },
                  "split": {
                    "summary": "One result, with one order per package in orders[]",
                    "value": {
                      "success": true,
                      "code": "OK",
                      "message": "Processed 1 item(s).",
                      "data": {
                        "summary": {
                          "total": 1,
                          "succeeded": 1,
                          "failed": 0
                        },
                        "results": [
                          {
                            "index": 0,
                            "success": true,
                            "code": "OK",
                            "message": "",
                            "retryable": false,
                            "customerOrderNo": "WMS-10005",
                            "packageCount": 3,
                            "orders": [
                              {
                                "packageIndex": 1,
                                "success": true,
                                "code": "OK",
                                "message": "",
                                "retryable": false,
                                "customerOrderNo": "WMS-10005",
                                "orderNo": "ORD-20261104-000201",
                                "status": "CREATED",
                                "statusReason": null,
                                "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                                "carrier": "usps",
                                "service": "usps_ground_advantage",
                                "totalCharge": "14.20",
                                "currency": "USD",
                                "trackingNumber": "9400111899223344556601",
                                "labelReady": true,
                                "labelStatus": "READY",
                                "labelUrl": null,
                                "labelUrlExpiresAt": null,
                                "trackingStatus": "PRE_SHIPMENT",
                                "trackingUpdatedAt": null,
                                "cancel": null,
                                "createdAt": "2026-11-04T08:00:00Z",
                                "submittedAt": "2026-11-04T08:00:04Z",
                                "packageCount": 3
                              },
                              {
                                "packageIndex": 2,
                                "success": true,
                                "code": "OK",
                                "message": "",
                                "retryable": false,
                                "customerOrderNo": "WMS-10005",
                                "orderNo": "ORD-20261104-000202",
                                "status": "CREATED",
                                "statusReason": null,
                                "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                                "carrier": "usps",
                                "service": "usps_ground_advantage",
                                "totalCharge": "14.20",
                                "currency": "USD",
                                "trackingNumber": "9400111899223344556602",
                                "labelReady": true,
                                "labelStatus": "READY",
                                "labelUrl": null,
                                "labelUrlExpiresAt": null,
                                "trackingStatus": "PRE_SHIPMENT",
                                "trackingUpdatedAt": null,
                                "cancel": null,
                                "createdAt": "2026-11-04T08:00:00Z",
                                "submittedAt": "2026-11-04T08:00:04Z",
                                "packageCount": 3
                              },
                              {
                                "packageIndex": 3,
                                "success": true,
                                "code": "OK",
                                "message": "",
                                "retryable": false,
                                "customerOrderNo": "WMS-10005",
                                "orderNo": "ORD-20261104-000203",
                                "status": "CREATED",
                                "statusReason": null,
                                "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                                "carrier": "usps",
                                "service": "usps_ground_advantage",
                                "totalCharge": "6.92",
                                "currency": "USD",
                                "trackingNumber": "9400111899223344556603",
                                "labelReady": true,
                                "labelStatus": "READY",
                                "labelUrl": null,
                                "labelUrlExpiresAt": null,
                                "trackingStatus": "PRE_SHIPMENT",
                                "trackingUpdatedAt": null,
                                "cancel": null,
                                "createdAt": "2026-11-04T08:00:00Z",
                                "submittedAt": "2026-11-04T08:00:04Z",
                                "packageCount": 3
                              }
                            ]
                          }
                        ]
                      },
                      "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/orders/labels": {
      "post": {
        "operationId": "getLabels",
        "tags": [
          "orders"
        ],
        "summary": "Batch labels",
        "description": "format: url (default, limit 500, one link of ours per order, valid for 1 hour) / base64 (limit 20, at most about 5 MB of label content in total per reply) / merged (limit 100, combined into one PDF). Orders being cancelled / cancelled no longer get labels. A customerOrderNo naming a split group counts every order of the group, and the order limit equals the item limit (url 500 · base64 20 · merged 100); otherwise the whole request is a 400 BATCH_TOO_LARGE and no label is read.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LabelsRequest"
              },
              "examples": {
                "url": {
                  "summary": "Get links",
                  "value": {
                    "format": "url",
                    "orders": [
                      {
                        "customerOrderNo": "WMS-10001"
                      },
                      {
                        "customerOrderNo": "WMS-10009"
                      }
                    ]
                  }
                },
                "merged": {
                  "summary": "Merge into one PDF",
                  "value": {
                    "format": "merged",
                    "orders": [
                      {
                        "customerOrderNo": "WMS-10001"
                      },
                      {
                        "orderNo": "ORD-20261019-000140"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Processed. Check data.results[i].success item by item.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LabelsResponse"
                },
                "examples": {
                  "url": {
                    "summary": "One label available, one order cancelled",
                    "value": {
                      "success": true,
                      "code": "OK",
                      "message": "Processed 2 item(s).",
                      "data": {
                        "summary": {
                          "total": 2,
                          "succeeded": 1,
                          "failed": 1
                        },
                        "results": [
                          {
                            "index": 0,
                            "success": true,
                            "code": "OK",
                            "message": "",
                            "retryable": false,
                            "customerOrderNo": "WMS-10001",
                            "orderNo": "ORD-20261019-000123",
                            "trackingNumber": "9400111899223344556677",
                            "fileType": "PDF",
                            "labelUrl": "https://example.com/labels/ORD-20261019-000123?signature=abc123",
                            "expiresAt": "2026-10-19T09:00:00Z"
                          },
                          {
                            "index": 1,
                            "success": false,
                            "code": "LABEL_BLOCKED_CANCELLED",
                            "message": "This order is being cancelled or is cancelled, so its label is no longer provided.",
                            "retryable": false,
                            "customerOrderNo": "WMS-10009",
                            "orderNo": "ORD-20261019-000131",
                            "trackingNumber": "9400111899223344550000"
                          }
                        ]
                      },
                      "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                    }
                  },
                  "merged": {
                    "summary": "Merged: one merged in, one format not supported",
                    "value": {
                      "success": true,
                      "code": "OK",
                      "message": "Processed 2 item(s).",
                      "data": {
                        "summary": {
                          "total": 2,
                          "succeeded": 1,
                          "failed": 1
                        },
                        "results": [
                          {
                            "index": 0,
                            "success": true,
                            "code": "OK",
                            "message": "",
                            "retryable": false,
                            "customerOrderNo": "WMS-10001",
                            "orderNo": "ORD-20261019-000123",
                            "trackingNumber": "9400111899223344556677",
                            "merged": true
                          },
                          {
                            "index": 1,
                            "success": false,
                            "code": "LABEL_FORMAT_UNSUPPORTED",
                            "message": "This label's format cannot be merged into a PDF. Fetch it on its own with format \"url\".",
                            "retryable": false,
                            "customerOrderNo": null,
                            "orderNo": "ORD-20261019-000140",
                            "trackingNumber": "1Z999AA10123456799"
                          }
                        ],
                        "merged": {
                          "labelUrl": "https://example.com/labels/merged/7d3f?signature=def456",
                          "expiresAt": "2026-10-19T09:00:00Z",
                          "pageCount": 1
                        }
                      },
                      "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/orders/cancel": {
      "post": {
        "operationId": "cancelOrders",
        "tags": [
          "orders"
        ],
        "summary": "Batch cancel (two-step approval)",
        "description": "1..500 items per request. What you submit is a \"cancellation request\": after we cancel with the carrier it goes to review, and the refund is issued only once it is approved. The API never says \"cancelled successfully\": the best immediate result is cancel.status = PENDING_REVIEW. With 20 or fewer items it waits up to 15 seconds to bring back the carrier's result. A customerOrderNo naming a split group counts every order of the group: 500 orders or fewer in all; otherwise the whole request is a 400 BATCH_TOO_LARGE and no cancellation request is submitted.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CancelRequest"
              },
              "examples": {
                "two": {
                  "summary": "Two items",
                  "value": {
                    "orders": [
                      {
                        "customerOrderNo": "WMS-10001",
                        "reason": "Customer changed mind"
                      },
                      {
                        "customerOrderNo": "WMS-10002"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Processed. Check data.results[i].success item by item.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancelResponse"
                },
                "examples": {
                  "mixed": {
                    "summary": "One goes to review, one is still being processed",
                    "value": {
                      "success": true,
                      "code": "OK",
                      "message": "Processed 2 item(s).",
                      "data": {
                        "summary": {
                          "total": 2,
                          "succeeded": 1,
                          "failed": 1
                        },
                        "results": [
                          {
                            "index": 0,
                            "success": true,
                            "code": "OK",
                            "message": "",
                            "retryable": false,
                            "customerOrderNo": "WMS-10001",
                            "orderNo": "ORD-20261019-000123",
                            "trackingNumber": "9400111899223344556677",
                            "status": "CANCEL_PENDING",
                            "cancel": {
                              "status": "PENDING_REVIEW",
                              "code": null,
                              "message": "The carrier has accepted the cancellation and the refund is waiting for our review. No refund has been issued yet.",
                              "carrierMessage": null,
                              "requestedAt": "2026-10-19T10:00:00Z",
                              "reviewedAt": null,
                              "refundAmount": null,
                              "currency": "USD",
                              "rejectReason": null
                            }
                          },
                          {
                            "index": 1,
                            "success": false,
                            "code": "ORDER_PROCESSING",
                            "message": "This order is still being processed. Retry the cancellation shortly.",
                            "retryable": true,
                            "customerOrderNo": "WMS-10002",
                            "orderNo": "ORD-20261019-000124",
                            "trackingNumber": null,
                            "status": "PROCESSING",
                            "cancel": null
                          }
                        ]
                      },
                      "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                    }
                  },
                  "carrierRejected": {
                    "summary": "The carrier refuses to cancel",
                    "value": {
                      "success": true,
                      "code": "OK",
                      "message": "Processed 1 item(s).",
                      "data": {
                        "summary": {
                          "total": 1,
                          "succeeded": 0,
                          "failed": 1
                        },
                        "results": [
                          {
                            "index": 0,
                            "success": false,
                            "code": "CARRIER_CANCEL_REJECTED",
                            "message": "The carrier refused to cancel this label (often because the parcel was already picked up). The order is unchanged and nothing was refunded. Contact us with the requestId if you need help.",
                            "retryable": false,
                            "customerOrderNo": "WMS-10001",
                            "orderNo": "ORD-20261019-000123",
                            "trackingNumber": "9400111899223344556677",
                            "status": "CREATED",
                            "cancel": {
                              "status": "FAILED",
                              "code": "CARRIER_CANCEL_REJECTED",
                              "message": "The carrier refused to cancel this label (often because the parcel was already picked up). The order is unchanged and nothing was refunded. Contact us with the requestId if you need help.",
                              "carrierMessage": null,
                              "requestedAt": "2026-10-19T10:00:00Z",
                              "reviewedAt": null,
                              "refundAmount": null,
                              "currency": "USD",
                              "rejectReason": null
                            }
                          }
                        ]
                      },
                      "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/balance": {
      "post": {
        "operationId": "getBalance",
        "tags": [
          "account"
        ],
        "summary": "Check your balance",
        "description": "Read-only. Returns the balance, reserved amount, frozen amount, available amount and credit of the customer bound to the key. available is the very figure the create-orders endpoint checks. We read the latest data. A test key returns the real balance (read-only; test orders never change it). A read failure is a 503, never a zero balance.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BalanceRequest"
              },
              "examples": {
                "empty": {
                  "summary": "Empty object",
                  "value": {}
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Your balance.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BalanceResponse"
                },
                "examples": {
                  "noCredit": {
                    "summary": "No credit",
                    "value": {
                      "success": true,
                      "code": "OK",
                      "message": "",
                      "data": {
                        "currency": "USD",
                        "balance": "120.50",
                        "reserved": "20.00",
                        "frozen": "30.00",
                        "available": "70.50",
                        "credit": null
                      },
                      "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                    }
                  },
                  "creditInUse": {
                    "summary": "A credit in use",
                    "value": {
                      "success": true,
                      "code": "OK",
                      "message": "",
                      "data": {
                        "currency": "USD",
                        "balance": "-40.00",
                        "reserved": "5.00",
                        "frozen": "0.00",
                        "available": "55.00",
                        "credit": {
                          "limit": "100.00",
                          "used": "40.00",
                          "remaining": "60.00"
                        }
                      },
                      "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/orders/list": {
      "post": {
        "operationId": "listOrders",
        "tags": [
          "orders"
        ],
        "summary": "List orders by creation time",
        "description": "Lists every order of the customer bound to the key by creation time (createdFrom ≤ createdAt < createdTo, whole seconds), oldest first, page by page (orders placed by hand in the dashboard, uploaded in bulk, created from a connected store or through this API; deleted orders are not listed). Each item is all order view fields, the same as the order info endpoint. Time range ≤ 31 days, 1–100 per page (default 50). With a status filter we look at no more than 500 orders per request, so a page may hold fewer than limit, even none: keep paging while nextCursor is not null. A cursor works only for the same customer account, the same kind of key and the same createdFrom / createdTo / status; otherwise 400 INVALID_CURSOR. A test key lists test orders only. A read failure is a 503, never an empty list.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ListOrdersRequest"
              },
              "examples": {
                "firstPage": {
                  "summary": "First page",
                  "value": {
                    "createdFrom": "2026-11-15T00:00:00Z",
                    "createdTo": "2026-11-16T00:00:00Z",
                    "status": [
                      "CREATED",
                      "CANCELLED"
                    ],
                    "limit": 2
                  }
                },
                "nextPage": {
                  "summary": "Next page (the same query + cursor)",
                  "value": {
                    "createdFrom": "2026-11-15T00:00:00Z",
                    "createdTo": "2026-11-16T00:00:00Z",
                    "status": [
                      "CREATED",
                      "CANCELLED"
                    ],
                    "limit": 2,
                    "cursor": "eyJ2IjoxLCJiIjoiN2ZrUTJ4"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One page of orders.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListOrdersResponse"
                },
                "examples": {
                  "page": {
                    "summary": "Two orders, with a next page",
                    "value": {
                      "success": true,
                      "code": "OK",
                      "message": "Listed 2 order(s).",
                      "data": {
                        "orders": [
                          {
                            "customerOrderNo": "WMS-10001",
                            "orderNo": "ORD-20261115-000123",
                            "status": "CREATED",
                            "statusReason": null,
                            "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                            "carrier": "usps",
                            "service": "usps_ground_advantage",
                            "totalCharge": "6.92",
                            "currency": "USD",
                            "trackingNumber": "9400111899223344556677",
                            "labelReady": true,
                            "labelStatus": "READY",
                            "labelUrl": null,
                            "labelUrlExpiresAt": null,
                            "trackingStatus": "PRE_SHIPMENT",
                            "trackingUpdatedAt": null,
                            "cancel": null,
                            "createdAt": "2026-11-15T08:00:00Z",
                            "submittedAt": "2026-11-15T08:00:04Z"
                          },
                          {
                            "customerOrderNo": null,
                            "orderNo": "ORD-20261115-000188",
                            "status": "CANCELLED",
                            "statusReason": null,
                            "serviceCode": null,
                            "carrier": "usps",
                            "service": "usps_ground_advantage",
                            "totalCharge": "8.15",
                            "currency": "USD",
                            "trackingNumber": "9400111899223344556688",
                            "labelReady": false,
                            "labelStatus": "BLOCKED_CANCELLED",
                            "labelUrl": null,
                            "labelUrlExpiresAt": null,
                            "trackingStatus": "PRE_SHIPMENT",
                            "trackingUpdatedAt": null,
                            "cancel": {
                              "status": "APPROVED",
                              "code": null,
                              "message": "",
                              "carrierMessage": null,
                              "requestedAt": "2026-11-15T10:00:00Z",
                              "reviewedAt": "2026-11-15T12:00:00Z",
                              "refundAmount": "8.15",
                              "currency": "USD",
                              "rejectReason": null
                            },
                            "createdAt": "2026-11-15T09:30:12Z",
                            "submittedAt": "2026-11-15T09:30:04Z"
                          }
                        ],
                        "nextCursor": "eyJ2IjoxLCJiIjoiN2ZrUTJ4",
                        "query": {
                          "createdFrom": "2026-11-15T00:00:00Z",
                          "createdTo": "2026-11-16T00:00:00Z",
                          "status": [
                            "CANCELLED",
                            "CREATED"
                          ],
                          "limit": 2
                        }
                      },
                      "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "zsk_live_<64 hex characters> / zsk_test_<64 hex characters>",
        "description": "Authorization: Bearer <key>. Live keys are zsk_live_…, test keys are zsk_test_…."
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Malformed request (INVALID_REQUEST / BATCH_TOO_LARGE / INVALID_CURSOR / IMPERSONATION_UNSUPPORTED).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "invalidRequest": {
                "value": {
                  "success": false,
                  "code": "INVALID_REQUEST",
                  "message": "The request body is invalid. See data.errors for the fields to fix.",
                  "data": {
                    "errors": [
                      {
                        "field": "unitSystem",
                        "code": "REQUIRED",
                        "message": "unitSystem is required: \"imperial\" (lb / in) or \"metric\" (kg / cm)."
                      }
                    ]
                  },
                  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                }
              },
              "batchTooLarge": {
                "value": {
                  "success": false,
                  "code": "BATCH_TOO_LARGE",
                  "message": "At most 100 items per request.",
                  "data": {
                    "maxItems": 100
                  },
                  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                }
              },
              "invalidCursor": {
                "value": {
                  "success": false,
                  "code": "INVALID_CURSOR",
                  "message": "This cursor is not valid for this request. Send nextCursor from the previous reply unchanged, with the same createdFrom, createdTo and status; to start over, omit cursor.",
                  "data": null,
                  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Invalid key (INVALID_API_KEY / API_KEY_REVOKED).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "invalidKey": {
                "value": {
                  "success": false,
                  "code": "INVALID_API_KEY",
                  "message": "A valid API key is required. Send it as \"Authorization: Bearer <key>\".",
                  "data": null,
                  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The account is not enabled (ACCOUNT_NOT_ENABLED), or the customer account bound to the key is deactivated (ACCOUNT_DEACTIVATED).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "notEnabled": {
                "value": {
                  "success": false,
                  "code": "ACCOUNT_NOT_ENABLED",
                  "message": "The account bound to this API key is not enabled for this operation. Please contact us.",
                  "data": null,
                  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                }
              },
              "deactivated": {
                "value": {
                  "success": false,
                  "code": "ACCOUNT_DEACTIVATED",
                  "message": "The customer account bound to this API key has been deactivated. A new key will not help; please contact us to reactivate the account.",
                  "data": null,
                  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                }
              }
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Rate limited (RATE_LIMITED / QUOTA_EXCEEDED). Note: the platform-wide per-second protective rate limit is returned as 429 by the gateway itself, and that reply is not in the envelope format.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "rateLimited": {
                "value": {
                  "success": false,
                  "code": "RATE_LIMITED",
                  "message": "Too many requests for this API key in the current minute. Retry after data.retryAfter seconds.",
                  "data": {
                    "retryAfter": 17
                  },
                  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                }
              }
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "A temporary failure on our side (SERVICE_UNAVAILABLE / API_KEY_LOOKUP_UNAVAILABLE), as 500 or 503. Resending unchanged is safe. A gateway timeout 504 is not in the envelope format.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "serviceUnavailable": {
                "value": {
                  "success": false,
                  "code": "SERVICE_UNAVAILABLE",
                  "message": "A temporary failure on our side. Resending the same request (same customerOrderNo) is safe; if it keeps happening, contact us with the requestId.",
                  "data": null,
                  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "RequestCode": {
        "description": "Request-level code (the code of the whole reply). x-http-status is the matching HTTP status code; x-retryable tells whether resending unchanged could succeed.",
        "type": "string",
        "enum": [
          "OK",
          "INVALID_API_KEY",
          "API_KEY_REVOKED",
          "API_KEY_LOOKUP_UNAVAILABLE",
          "IMPERSONATION_UNSUPPORTED",
          "RATE_LIMITED",
          "QUOTA_EXCEEDED",
          "ACCOUNT_NOT_ENABLED",
          "ACCOUNT_DEACTIVATED",
          "INVALID_REQUEST",
          "BATCH_TOO_LARGE",
          "INVALID_CURSOR",
          "NOT_FOUND",
          "SERVICE_UNAVAILABLE"
        ],
        "x-retryable": {
          "OK": false,
          "INVALID_API_KEY": false,
          "API_KEY_REVOKED": false,
          "API_KEY_LOOKUP_UNAVAILABLE": true,
          "IMPERSONATION_UNSUPPORTED": false,
          "RATE_LIMITED": true,
          "QUOTA_EXCEEDED": true,
          "ACCOUNT_NOT_ENABLED": false,
          "ACCOUNT_DEACTIVATED": false,
          "INVALID_REQUEST": false,
          "BATCH_TOO_LARGE": false,
          "INVALID_CURSOR": false,
          "NOT_FOUND": false,
          "SERVICE_UNAVAILABLE": true
        },
        "x-http-status": {
          "OK": 200,
          "INVALID_API_KEY": 401,
          "API_KEY_REVOKED": 401,
          "API_KEY_LOOKUP_UNAVAILABLE": 503,
          "IMPERSONATION_UNSUPPORTED": 400,
          "RATE_LIMITED": 429,
          "QUOTA_EXCEEDED": 429,
          "ACCOUNT_NOT_ENABLED": 403,
          "ACCOUNT_DEACTIVATED": 403,
          "INVALID_REQUEST": 400,
          "BATCH_TOO_LARGE": 400,
          "INVALID_CURSOR": 400,
          "NOT_FOUND": 404,
          "SERVICE_UNAVAILABLE": 503
        },
        "x-enum-descriptions": {
          "OK": "The request was processed. For batch endpoints, check results[i].success item by item.",
          "INVALID_API_KEY": "The key is missing, does not exist or is malformed.",
          "API_KEY_REVOKED": "The key has been revoked or has expired; generate a new key in the OminiShip dashboard under Settings → API Keys.",
          "API_KEY_LOOKUP_UNAVAILABLE": "We cannot verify keys right now (not a problem with your key); retry unchanged shortly, and do not switch keys.",
          "IMPERSONATION_UNSUPPORTED": "The request carries an unsupported identity-switching request header (X-Impersonate-Session); remove it and resend.",
          "RATE_LIMITED": "Too many requests within this minute; retry after data.retryAfter seconds.",
          "QUOTA_EXCEEDED": "Today's (UTC) requests are used up; retry after data.retryAfter seconds (resets at UTC midnight).",
          "ACCOUNT_NOT_ENABLED": "The account bound to the key is not enabled for this feature; please contact us.",
          "ACCOUNT_DEACTIVATED": "The customer account bound to the key has been deactivated (live and test keys alike). A new key will not help; please contact us to reactivate the account, and once it is reactivated the existing keys work again.",
          "INVALID_REQUEST": "The request body is malformed; fix it according to data.errors and resend.",
          "BATCH_TOO_LARGE": "Too many items (above data.maxItems) or packages / orders (above data.maxPackages; this request counted data.packages) in one request; split the batch.",
          "INVALID_CURSOR": "The list-orders cursor is not valid for this request (not issued for this account, this kind of key or this createdFrom / createdTo / status, or damaged). Send the previous page's nextCursor unchanged; to start over, omit cursor.",
          "NOT_FOUND": "No such endpoint path; check the method (POST) and the path.",
          "SERVICE_UNAVAILABLE": "A temporary failure on our side. Resending the same request unchanged (the same customer order numbers) is safe; if it keeps happening, contact us with the requestId."
        }
      },
      "ItemCode": {
        "description": "Per-item code (results[i].code, statusReason.code, cancel.code, unavailable[i].code). x-retryable tells whether resending unchanged could succeed; x-item-success is the results[i].success that goes with the code.",
        "type": "string",
        "enum": [
          "OK",
          "INVALID_IDENTIFIER",
          "ORDER_NOT_FOUND",
          "AMBIGUOUS_TRACKING_NUMBER",
          "DUPLICATE_IN_BATCH",
          "INVALID_ORDER",
          "INVALID_SHIPMENT",
          "SERVICE_NOT_AVAILABLE",
          "SERVICE_CODE_GROUP_NOT_FOUND",
          "SERVICE_CODE_GROUP_EMPTY",
          "RECEIVER_PHONE_INVALID",
          "NO_RATE",
          "CARRIER_RATE_ERROR",
          "RATE_TIMEOUT",
          "PRICE_ABOVE_MAX",
          "INSUFFICIENT_BALANCE",
          "CARRIER_REJECTED",
          "SUBMIT_PAUSED",
          "PRICE_CHANGED",
          "SUBMIT_FAILED",
          "CUSTOMER_ORDER_NO_CONFLICT",
          "CUSTOMER_ORDER_NO_USED",
          "ACCEPT_TIMEOUT",
          "LABEL_NOT_READY",
          "LABEL_PREPARING",
          "LABEL_BLOCKED_CANCELLED",
          "LABEL_UNAVAILABLE",
          "LABEL_FORMAT_UNSUPPORTED",
          "RESPONSE_TOO_LARGE",
          "ORDER_NOT_SHIPPED",
          "ORDER_PROCESSING",
          "CANCEL_ALREADY_REQUESTED",
          "ALREADY_CANCELLED",
          "CARRIER_CANCEL_REJECTED",
          "CARRIER_ORDER_NOT_FOUND",
          "CARRIER_CANCEL_UNCONFIRMED",
          "CANCEL_TEMPORARILY_UNAVAILABLE"
        ],
        "x-retryable": {
          "OK": false,
          "INVALID_IDENTIFIER": false,
          "ORDER_NOT_FOUND": false,
          "AMBIGUOUS_TRACKING_NUMBER": false,
          "DUPLICATE_IN_BATCH": false,
          "INVALID_ORDER": false,
          "INVALID_SHIPMENT": false,
          "SERVICE_NOT_AVAILABLE": false,
          "SERVICE_CODE_GROUP_NOT_FOUND": false,
          "SERVICE_CODE_GROUP_EMPTY": false,
          "RECEIVER_PHONE_INVALID": false,
          "NO_RATE": false,
          "CARRIER_RATE_ERROR": true,
          "RATE_TIMEOUT": true,
          "PRICE_ABOVE_MAX": false,
          "INSUFFICIENT_BALANCE": true,
          "CARRIER_REJECTED": false,
          "SUBMIT_PAUSED": true,
          "PRICE_CHANGED": true,
          "SUBMIT_FAILED": true,
          "CUSTOMER_ORDER_NO_CONFLICT": false,
          "CUSTOMER_ORDER_NO_USED": false,
          "ACCEPT_TIMEOUT": true,
          "LABEL_NOT_READY": true,
          "LABEL_PREPARING": true,
          "LABEL_BLOCKED_CANCELLED": false,
          "LABEL_UNAVAILABLE": true,
          "LABEL_FORMAT_UNSUPPORTED": false,
          "RESPONSE_TOO_LARGE": true,
          "ORDER_NOT_SHIPPED": false,
          "ORDER_PROCESSING": true,
          "CANCEL_ALREADY_REQUESTED": false,
          "ALREADY_CANCELLED": false,
          "CARRIER_CANCEL_REJECTED": false,
          "CARRIER_ORDER_NOT_FOUND": false,
          "CARRIER_CANCEL_UNCONFIRMED": false,
          "CANCEL_TEMPORARILY_UNAVAILABLE": true
        },
        "x-item-success": {
          "OK": true,
          "INVALID_IDENTIFIER": false,
          "ORDER_NOT_FOUND": false,
          "AMBIGUOUS_TRACKING_NUMBER": false,
          "DUPLICATE_IN_BATCH": false,
          "INVALID_ORDER": false,
          "INVALID_SHIPMENT": false,
          "SERVICE_NOT_AVAILABLE": false,
          "SERVICE_CODE_GROUP_NOT_FOUND": false,
          "SERVICE_CODE_GROUP_EMPTY": false,
          "RECEIVER_PHONE_INVALID": false,
          "NO_RATE": false,
          "CARRIER_RATE_ERROR": false,
          "RATE_TIMEOUT": false,
          "PRICE_ABOVE_MAX": false,
          "INSUFFICIENT_BALANCE": false,
          "CARRIER_REJECTED": false,
          "SUBMIT_PAUSED": false,
          "PRICE_CHANGED": false,
          "SUBMIT_FAILED": false,
          "CUSTOMER_ORDER_NO_CONFLICT": false,
          "CUSTOMER_ORDER_NO_USED": false,
          "ACCEPT_TIMEOUT": false,
          "LABEL_NOT_READY": false,
          "LABEL_PREPARING": false,
          "LABEL_BLOCKED_CANCELLED": false,
          "LABEL_UNAVAILABLE": false,
          "LABEL_FORMAT_UNSUPPORTED": false,
          "RESPONSE_TOO_LARGE": false,
          "ORDER_NOT_SHIPPED": false,
          "ORDER_PROCESSING": false,
          "CANCEL_ALREADY_REQUESTED": true,
          "ALREADY_CANCELLED": true,
          "CARRIER_CANCEL_REJECTED": false,
          "CARRIER_ORDER_NOT_FOUND": false,
          "CARRIER_CANCEL_UNCONFIRMED": false,
          "CANCEL_TEMPORARILY_UNAVAILABLE": false
        },
        "x-enum-descriptions": {
          "OK": "Success / accepted.",
          "INVALID_IDENTIFIER": "Each item must give exactly one of customerOrderNo, orderNo and trackingNumber, in the right format.",
          "ORDER_NOT_FOUND": "No such order (including orders that are not yours).",
          "AMBIGUOUS_TRACKING_NUMBER": "This tracking number matches more than one of your orders; use the customer order number or the OminiShip order number instead (the candidates are in that item's orderNos).",
          "DUPLICATE_IN_BATCH": "Repeats an earlier item of the same request; skipped.",
          "INVALID_ORDER": "An order field is invalid; see that item's errors.",
          "INVALID_SHIPMENT": "A field of the rate item is invalid; see that item's errors.",
          "SERVICE_NOT_AVAILABLE": "The service code is not yours, is disabled, or the service is temporarily unavailable (when the cause is on our side, the message says to contact us).",
          "SERVICE_CODE_GROUP_NOT_FOUND": "No service code group with this exact name exists on your account. Group names are case-sensitive (also the code when the group was deleted before the purchase).",
          "SERVICE_CODE_GROUP_EMPTY": "There are no usable services in this service code group. Contact us, or use serviceCode instead.",
          "RECEIVER_PHONE_INVALID": "The shipTo.phone of a US address (shipTo.country empty / US / USA) is filled in but is not exactly 10 digits (no +1, extension, spaces, dashes or parentheses); see the item's errors. Nothing was rated, created or charged; fix it and send it again (create orders may keep the same customerOrderNo, unless it already holds a draft or a failed order: then use a new one).",
          "NO_RATE": "The carrier gave no rate for this package (the carrier's own words are in carrierMessage).",
          "CARRIER_RATE_ERROR": "The carrier's rating service returned an error; retry later.",
          "RATE_TIMEOUT": "Rating this service did not finish in time for this request; just retry.",
          "PRICE_ABOVE_MAX": "The rate is above maxCharge; nothing was bought and nothing was charged (the rate at that time is in statusReason.quotedCharge).",
          "INSUFFICIENT_BALANCE": "Insufficient balance; nothing was bought and nothing was charged. Top up, then resend the same number unchanged.",
          "CARRIER_REJECTED": "The carrier rejected the shipment (see carrierCode / carrierMessage); nothing was charged. Change the content and resend with a new customer order number.",
          "SUBMIT_PAUSED": "We have paused label purchases (maintenance); nothing was charged. Retry later.",
          "PRICE_CHANGED": "The price changed (went up) between the rate and the purchase; nothing was bought and nothing was charged. Resending the same number unchanged tries again at the current price.",
          "SUBMIT_FAILED": "The label could not be bought for a reason on our side, and we are certain that nothing was charged. Resending the same number unchanged is safe; if it keeps failing, contact us with the requestId.",
          "CUSTOMER_ORDER_NO_CONFLICT": "This customer order number already has an order with different content; use a new customer order number.",
          "CUSTOMER_ORDER_NO_USED": "The order with this customer order number was deleted in the dashboard. Customer order numbers cannot be reused; use a new one.",
          "ACCEPT_TIMEOUT": "This item could not be accepted in time for this request; resending unchanged is safe.",
          "LABEL_NOT_READY": "The label is not ready yet (some services issue labels a little later); retry shortly.",
          "LABEL_PREPARING": "We are preparing the label file; retry shortly.",
          "LABEL_BLOCKED_CANCELLED": "The order is being cancelled or is cancelled; its label is no longer provided.",
          "LABEL_UNAVAILABLE": "The carrier's label file cannot be fetched right now; retry later.",
          "LABEL_FORMAT_UNSUPPORTED": "This label format cannot be merged into a PDF; fetch it on its own with format \"url\".",
          "RESPONSE_TOO_LARGE": "This reply is already full; request the remaining labels in a separate call.",
          "ORDER_NOT_SHIPPED": "No label was bought for the order and nothing was charged (a draft or a failed purchase), so there is nothing to cancel and no label.",
          "ORDER_PROCESSING": "The order is still processing; try again later.",
          "CANCEL_ALREADY_REQUESTED": "A cancellation request was already submitted and is waiting for our review (a successful item; not refunded yet).",
          "ALREADY_CANCELLED": "Already cancelled and refunded (a successful item).",
          "CARRIER_CANCEL_REJECTED": "The carrier refuses to cancel (usually: already picked up); the order is unchanged and nothing was refunded.",
          "CARRIER_ORDER_NOT_FOUND": "The carrier cannot find this label, so we need to check it by hand; do not submit it again, and please contact us with the requestId.",
          "CARRIER_CANCEL_UNCONFIRMED": "The carrier's answer cannot confirm the cancellation, so we need to check it by hand; do not submit it again, and please contact us with the requestId.",
          "CANCEL_TEMPORARILY_UNAVAILABLE": "The cancellation request could not be sent this time; nothing changed. Retry later."
        }
      },
      "FieldErrorCode": {
        "type": "string",
        "enum": [
          "REQUIRED",
          "INVALID_TYPE",
          "INVALID_VALUE",
          "TOO_LONG",
          "OUT_OF_RANGE"
        ],
        "description": "REQUIRED missing · INVALID_TYPE wrong type · INVALID_VALUE wrong value · TOO_LONG too long · OUT_OF_RANGE out of range."
      },
      "FieldError": {
        "type": "object",
        "required": [
          "field",
          "code",
          "message"
        ],
        "properties": {
          "field": {
            "type": "string",
            "description": "Full JSON path, such as orders[1].shipTo.postalCode.",
            "example": "orders[1].shipTo.postalCode"
          },
          "code": {
            "$ref": "#/components/schemas/FieldErrorCode"
          },
          "message": {
            "type": "string",
            "description": "Our English description; never echoes the value you sent."
          }
        }
      },
      "Envelope": {
        "type": "object",
        "description": "Every reply that passes through our service has this shape (4xx / 5xx included). Read success / code first, then the HTTP status code.",
        "required": [
          "success",
          "code",
          "message",
          "data",
          "requestId"
        ],
        "properties": {
          "success": {
            "type": "boolean"
          },
          "code": {
            "type": "string",
            "description": "OK on success; one of RequestCode on failure."
          },
          "message": {
            "type": "string",
            "description": "An English description; on failure it includes the next step. Never \"Internal server error\"."
          },
          "data": {
            "type": "object",
            "description": "The endpoint's data; on failure it may carry details or be null.",
            "nullable": true
          },
          "requestId": {
            "type": "string",
            "description": "The ID of this request. Include it when you contact us."
          }
        }
      },
      "ErrorData": {
        "type": "object",
        "description": "The data of a failure reply; only the keys that go with the code appear. For 5xx it can only carry retryAfter, or be null.",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FieldError"
            },
            "description": "Field errors for INVALID_REQUEST."
          },
          "maxItems": {
            "type": "integer",
            "description": "For BATCH_TOO_LARGE: the most items this endpoint (this format) allows per request."
          },
          "maxPackages": {
            "type": "integer",
            "description": "BATCH_TOO_LARGE of create / info / labels / cancel: the package (= order) limit per request, equal to maxItems."
          },
          "packages": {
            "type": "integer",
            "nullable": true,
            "description": "BATCH_TOO_LARGE of create / info / labels / cancel: the packages (= orders) this request counted; null when only the item count is over."
          },
          "maxCombinations": {
            "type": "integer",
            "description": "Only for BATCH_TOO_LARGE on /v1/rates: the most \"items × services\" combinations allowed per request (200)."
          },
          "combinations": {
            "type": "integer",
            "description": "Only for BATCH_TOO_LARGE on /v1/rates: the number of combinations in this request."
          },
          "retryAfter": {
            "type": "integer",
            "description": "For RATE_LIMITED / QUOTA_EXCEEDED: how many seconds until you can retry."
          }
        },
        "nullable": true
      },
      "ErrorEnvelope": {
        "type": "object",
        "required": [
          "success",
          "code",
          "message",
          "data",
          "requestId"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "code": {
            "$ref": "#/components/schemas/RequestCode"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "$ref": "#/components/schemas/ErrorData"
          },
          "requestId": {
            "type": "string"
          }
        }
      },
      "BatchSummary": {
        "type": "object",
        "required": [
          "total",
          "succeeded",
          "failed"
        ],
        "properties": {
          "total": {
            "type": "integer"
          },
          "succeeded": {
            "type": "integer",
            "description": "The number of items with success true (including \"accepted\" items such as PROCESSING)."
          },
          "failed": {
            "type": "integer"
          }
        }
      },
      "ItemResultBase": {
        "type": "object",
        "description": "Every result has these 5 keys. success and retryable are set by code alone (see x-item-success / x-retryable of ItemCode).",
        "required": [
          "index",
          "success",
          "code",
          "message",
          "retryable"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "description": "The position in the request array (starting at 0, in the same order as the request)."
          },
          "success": {
            "type": "boolean"
          },
          "code": {
            "$ref": "#/components/schemas/ItemCode"
          },
          "message": {
            "type": "string",
            "description": "An English description; an empty string for OK."
          },
          "retryable": {
            "type": "boolean",
            "description": "Whether resending this item unchanged could succeed."
          }
        }
      },
      "UnitSystem": {
        "type": "string",
        "enum": [
          "imperial",
          "metric"
        ],
        "description": "Required, no default. imperial = pounds / inches (lb / in); metric = kilograms / centimeters (kg / cm)."
      },
      "Currency": {
        "type": "string",
        "enum": [
          "USD"
        ]
      },
      "Address": {
        "type": "object",
        "description": "Strings are trimmed of leading and trailing spaces; unknown fields are ignored.",
        "required": [
          "name",
          "address1",
          "city",
          "state",
          "postalCode"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 100
          },
          "company": {
            "type": "string",
            "maxLength": 100
          },
          "phone": {
            "type": "string",
            "maxLength": 30,
            "description": "For a US shipTo when rating and creating orders: if filled in, it must be exactly 10 digits (e.g. 2125550100; no +1, extension, spaces, dashes or parentheses), otherwise that item gets RECEIVER_PHONE_INVALID. shipFrom and non-US addresses are not checked."
          },
          "email": {
            "type": "string",
            "maxLength": 100
          },
          "address1": {
            "type": "string",
            "maxLength": 100
          },
          "address2": {
            "type": "string",
            "maxLength": 100
          },
          "city": {
            "type": "string",
            "maxLength": 60
          },
          "state": {
            "type": "string",
            "maxLength": 30,
            "description": "For a US address, it must be the 2-letter state code (such as CA); any case is accepted and converted to upper case."
          },
          "postalCode": {
            "type": "string",
            "maxLength": 20,
            "description": "For a US address, it must be 12345 or 12345-6789."
          },
          "country": {
            "type": "string",
            "pattern": "^[A-Za-z]{2}$",
            "default": "US",
            "description": "2-letter country code; may be omitted (default US); converted to upper case."
          },
          "residential": {
            "type": "boolean",
            "default": false,
            "description": "Whether it is a residential address (affects the residential surcharge); default false."
          }
        }
      },
      "Package": {
        "type": "object",
        "required": [
          "weight",
          "length",
          "width",
          "height"
        ],
        "properties": {
          "weight": {
            "type": "number",
            "exclusiveMinimum": true,
            "minimum": 0,
            "maximum": 2000,
            "description": "Weight of a single piece; the unit is set by unitSystem."
          },
          "length": {
            "type": "number",
            "exclusiveMinimum": true,
            "minimum": 0,
            "maximum": 500
          },
          "width": {
            "type": "number",
            "exclusiveMinimum": true,
            "minimum": 0,
            "maximum": 500
          },
          "height": {
            "type": "number",
            "exclusiveMinimum": true,
            "minimum": 0,
            "maximum": 500
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 1,
            "description": "Number of identical pieces. Each piece is one package, that is, one order; at most 50 pieces in total over all entries of a shipment."
          }
        }
      },
      "Packages": {
        "type": "array",
        "minItems": 1,
        "maxItems": 50,
        "items": {
          "$ref": "#/components/schemas/Package"
        },
        "description": "1–50 entries; counting quantity, at most 50 packages per shipment (x-max-packages). An order with several packages is split into several orders.",
        "x-max-packages": 50
      },
      "RateShipment": {
        "type": "object",
        "required": [
          "shipFrom",
          "shipTo",
          "packages"
        ],
        "properties": {
          "ref": {
            "type": "string",
            "maxLength": 64,
            "description": "Optional; echoed back unchanged so you can match the results."
          },
          "serviceCode": {
            "type": "string",
            "description": "Optional. Use either this or serviceCodeGroup; leave both out = rate every service you can use."
          },
          "serviceCodeGroup": {
            "type": "string",
            "minLength": 1,
            "maxLength": 50,
            "description": "Optional. The name of one of your service code groups (case-sensitive and must match exactly; leading and trailing spaces are ignored). Returns one rate: the lowest price in the group right now (serviceCode / carrier / service are null; which service it is is not said). Sent together with serviceCode ⇒ that item gets INVALID_SHIPMENT; not found ⇒ SERVICE_CODE_GROUP_NOT_FOUND; no service in the group you can use right now ⇒ SERVICE_CODE_GROUP_EMPTY."
          },
          "shipFrom": {
            "$ref": "#/components/schemas/Address"
          },
          "shipTo": {
            "$ref": "#/components/schemas/Address"
          },
          "packages": {
            "$ref": "#/components/schemas/Packages"
          }
        }
      },
      "RatesRequest": {
        "type": "object",
        "required": [
          "unitSystem",
          "shipments"
        ],
        "properties": {
          "unitSystem": {
            "$ref": "#/components/schemas/UnitSystem"
          },
          "shipments": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/RateShipment"
            },
            "description": "1..100 items; and \"number of items × number of services to rate × number of different package sizes in the item\" ≤ 200.",
            "x-max-combinations": 200
          }
        }
      },
      "Rate": {
        "type": "object",
        "required": [
          "serviceCode",
          "carrier",
          "service",
          "totalCharge",
          "currency"
        ],
        "properties": {
          "serviceCode": {
            "type": "string",
            "description": "Service code (an opaque string; pass it back unchanged when creating orders). null for a service code group rate.",
            "nullable": true
          },
          "carrier": {
            "type": "string",
            "example": "usps",
            "description": "Carrier, such as ups / usps / fedex. null for a service code group rate.",
            "nullable": true
          },
          "service": {
            "type": "string",
            "example": "usps_ground_advantage",
            "description": "Carrier service, such as ups_ground / fedex_ground. null for a service code group rate.",
            "nullable": true
          },
          "serviceCodeGroup": {
            "type": "string",
            "description": "Present only for a service code group rate: the group name you sent (with leading and trailing spaces removed). To order, put it in serviceCodeGroup."
          },
          "totalCharge": {
            "type": "string",
            "pattern": "^\\d+\\.\\d{2}$",
            "example": "12.34",
            "description": "Total amount payable. An amount string, in US dollars, with two decimal places. Convert it to a number before doing arithmetic."
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "packageRates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PackageRate"
            },
            "description": "Only in a rate for several packages (quantity counted): one price per package, in package order; totalCharge is their sum."
          }
        }
      },
      "UnavailableService": {
        "type": "object",
        "required": [
          "serviceCode",
          "code",
          "message",
          "retryable",
          "carrierMessage"
        ],
        "properties": {
          "serviceCode": {
            "type": "string",
            "description": "The service code that returned no rate; null for a service code group rate.",
            "nullable": true
          },
          "code": {
            "type": "string",
            "enum": [
              "NO_RATE",
              "CARRIER_RATE_ERROR",
              "RATE_TIMEOUT",
              "SERVICE_NOT_AVAILABLE",
              "SERVICE_CODE_GROUP_NOT_FOUND",
              "SERVICE_CODE_GROUP_EMPTY",
              "RECEIVER_PHONE_INVALID"
            ]
          },
          "message": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          },
          "carrierMessage": {
            "type": "string",
            "description": "The carrier's own words (redacted and truncated); null when there are none, and always null for a service code group rate.",
            "nullable": true
          }
        }
      },
      "RateResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ItemResultBase"
          },
          {
            "type": "object",
            "required": [
              "ref",
              "rates",
              "unavailable"
            ],
            "properties": {
              "ref": {
                "type": "string",
                "nullable": true
              },
              "rates": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Rate"
                },
                "description": "From lowest to highest price."
              },
              "unavailable": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/UnavailableService"
                },
                "description": "Services that returned no rate, with the reasons."
              },
              "errors": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/FieldError"
                },
                "description": "Only with INVALID_SHIPMENT or RECEIVER_PHONE_INVALID."
              }
            }
          }
        ]
      },
      "References": {
        "type": "object",
        "properties": {
          "reference1": {
            "type": "string",
            "maxLength": 50
          },
          "reference2": {
            "type": "string",
            "maxLength": 50
          }
        }
      },
      "CreateOrderItem": {
        "type": "object",
        "required": [
          "customerOrderNo",
          "shipFrom",
          "shipTo",
          "packages"
        ],
        "properties": {
          "customerOrderNo": {
            "type": "string",
            "pattern": "^[A-Za-z0-9._\\-/]{1,64}$",
            "description": "Customer order number, required. Case-sensitive and never normalized (leading or trailing spaces make it invalid outright). Once used, it belongs to that order forever."
          },
          "serviceCode": {
            "type": "string",
            "maxLength": 128,
            "description": "The service code from /v1/rates, passed back unchanged. Give exactly one of this and serviceCodeGroup."
          },
          "serviceCodeGroup": {
            "type": "string",
            "minLength": 1,
            "maxLength": 50,
            "description": "The name of one of your service code groups (case-sensitive and must match exactly; leading and trailing spaces are ignored). Right before buying, we buy the cheapest service in the group at that moment; the order view gives no carrier / service until the label is bought, and its serviceCode is always null. Give exactly one of this and serviceCode (neither or both ⇒ that item gets INVALID_ORDER); not found ⇒ SERVICE_CODE_GROUP_NOT_FOUND; no service in the group you can use right now ⇒ SERVICE_CODE_GROUP_EMPTY."
          },
          "shipDate": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "description": "Ship date YYYY-MM-DD. May be omitted: when omitted, the UTC date of the day the order is created."
          },
          "maxCharge": {
            "type": "string",
            "pattern": "^\\d{1,7}(\\.\\d{1,2})?$",
            "description": "Optional, an amount string (a number type is not accepted). If our rate right before the purchase is above it, we do not buy (the order is FAILED / PRICE_ABOVE_MAX and nothing is charged). Cannot be used yet with several packages in one order (quantity counted): that item gets INVALID_ORDER."
          },
          "shipFrom": {
            "$ref": "#/components/schemas/Address"
          },
          "shipTo": {
            "$ref": "#/components/schemas/Address"
          },
          "packages": {
            "$ref": "#/components/schemas/Packages"
          },
          "references": {
            "$ref": "#/components/schemas/References"
          }
        }
      },
      "CreateOrdersRequest": {
        "type": "object",
        "required": [
          "unitSystem",
          "orders"
        ],
        "properties": {
          "unitSystem": {
            "$ref": "#/components/schemas/UnitSystem"
          },
          "confirm": {
            "type": "boolean",
            "default": true,
            "description": "true (default) = create the order + charge + buy the label; false = create a draft only."
          },
          "orders": {
            "type": "array",
            "minItems": 1,
            "maxItems": 500,
            "items": {
              "$ref": "#/components/schemas/CreateOrderItem"
            },
            "description": "1..500 items; the packages of all items together (quantity counted) ≤ 500."
          }
        }
      },
      "OrderStatus": {
        "type": "string",
        "enum": [
          "DRAFT",
          "PROCESSING",
          "CREATED",
          "FAILED",
          "CANCEL_PENDING",
          "CANCELLED"
        ],
        "description": "DRAFT draft · PROCESSING processing (not a failure; do not resend with a new number) · CREATED label bought and charged · FAILED definite failure (no label bought, nothing charged) · CANCEL_PENDING cancellation request submitted, waiting for our refund review · CANCELLED cancelled and refunded."
      },
      "LabelStatus": {
        "type": "string",
        "enum": [
          "NOT_CREATED",
          "PENDING",
          "READY",
          "BLOCKED_CANCELLED"
        ],
        "description": "NOT_CREATED no label bought · PENDING label bought, but the file comes later · READY can be fetched · BLOCKED_CANCELLED being cancelled / cancelled, no longer provided."
      },
      "TrackingStatus": {
        "type": "string",
        "enum": [
          "PRE_SHIPMENT",
          "IN_TRANSIT",
          "OUT_FOR_DELIVERY",
          "DELIVERED",
          "RETURNED",
          "EXCEPTION",
          "UNKNOWN"
        ]
      },
      "CancelStatus": {
        "type": "string",
        "enum": [
          "PROCESSING",
          "PENDING_REVIEW",
          "APPROVED",
          "REJECTED",
          "FAILED"
        ],
        "description": "PROCESSING cancelling with the carrier · PENDING_REVIEW the carrier has cancelled, waiting for our refund review (not refunded) · APPROVED refunded · REJECTED rejected in review, not refunded · FAILED the cancellation did not succeed, not refunded."
      },
      "StatusReason": {
        "type": "object",
        "description": "Not null only when status is FAILED or PROCESSING; the five keys are always present.",
        "required": [
          "code",
          "message",
          "carrierCode",
          "carrierMessage",
          "quotedCharge"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "ORDER_PROCESSING for PROCESSING; for FAILED, the failure reason code (one of ItemCode)."
          },
          "message": {
            "type": "string"
          },
          "carrierCode": {
            "type": "string",
            "description": "Only for CARRIER_REJECTED when the carrier gave a code; always null for a service code group order.",
            "nullable": true
          },
          "carrierMessage": {
            "type": "string",
            "description": "The carrier's own words (redacted and truncated); always null for a service code group order (code / message give the reason and the next step).",
            "nullable": true
          },
          "quotedCharge": {
            "type": "string",
            "pattern": "^\\d+\\.\\d{2}$",
            "example": "27.40",
            "description": "Only for PRICE_ABOVE_MAX: the rate quoted right before the purchase. An amount string, in US dollars, with two decimal places. Convert it to a number before doing arithmetic.",
            "nullable": true
          }
        },
        "nullable": true
      },
      "CancelView": {
        "type": "object",
        "description": "null if a cancellation was never requested; the nine keys are always present.",
        "required": [
          "status",
          "code",
          "message",
          "carrierMessage",
          "requestedAt",
          "reviewedAt",
          "refundAmount",
          "currency",
          "rejectReason"
        ],
        "properties": {
          "status": {
            "$ref": "#/components/schemas/CancelStatus"
          },
          "code": {
            "type": "string",
            "description": "Only for FAILED: CARRIER_CANCEL_REJECTED / CARRIER_ORDER_NOT_FOUND / CARRIER_CANCEL_UNCONFIRMED / CANCEL_TEMPORARILY_UNAVAILABLE / ORDER_NOT_SHIPPED / ORDER_PROCESSING.",
            "nullable": true
          },
          "message": {
            "type": "string"
          },
          "carrierMessage": {
            "type": "string",
            "description": "The carrier's own words. null when the carrier simply refuses to cancel (CARRIER_CANCEL_REJECTED).",
            "nullable": true
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "reviewedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "refundAmount": {
            "type": "string",
            "pattern": "^\\d+\\.\\d{2}$",
            "example": "12.34",
            "description": "Only for APPROVED: the refund amount. An amount string, in US dollars, with two decimal places. Convert it to a number before doing arithmetic.",
            "nullable": true
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "rejectReason": {
            "type": "string",
            "description": "Only for REJECTED: the rejection reason.",
            "nullable": true
          }
        },
        "nullable": true
      },
      "OrderView": {
        "type": "object",
        "description": "The public view of an order. Every key is always present (null when there is no value).",
        "required": [
          "customerOrderNo",
          "orderNo",
          "status",
          "statusReason",
          "serviceCode",
          "carrier",
          "service",
          "totalCharge",
          "currency",
          "trackingNumber",
          "labelReady",
          "labelStatus",
          "labelUrl",
          "labelUrlExpiresAt",
          "trackingStatus",
          "trackingUpdatedAt",
          "cancel",
          "createdAt",
          "submittedAt"
        ],
        "properties": {
          "customerOrderNo": {
            "type": "string",
            "description": "Customer order number; null for orders placed by hand in the dashboard.",
            "nullable": true
          },
          "orderNo": {
            "type": "string",
            "description": "OminiShip order number (ORD-…; SBX-… for test orders).",
            "nullable": true
          },
          "status": {
            "$ref": "#/components/schemas/OrderStatus"
          },
          "statusReason": {
            "$ref": "#/components/schemas/StatusReason"
          },
          "serviceCode": {
            "type": "string",
            "description": "Given only for orders created through this API with a serviceCode; null for orders created in the dashboard or with a service code group.",
            "nullable": true
          },
          "carrier": {
            "type": "string",
            "description": "Carrier; null until the label is bought for an order created with a service code group.",
            "nullable": true
          },
          "service": {
            "type": "string",
            "description": "Carrier service; null until the label is bought for an order created with a service code group.",
            "nullable": true
          },
          "totalCharge": {
            "type": "string",
            "pattern": "^\\d+\\.\\d{2}$",
            "example": "12.34",
            "description": "Amount charged (has a value only for CREATED / CANCEL_PENDING / CANCELLED). An amount string, in US dollars, with two decimal places. Convert it to a number before doing arithmetic.",
            "nullable": true
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "trackingNumber": {
            "type": "string",
            "description": "Has a value only in the charged statuses.",
            "nullable": true
          },
          "labelReady": {
            "type": "boolean"
          },
          "labelStatus": {
            "$ref": "#/components/schemas/LabelStatus"
          },
          "labelUrl": {
            "type": "string",
            "format": "uri",
            "description": "Given only when READY and we have prepared the label file (valid for 1 hour); otherwise null, so fetch it with /v1/orders/labels.",
            "nullable": true
          },
          "labelUrlExpiresAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "trackingStatus": {
            "$ref": "#/components/schemas/TrackingStatus",
            "nullable": true
          },
          "trackingUpdatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When we last updated the tracking status (not a real-time query).",
            "nullable": true
          },
          "cancel": {
            "$ref": "#/components/schemas/CancelView"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "submittedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "PackageRate": {
        "type": "object",
        "description": "The price of one package.",
        "required": [
          "packageIndex",
          "totalCharge"
        ],
        "properties": {
          "packageIndex": {
            "type": "integer",
            "minimum": 1,
            "description": "Which package it is (from 1; after quantity is expanded, in request order)."
          },
          "totalCharge": {
            "type": "string",
            "example": "7.10",
            "description": "Amount string, USD, 2 decimals."
          }
        }
      },
      "SplitOrderFields": {
        "type": "object",
        "description": "Only on an order split from an order with several packages (an order with one package has neither key).",
        "properties": {
          "packageIndex": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "description": "Which package of the group this order is (from 1)."
          },
          "packageCount": {
            "type": "integer",
            "minimum": 2,
            "maximum": 50,
            "description": "How many packages (that is, orders) the group has."
          }
        }
      },
      "PackageOrderEntry": {
        "type": "object",
        "description": "The order of one package: packageIndex + success / code / message / retryable; the other fields are those that item would have if this order were named on its own (orderNo): create orders adds replayed and all order view fields, order info all order view fields, labels the label fields, cancel the cancellation fields.",
        "required": [
          "packageIndex",
          "success",
          "code",
          "message",
          "retryable"
        ],
        "properties": {
          "packageIndex": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50
          },
          "success": {
            "type": "boolean"
          },
          "code": {
            "$ref": "#/components/schemas/ItemCode"
          },
          "message": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          }
        },
        "additionalProperties": true
      },
      "PackageGroupResult": {
        "description": "One result for an order with several packages named by its customer order number (create orders / order info / labels / cancel). code: the code all packages share, if they do; otherwise OK when every package succeeded, else the code of the first package that did not.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ItemResultBase"
          },
          {
            "type": "object",
            "required": [
              "customerOrderNo",
              "packageCount",
              "orders"
            ],
            "properties": {
              "replayed": {
                "type": "boolean",
                "description": "Create orders only: true when the orders of all packages already existed."
              },
              "customerOrderNo": {
                "type": "string",
                "description": "Customer order number (the number of the group)."
              },
              "packageCount": {
                "type": "integer",
                "minimum": 2,
                "maximum": 50
              },
              "orders": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PackageOrderEntry"
                },
                "description": "One entry per package, in package order."
              }
            }
          }
        ]
      },
      "CreateOrderAccepted": {
        "description": "Accepted / replayed: carries all order view fields. When the order is FAILED, code is the failure reason code and success is false; when PROCESSING, success is true.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ItemResultBase"
          },
          {
            "type": "object",
            "required": [
              "replayed"
            ],
            "properties": {
              "replayed": {
                "type": "boolean",
                "description": "true = an order with this customer order number already existed, and this is that order."
              }
            }
          },
          {
            "$ref": "#/components/schemas/OrderView"
          },
          {
            "$ref": "#/components/schemas/SplitOrderFields"
          }
        ]
      },
      "CreateOrderRefused": {
        "description": "Refused: this request created nothing for this item and charged nothing.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ItemResultBase"
          },
          {
            "type": "object",
            "properties": {
              "customerOrderNo": {
                "type": "string",
                "nullable": true
              },
              "errors": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/FieldError"
                },
                "description": "Only with INVALID_ORDER."
              },
              "required": {
                "type": "string",
                "example": "36.00",
                "description": "Only for an order with several packages whose balance does not cover all of them (INSUFFICIENT_BALANCE): the amount needed to buy every package of this request (the sum of each package's rate plus its price-change allowance). Money string, USD, 2 decimals."
              },
              "shortfall": {
                "type": "string",
                "example": "6.00",
                "description": "Together with required: the amount missing. Money string, USD, 2 decimals."
              },
              "carrierMessage": {
                "type": "string",
                "description": "May appear only when an order with several packages is refused because one package could not be rated: the carrier's own words."
              }
            }
          }
        ]
      },
      "CreateOrderResult": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/CreateOrderAccepted"
          },
          {
            "$ref": "#/components/schemas/CreateOrderRefused"
          },
          {
            "$ref": "#/components/schemas/PackageGroupResult"
          }
        ]
      },
      "OrderRef": {
        "type": "object",
        "description": "One of three: exactly one must be given.",
        "properties": {
          "customerOrderNo": {
            "type": "string",
            "maxLength": 64
          },
          "orderNo": {
            "type": "string",
            "maxLength": 64,
            "description": "OminiShip order number, not case-sensitive."
          },
          "trackingNumber": {
            "type": "string",
            "maxLength": 64,
            "description": "May not be found for about 1 minute right after the label is bought; prefer the customer order number."
          }
        }
      },
      "IdentifierFailure": {
        "description": "Identifier failure: echoes back the identifier field you sent.",
        "allOf": [
          {
            "$ref": "#/components/schemas/ItemResultBase"
          },
          {
            "type": "object",
            "properties": {
              "customerOrderNo": {
                "type": "string"
              },
              "orderNo": {
                "type": "string"
              },
              "trackingNumber": {
                "type": "string"
              },
              "orderNos": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Only for AMBIGUOUS_TRACKING_NUMBER: the candidate OminiShip order numbers under your own account."
              }
            }
          }
        ]
      },
      "OrdersInfoRequest": {
        "type": "object",
        "required": [
          "orders"
        ],
        "properties": {
          "orders": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/OrderRef"
            },
            "description": "1..100 items; the orders the identifiers name ≤ 100 in all (every order of a split group counts)."
          }
        }
      },
      "OrderInfoFound": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ItemResultBase"
          },
          {
            "$ref": "#/components/schemas/OrderView"
          },
          {
            "$ref": "#/components/schemas/SplitOrderFields"
          }
        ]
      },
      "OrderInfoResult": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/OrderInfoFound"
          },
          {
            "$ref": "#/components/schemas/IdentifierFailure"
          },
          {
            "$ref": "#/components/schemas/PackageGroupResult"
          }
        ]
      },
      "LabelsRequest": {
        "type": "object",
        "required": [
          "orders"
        ],
        "properties": {
          "format": {
            "type": "string",
            "enum": [
              "url",
              "base64",
              "merged"
            ],
            "default": "url"
          },
          "orders": {
            "type": "array",
            "minItems": 1,
            "maxItems": 500,
            "items": {
              "$ref": "#/components/schemas/OrderRef"
            },
            "description": "The limit depends on format: url 500 · base64 20 · merged 100; the orders the identifiers name have the same limit (every order of a split group counts).",
            "x-max-items-by-format": {
              "url": 500,
              "base64": 20,
              "merged": 100
            }
          }
        }
      },
      "LabelResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ItemResultBase"
          },
          {
            "type": "object",
            "properties": {
              "customerOrderNo": {
                "type": "string",
                "nullable": true
              },
              "orderNo": {
                "type": "string",
                "nullable": true
              },
              "trackingNumber": {
                "type": "string",
                "nullable": true
              },
              "fileType": {
                "type": "string",
                "description": "url / base64: PDF / PNG / JPEG, or another format exactly as the carrier gives it (such as ZPL); UNKNOWN when it cannot be recognized."
              },
              "labelUrl": {
                "type": "string",
                "format": "uri",
                "description": "url: our download link, valid for 1 hour."
              },
              "expiresAt": {
                "type": "string",
                "format": "date-time"
              },
              "contentBase64": {
                "type": "string",
                "description": "base64: the label file content."
              },
              "merged": {
                "type": "boolean",
                "enum": [
                  true
                ],
                "description": "merged: this order has been put into the merged file."
              },
              "orderNos": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        ]
      },
      "MergedLabel": {
        "type": "object",
        "description": "Only for format = merged: one PDF combining every label that can be merged; null when none can be merged.",
        "required": [
          "labelUrl",
          "expiresAt",
          "pageCount"
        ],
        "properties": {
          "labelUrl": {
            "type": "string",
            "format": "uri"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "pageCount": {
            "type": "integer"
          }
        },
        "nullable": true
      },
      "CancelRequestItem": {
        "type": "object",
        "description": "One-of-three identifier + optional reason.",
        "properties": {
          "customerOrderNo": {
            "type": "string",
            "maxLength": 64
          },
          "orderNo": {
            "type": "string",
            "maxLength": 64
          },
          "trackingNumber": {
            "type": "string",
            "maxLength": 64
          },
          "reason": {
            "type": "string",
            "maxLength": 200,
            "description": "Optional, cancellation reason. Not a string, or longer than 200 characters ⇒ the whole request gets 400 and nothing is sent."
          }
        }
      },
      "CancelRequest": {
        "type": "object",
        "required": [
          "orders"
        ],
        "properties": {
          "orders": {
            "type": "array",
            "minItems": 1,
            "maxItems": 500,
            "items": {
              "$ref": "#/components/schemas/CancelRequestItem"
            },
            "description": "1..500 items; the orders the identifiers name ≤ 500 in all (every order of a split group counts)."
          }
        }
      },
      "CancelResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ItemResultBase"
          },
          {
            "type": "object",
            "properties": {
              "customerOrderNo": {
                "type": "string",
                "nullable": true
              },
              "orderNo": {
                "type": "string",
                "nullable": true
              },
              "trackingNumber": {
                "type": "string",
                "nullable": true
              },
              "status": {
                "$ref": "#/components/schemas/OrderStatus"
              },
              "cancel": {
                "$ref": "#/components/schemas/CancelView"
              },
              "orderNos": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        ]
      },
      "RatesResponse": {
        "type": "object",
        "required": [
          "success",
          "code",
          "message",
          "data",
          "requestId"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "OK"
            ]
          },
          "message": {
            "type": "string",
            "example": "Processed 2 item(s)."
          },
          "data": {
            "type": "object",
            "required": [
              "summary",
              "results"
            ],
            "properties": {
              "summary": {
                "$ref": "#/components/schemas/BatchSummary"
              },
              "results": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/RateResult"
                },
                "description": "In the same order as the request."
              }
            }
          },
          "requestId": {
            "type": "string"
          }
        }
      },
      "CreateOrdersResponse": {
        "type": "object",
        "required": [
          "success",
          "code",
          "message",
          "data",
          "requestId"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "OK"
            ]
          },
          "message": {
            "type": "string",
            "example": "Processed 2 item(s)."
          },
          "data": {
            "type": "object",
            "required": [
              "summary",
              "results"
            ],
            "properties": {
              "summary": {
                "$ref": "#/components/schemas/BatchSummary"
              },
              "results": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/CreateOrderResult"
                },
                "description": "In the same order as the request."
              }
            }
          },
          "requestId": {
            "type": "string"
          }
        }
      },
      "OrdersInfoResponse": {
        "type": "object",
        "required": [
          "success",
          "code",
          "message",
          "data",
          "requestId"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "OK"
            ]
          },
          "message": {
            "type": "string",
            "example": "Processed 2 item(s)."
          },
          "data": {
            "type": "object",
            "required": [
              "summary",
              "results"
            ],
            "properties": {
              "summary": {
                "$ref": "#/components/schemas/BatchSummary"
              },
              "results": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/OrderInfoResult"
                },
                "description": "In the same order as the request."
              }
            }
          },
          "requestId": {
            "type": "string"
          }
        }
      },
      "LabelsResponse": {
        "type": "object",
        "required": [
          "success",
          "code",
          "message",
          "data",
          "requestId"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "OK"
            ]
          },
          "message": {
            "type": "string",
            "example": "Processed 2 item(s)."
          },
          "data": {
            "type": "object",
            "required": [
              "summary",
              "results"
            ],
            "properties": {
              "summary": {
                "$ref": "#/components/schemas/BatchSummary"
              },
              "results": {
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/LabelResult"
                    },
                    {
                      "$ref": "#/components/schemas/PackageGroupResult"
                    }
                  ]
                },
                "description": "In the same order as the request."
              },
              "merged": {
                "$ref": "#/components/schemas/MergedLabel"
              }
            }
          },
          "requestId": {
            "type": "string"
          }
        }
      },
      "CancelResponse": {
        "type": "object",
        "required": [
          "success",
          "code",
          "message",
          "data",
          "requestId"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "OK"
            ]
          },
          "message": {
            "type": "string",
            "example": "Processed 2 item(s)."
          },
          "data": {
            "type": "object",
            "required": [
              "summary",
              "results"
            ],
            "properties": {
              "summary": {
                "$ref": "#/components/schemas/BatchSummary"
              },
              "results": {
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/CancelResult"
                    },
                    {
                      "$ref": "#/components/schemas/PackageGroupResult"
                    }
                  ]
                },
                "description": "In the same order as the request."
              }
            }
          },
          "requestId": {
            "type": "string"
          }
        }
      },
      "BalanceRequest": {
        "type": "object",
        "description": "An empty object {}; any keys in it are ignored."
      },
      "CreditView": {
        "type": "object",
        "description": "Your credit; the whole object is null when you have none. The three keys are always present.",
        "required": [
          "limit",
          "used",
          "remaining"
        ],
        "properties": {
          "limit": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{2}$",
            "example": "12.34",
            "description": "The credit limit. An amount string, USD, two decimal places."
          },
          "used": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{2}$",
            "example": "12.34",
            "description": "Used: how far the balance is below zero (at most limit)."
          },
          "remaining": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{2}$",
            "example": "12.34",
            "description": "Remaining: limit − used."
          }
        },
        "nullable": true
      },
      "BalanceView": {
        "type": "object",
        "description": "The six keys are always present. Every amount is a string with two decimal places, in USD; convert it to a number before doing arithmetic.",
        "required": [
          "currency",
          "balance",
          "reserved",
          "frozen",
          "available",
          "credit"
        ],
        "properties": {
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "balance": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{2}$",
            "example": "12.34",
            "description": "The balance; negative while a credit is in use."
          },
          "reserved": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{2}$",
            "example": "12.34",
            "description": "Reserved for orders whose labels are being bought."
          },
          "frozen": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{2}$",
            "example": "12.34",
            "description": "Frozen by us; only we can unfreeze it."
          },
          "available": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{2}$",
            "example": "12.34",
            "description": "What you can spend on new orders right now = balance − reserved − frozen (+ credit.limit). The very figure the create-orders endpoint checks: an order whose required amount (rate plus price-change allowance) is not more than it can be bought."
          },
          "credit": {
            "$ref": "#/components/schemas/CreditView"
          }
        }
      },
      "BalanceResponse": {
        "type": "object",
        "required": [
          "success",
          "code",
          "message",
          "data",
          "requestId"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "OK"
            ]
          },
          "message": {
            "type": "string"
          },
          "data": {
            "$ref": "#/components/schemas/BalanceView"
          },
          "requestId": {
            "type": "string"
          }
        }
      },
      "ListOrdersRequest": {
        "type": "object",
        "required": [
          "createdFrom",
          "createdTo"
        ],
        "properties": {
          "createdFrom": {
            "type": "string",
            "format": "date-time",
            "example": "2026-11-15T00:00:00Z",
            "description": "Start time (inclusive). An ISO 8601 date-time with a time zone (Z or ±hh:mm); a date alone or a time without a time zone is refused. Compared to the whole second."
          },
          "createdTo": {
            "type": "string",
            "format": "date-time",
            "example": "2026-11-15T00:00:00Z",
            "description": "End time (exclusive), same format; must be later than createdFrom, at most 31 days apart."
          },
          "status": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/OrderStatus"
            },
            "description": "List only orders in these statuses; omitted = every status."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50,
            "description": "At most this many orders per page."
          },
          "cursor": {
            "type": "string",
            "description": "nextCursor from the previous page's reply, unchanged; omit it for the first page. Valid only for the same customer account, the same kind of key and the same createdFrom / createdTo / status; otherwise 400 INVALID_CURSOR."
          }
        },
        "x-max-range-days": 31
      },
      "ListedOrder": {
        "allOf": [
          {
            "$ref": "#/components/schemas/OrderView"
          },
          {
            "$ref": "#/components/schemas/SplitOrderFields"
          }
        ]
      },
      "ListOrdersQuery": {
        "type": "object",
        "description": "The query that was applied (whole seconds, UTC).",
        "required": [
          "createdFrom",
          "createdTo",
          "status",
          "limit"
        ],
        "properties": {
          "createdFrom": {
            "type": "string",
            "format": "date-time"
          },
          "createdTo": {
            "type": "string",
            "format": "date-time"
          },
          "status": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderStatus"
            },
            "nullable": true,
            "description": "null when omitted."
          },
          "limit": {
            "type": "integer"
          }
        }
      },
      "ListOrdersData": {
        "type": "object",
        "required": [
          "orders",
          "nextCursor",
          "query"
        ],
        "properties": {
          "orders": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ListedOrder"
            },
            "description": "Oldest first by creation time. May hold fewer than limit, even none; keep paging while nextCursor is not null. An order with several packages placed by hand in the dashboard is listed as its package orders, always on one page (more than limit when it has more packages than limit)."
          },
          "nextCursor": {
            "type": "string",
            "nullable": true,
            "description": "A string when there may be another page: send it unchanged as the next request's cursor; null when there is nothing more."
          },
          "query": {
            "$ref": "#/components/schemas/ListOrdersQuery"
          }
        }
      },
      "ListOrdersResponse": {
        "type": "object",
        "required": [
          "success",
          "code",
          "message",
          "data",
          "requestId"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "OK"
            ]
          },
          "message": {
            "type": "string",
            "example": "Listed 2 order(s)."
          },
          "data": {
            "$ref": "#/components/schemas/ListOrdersData"
          },
          "requestId": {
            "type": "string"
          }
        }
      }
    }
  }
}
