OminiShip
Developers Β· API v1

OminiShip Open API v1 Integration Guide

Version v1 Β· Updated 2026-11-18
Machine-readable spec: openapi.en.json in the same directory (OpenAPI 3.0.3; import it straight into Postman or use it to generate an SDK). This guide and the spec say the same thing; if they ever disagree, please contact us.

This API lets your system (a WMS, an ERP, your own back office and so on) do seven things as your OminiShip customer account:

What you can doEndpointLimit per request
Batch ratesPOST /v1/rates100 items (and "items Γ— services" ≀ 200)
Batch create orders (by default in one step: create the order + charge + buy the label)POST /v1/orders/create500 items, ≀ 500 packages in all (see 5.2)
Batch order info (status, price, tracking number, label link, tracking status, cancellation progress)POST /v1/orders/info100 items, ≀ 100 orders in all (see 5.3)
Batch labels (link / base64 / merged PDF)POST /v1/orders/labels500 / 20 / 100 items, same limits on orders (see 5.4)
Batch cancel (submits a cancellation request; refunded after our approval)POST /v1/orders/cancel500 items, ≀ 500 orders in all (see 5.5)
Check your balance (balance, reserved, frozen, available amount, credit)POST /v1/balanceNone (request body {}, see 5.6)
List orders by creation time (reconciliation, incremental sync)POST /v1/orders/list1–100 orders per page, time range ≀ 31 days (see 5.7)


Get an API key

You generate, view and revoke keys yourself in the OminiShip dashboard; there is no need to email us.

  1. Sign in to the dashboard with your OminiShip customer account and open Settings β†’ API Keys. No customer account yet? Please contact us to open one.
  2. First generate a test key (starting with zsk_test_) for integration testing: it never contacts a carrier and never charges you (see Section 9).
  3. Once it works, generate a live key (starting with zsk_live_) and switch your system to it to go live; no other code changes.
  4. The full key is shown only once, when it is generated, so save it right away. Each type allows at most 2 active keys. If a key leaks or someone leaves, generate a new key and switch to it first, then revoke the old one (see Section 2.8).
Sign in to generate a key

Contact us

Email us about:

  • Opening an OminiShip customer account
  • Reactivating a deactivated account (all its keys return 403)
  • A higher request quota
  • Persistent 5xx errors, or errors you cannot make sense of

Email: support@ominiship.com. For a specific request, include the requestId from the reply.

1. Quick start

#
  1. Get your keys: sign in to the OminiShip dashboard with your customer account, open Settings β†’ API Keys and generate the keys yourself: first generate a test key (starting with zsk_test_) for integration testing, and once that works, generate a live key (starting with zsk_live_). A key is shown in full only once, at the moment it is generated, so save it securely right away; we do not store it in plain text, so if you lose it, revoke the old one on the same page and generate a new one. Each type (test key and live key) allows at most 2 active keys (revoking one frees its slot); see Section 2.8 for details. No OminiShip customer account yet? Please contact us to open one.
  2. Get it working with the test key: a test key calls the same base URL and the same endpoints, but never contacts any carrier and never charges you anything; it returns test order numbers, test tracking numbers and sample labels (see Section 9). Run all seven endpoints and every error path you care about.
  3. Switch to the live key to go live: change the key to zsk_live_…; no other code changes. From then on, creating orders really charges you and really buys labels.

Smallest runnable example (rates):

curl -X POST https://openapi.ominiship.com/v1/rates \
  -H "Authorization: Bearer zsk_test_<your test key>" \
  -H "Content-Type: application/json" \
  -d '{
    "unitSystem": "imperial",
    "shipments": [{
      "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", "residential": true },
      "packages": [{ "weight": 2.5, "length": 10, "width": 8, "height": 4 }]
    }]
  }'

2. Conventions

#

2.1 Base URL and method

#
ItemConvention
Base URLhttps://openapi.ominiship.com (production only; test keys and live keys use the same base URL)
MethodAll 5 endpoints use POST
Request headersContent-Type: application/json; Authorization: Bearer <key>
PathsOnly the 5 paths under /v1/... are open. Any other path (including the old paths of the earlier beta) returns 404 NOT_FOUND
Field namesAlways camelCase; case-sensitive; unknown fields are ignored

2.2 Authentication

#
  • Every request must carry Authorization: Bearer <key>.
  • One key = one customer. You neither need to nor can pass a company or customer id in the request: the customer bound to the key is the one who places the orders, pays for them and requests cancellations; you can only see and act on that customer's own orders (including orders that customer placed by hand in the OminiShip dashboard).
  • A live key is zsk_live_ + 64 hex characters; a test key is zsk_test_ + 64 hex characters.
  • If a key leaks or someone on your team leaves, first generate a new key in the dashboard under Settings β†’ API Keys and switch your system to it, then revoke the old one; revoking takes effect immediately and cannot be undone, and the old key returns 401 API_KEY_REVOKED from its next request on. If you need help, you can contact us: our staff can revoke a key for you, but cannot generate one for you (the full key is shown only to you).
  • Do not send the X-Impersonate-Session request header (it is rejected: 400 IMPERSONATION_UNSUPPORTED).
  • Once the customer account bound to a key is deactivated, every key of that customer (live and test alike) returns 403 ACCOUNT_DEACTIVATED. The keys themselves are not revoked, so a new key will not help; please contact us, and once the account is reactivated the existing keys work again. Rejected requests do not count toward the rate limit.
  • Authentication is checked in this order, and the first check that fails is returned:
    the X-Impersonate-Session request header is present β‡’ 400 IMPERSONATION_UNSUPPORTED β†’
    the key is missing or malformed β‡’ 401 INVALID_API_KEY β†’
    we cannot verify keys right now β‡’ 503 API_KEY_LOOKUP_UNAVAILABLE β†’
    the key is invalid (does not exist β‡’ 401 INVALID_API_KEY; revoked or expired β‡’ 401 API_KEY_REVOKED) β†’
    the customer account is deactivated β‡’ 403 ACCOUNT_DEACTIVATED β†’
    over the rate limit β‡’ 429 RATE_LIMITED / QUOTA_EXCEEDED.
    Only after all of these pass do we check whether the account is enabled for this feature (403 ACCOUNT_NOT_ENABLED) and the request body (400 INVALID_REQUEST / BATCH_TOO_LARGE).

2.3 Reply format (envelope)

#

Every reply produced by our service (success, 4xx and 5xx alike) has this shape:

{
  "success": true,
  "code": "OK",
  "message": "Processed 2 item(s).",
  "data": { },
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}
FieldDescription
successWhether the request as a whole was processed
codeOK on success; on failure, a request-level error code (Section 10.1)
messageAn English description; on failure it states the next step. It is never "Internal server error"
dataThe endpoint's data; on failure it may carry details (such as errors, maxItems, maxPackages, retryAfter) or be null
requestIdThe ID of this request. Include it whenever you contact us about a problem

Suggested order of handling: read success / code first, then the HTTP status code.

  • Business outcomes (including "some items failed") are always HTTP 200.
  • Authentication failure 401, account not enabled or deactivated 403, malformed request 400, unknown path 404, rate limit 429, failure on our side 5xx (500 or 503): the reply body is still the envelope above.

Exceptions (not in the envelope format; handle them by HTTP status code only):

SituationWhat you seeWhat to do
Platform-wide per-second protective rate limitHTTP 429, the body is not an envelopeWait a few seconds and retry
Request timeout (about 30 seconds)HTTP 504, the body is not an envelopeResending unchanged with the same customer order number is safe (see Section 3); you will not be charged twice
In rare cases an unknown path is rejected by the gateway itselfHTTP 404, the body is not an envelopeCheck the method and the path

2.4 Batch results

#

The five endpoints for rates, creating orders, order info, labels and cancel are batch endpoints; on success data looks like this:

{
  "summary": { "total": 2, "succeeded": 1, "failed": 1 },
  "results": [
    { "index": 0, "success": true,  "code": "OK", "message": "", "retryable": false, "...": "fields of that endpoint" },
    { "index": 1, "success": false, "code": "ORDER_NOT_FOUND", "message": "No order of yours matches this identifier.", "retryable": false }
  ]
}
  • results is in the same order as the request array, and index is the position in the request (starting at 0).
  • A whole reply of success: true, code: "OK" only means "the request was processed"; check results[i].success item by item.
  • Every item has the five keys index, success, code, message and retryable. retryable: true means "resending this item unchanged may succeed".
  • summary.succeeded counts the items with success: true, including items that were "accepted and are processing".

2.5 Amounts, currency, units and time

#
ItemConvention
AmountsStrings with two decimal places, in US dollars, e.g. "12.34", "0.00". Convert them to numbers before doing arithmetic such as addition, and format them back to two decimal places for display
CurrencyEvery amount comes with "currency": "USD"
UnitsAt the top level of rate and create-order request bodies, unitSystem is required and has no default: "imperial" (lb / in) or "metric" (kg / cm). Without it the whole request gets 400
TimestampsISO 8601 UTC, e.g. 2026-10-19T08:00:00Z
Ship date shipDateYYYY-MM-DD; when omitted, the UTC date of the day the order is created
Empty optional fieldsA field with no value in a reply is always null; the key is always present

2.6 Rate limits

#
DimensionDefault quotaReply when exceeded
Per key per minute (UTC calendar minute)60 requests429 RATE_LIMITED; data.retryAfter = seconds until the next minute
Per key per day (UTC calendar day)5000 requests429 QUOTA_EXCEEDED; data.retryAfter = seconds until UTC midnight
  • One batch call counts as 1 request, no matter how many items it contains. So batch your calls as much as you can rather than calling one item at a time.
  • Test keys and live keys are counted separately.
  • After exceeding a limit, wait for retryAfter; requests sent while you wait are still rejected.
  • For a higher quota, please contact us.

2.7 Timeouts and retries

#
  • Every endpoint replies within about 20 seconds. We recommend a client timeout of 30 seconds or more.
  • When resending unchanged is safe: when you see retryable: true, a 5xx, a 504, or the connection drops and you do not know the outcome, just resend exactly the same request body (the same customer order numbers): order creation is deduplicated by customer order number, so no extra order is created and you are not charged twice (Section 3).
  • Do not resend with a new customer order number just because you see PROCESSING: that really buys a second label.

2.8 Getting and managing keys

#

You manage keys yourself in the OminiShip dashboard, under Settings β†’ API Keys (sign in with your customer account).

  • Generate: choose a test key or a live key, enter a name for it (1–50 characters, for example "WMS production") and click Generate. The full key is shown only this once; after you close it nobody (including us) can see it again, so copy and save it right away.
  • At most 2 per type: each customer account can have at most 2 active keys of each type (test and live); revoked keys do not take up a slot. If you are at the limit and want another one, first revoke a key you no longer use.
  • List: for each key you can see its name, type, last 4 characters, creation time, last-used time (accurate to about 1 minute) and status. Revoked keys also stay in the list so you can check them.
  • Rotate keys: generate a new key first β†’ switch your system to it and confirm that calls succeed β†’ then revoke the old key. In this order your integration is never interrupted.
  • Revoke: takes effect immediately and cannot be undone. After revoking, requests with that key return 401 API_KEY_REVOKED from the very next one.
  • Rate limits are counted per key (see 2.6).
  • If you suspect your account was compromised: change your sign-in password first, then go to Settings β†’ API Keys to check for and revoke any key you do not recognize. Changing the password does not automatically revoke keys.
  • Our staff can help you view and revoke keys, but cannot generate keys for you: the full key is shown only to you.

3. Customer order number (no duplicate orders)

#

3.1 Rules

#

Every item of an order-creation request must carry a customerOrderNo (the order number in your system).

RuleDescription
Format1–64 characters: letters, digits and . _ - / only
Case-sensitive, never alteredref-1 and REF-1 are two different order numbers; leading or trailing spaces make it invalid outright
ScopeUnique within your customer account; other customers of the same company can use the same numbers without affecting or seeing each other
Test and live are separateOrder numbers under test keys are unrelated to those under live keys
Once used, it belongs to that order foreverResending the same number only returns that order; it never creates an extra order or charges you again
Several packages = several ordersAn order with several packages (quantity counted) is split into several orders, each with 1 package and its own order number and tracking number; the customer order number is the number of the whole group, and resending it returns the same group of orders (see 5.2)
Cannot be reused after cancellationA number whose order was cancelled (or had a cancellation requested) cannot be used to ship again; to ship again, use a new number (for example WMS-10001-2)
New content needs a new numberThe same number with different content is rejected (CUSTOMER_ORDER_NO_CONFLICT); to change something, use a new number or edit the draft in the OminiShip dashboard
Numbers deleted in the dashboard cannot be reused eitherReturns CUSTOMER_ORDER_NO_USED

"Same content" means all of these match: unitSystem, serviceCode (or serviceCodeGroup), shipDate (the value as you sent it; omitted counts as omitted), maxCharge, both addresses (after trimming leading and trailing spaces), the packages and references. A request that omits shipDate and is resent unchanged the next day still counts as the same content.

3.2 What happens when a customer order number is sent again

#
The order this number already hasThis time confirm: false (draft only)This time confirm: true (default, buy the label)
NoneCreates a new draftCreates the order and buys the label
Draft DRAFTReturns this draftSame content β‡’ buys the label for this draft; different content β‡’ CUSTOMER_ORDER_NO_CONFLICT (nothing changed, no label bought)
Processing PROCESSINGReturns its current stateReturns its current state; it is not queued again
Label bought CREATEDReturns this orderReturns this order; you are not charged again (the content is not compared)
Failed FAILEDReturns the failure reasonSame content β‡’ retries buying the label once with the original content (same number); different content β‡’ CUSTOMER_ORDER_NO_CONFLICT
Being cancelled CANCEL_PENDING / cancelled CANCELLEDReturns this orderReturns this order (it cannot be reused; to ship again, use a new number)
Deleted in the dashboardCUSTOMER_ORDER_NO_USEDCUSTOMER_ORDER_NO_USED

When an existing order is returned, that item has replayed: true. Returning an existing order does not re-check whether its serviceCode (or service code group) is still available: even if the service was disabled later, resending the same number still returns that order; only when this request has to create an order or buy the label does an unavailable service return SERVICE_NOT_AVAILABLE (SERVICE_CODE_GROUP_NOT_FOUND / SERVICE_CODE_GROUP_EMPTY with a service code group; in which case nothing was created and nothing was charged this time).

With several packages (see 5.2), the table above is applied to each package's order; if any one package is refused (for example one of them was deleted in the dashboard), the whole item is refused and nothing is created or charged this time. A different number of packages (for example from 3 to 2) also counts as "different content": orders whose labels were bought return the original group as before, and drafts or failed orders return CUSTOMER_ORDER_NO_CONFLICT.

In one sentence: once used, a customer order number belongs to that order forever; resending the same number only returns that order and never charges you again.


4. One of three identifiers

#

In the three endpoints order info, labels and cancel, each item identifies the order with exactly one of the three fields below (0 of them, or 2 or more β‡’ that item gets INVALID_IDENTIFIER):

FieldWhat it isNotes
customerOrderNoYour customer order numberRecommended: can be looked up right away and is unique
orderNoThe OminiShip order number (ORD-…; SBX-… for test orders)Not case-sensitive; orders placed by hand in the OminiShip dashboard can only be looked up with it or with the tracking number
trackingNumberThe carrier's tracking numberMay not be found for about 1 minute right after the label is bought; if it matches more than one of your orders, AMBIGUOUS_TRACKING_NUMBER is returned with your candidate OminiShip order numbers listed in that item's orderNos
  • Each value is at most 64 characters and cannot contain spaces.
  • Whether the order does not exist or is not yours, you only get ORDER_NOT_FOUND (the reply is exactly the same in both cases).
  • When two items in the same request point to the same order, the later one returns DUPLICATE_IN_BATCH.
  • An item that fails on its identifier echoes back the identifier field you sent, so you can match it up.

5. Endpoints

#

5.1 Batch rates POST /v1/rates

#

Getting rates is free. Fully synchronous; replies within about 20 seconds.

Request

FieldTypeRequiredDescription
unitSystemstringYesimperial / metric
shipmentsarrayYes1–100 items
shipments[].refstringNo≀ 64 characters; echoed back unchanged so you can match the results
shipments[].serviceCodestringNoRate only this service; use either this or serviceCodeGroup; leave both out = rate every service you can use
shipments[].serviceCodeGroupstringNoThe name of one of your service code groups (≀ 50 characters; case-sensitive and must match exactly; leading and trailing spaces are ignored). Returns one rate: the lowest price in the group right now, without saying which service it is; sent together with serviceCode β‡’ that item gets INVALID_SHIPMENT
shipments[].shipFrom / shipToobjectYesAddress, see 6.1
shipments[].packagesarrayYesPackages, see 6.2; several packages (quantity counted) are rated package by package, at most 50 per shipment

"Number of items Γ— number of services to rate" (a service code group counts as the number of services in it that you can use; an item with several packages is further multiplied by its number of different package sizes) cannot exceed 200; above that the whole request gets 400 BATCH_TOO_LARGE (data carries maxItems, maxCombinations and combinations) and no carrier is asked at all: send fewer items or specify serviceCode.

Each result

FieldDescription
index / success / code / message / retryableSee 2.4
refThe ref you sent (null if you sent none)
rates[]The rates returned, from lowest to highest price: { serviceCode, carrier, service, totalCharge, currency }; a service code group returns exactly one: { serviceCode: null, carrier: null, service: null, serviceCodeGroup, totalCharge, currency }; with several packages each rate also carries packageRates: [ { packageIndex, totalCharge } ], one price per package, and totalCharge is their sum
unavailable[]Services that returned no rate: { serviceCode, code, message, retryable, carrierMessage }
errors[]Only with INVALID_SHIPMENT or RECEIVER_PHONE_INVALID: field errors (6.6)
  • At least one rate β‡’ that item is OK; none at all β‡’ that item's code is the reason given for the first unavailable service.
  • unavailable[].code: NO_RATE (the carrier gave no rate, or one of several packages got no rate; with the carrier's own words or our explanation), CARRIER_RATE_ERROR (retryable), RATE_TIMEOUT (retryable), SERVICE_NOT_AVAILABLE (a configuration issue on our side; please contact us).
  • The specified serviceCode is not yours / is disabled β‡’ that item gets SERVICE_NOT_AVAILABLE. The specified serviceCodeGroup is not found β‡’ SERVICE_CODE_GROUP_NOT_FOUND; the group has no service you can use right now β‡’ SERVICE_CODE_GROUP_EMPTY (no carrier is asked in either case).
  • A US recipient address (shipTo.country empty / US / USA) whose shipTo.phone is filled in but is not exactly 10 digits (no +1, extension, spaces, dashes or parentheses) β‡’ that item gets RECEIVER_PHONE_INVALID, with errors[] pointing at shipments[i].shipTo.phone (no carrier is asked).
  • serviceCode is an opaque string: store it as is and pass it back unchanged to the create-orders endpoint; do not parse it or build it yourself.
  • Rating with a service code group: we set up the groups on your account, and a group's name is the one you see when you create an order in the OminiShip dashboard. The reply does not say which service in the group it is (serviceCode / carrier / service are null); when no service in the group returns a rate, unavailable[] has exactly one entry, whose serviceCode and carrierMessage are null. To order, put the same group name in serviceCodeGroup of the create-orders endpoint (see 5.2).
  • carrier examples: ups, usps, fedex; service examples: ups_ground, usps_ground_advantage, fedex_ground.
  • Several packages (quantity counted) are rated package by package: each package later becomes its own order with its own tracking number, so the price is the sum of each package's own price; identical packages are asked about only once. A service counts as rated only when every package got a price; otherwise it goes to unavailable[], with a message starting Package k: that says which package got no rate. At most 50 packages per shipment (quantity counted); more β‡’ that item gets INVALID_SHIPMENT.

Success example (one item rates every service, one has a wrong postal code)

Request:

{
  "unitSystem": "imperial",
  "shipments": [
    {
      "ref": "quote-1",
      "shipFrom": { "name": "Warehouse A", "company": "Acme Fulfillment", "phone": "9095550100", "address1": "1000 E Example Ave", "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", "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", "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": "1011" },
      "packages": [ { "weight": 2.5, "length": 10, "width": 8, "height": 4 } ]
    }
  ]
}

Reply:

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

Failure example (missing unitSystem, whole request 400)

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

5.2 Batch create orders POST /v1/orders/create

#

Request

FieldTypeRequiredDescription
unitSystemstringYesimperial / metric
confirmbooleanNoDefault true: create the order + charge + buy the label; false: create a draft only (you can later submit it by hand in the OminiShip dashboard, or call this endpoint again with the same content + confirm: true)
ordersarrayYes1–500 items; the packages of all items together (quantity counted) must be 500 or fewer, otherwise the whole request is a 400 BATCH_TOO_LARGE (data carries maxItems, maxPackages, packages) and nothing is created or charged. An item that fails validation counts 0; an item with more than 50 packages counts 50 (it is still refused itself)
orders[].customerOrderNostringYesCustomer order number, see Section 3
orders[].serviceCodestringEitherThe service code from the rates endpoint, passed back unchanged (≀ 128 characters); give exactly one of this and serviceCodeGroup
orders[].serviceCodeGroupstringEitherThe name of one of your service code groups (≀ 50 characters; for the rules, see 5.1). 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; when the purchase fails, statusReason.carrierCode and carrierMessage are always null (the failure reason code and the next step are given as usual). Neither or both of the two β‡’ that item gets INVALID_ORDER
orders[].shipDatestringNoYYYY-MM-DD; when omitted, the UTC date of the day the order is created
orders[].maxChargestringNoAn amount string (such as "25.00"; a number type is rejected). 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 (that item gets INVALID_ORDER, see "Several packages in one order" below)
orders[].shipFrom / shipToobjectYesAddress, see 6.1
orders[].packagesarrayYesPackages, see 6.2; several packages (quantity counted) are split into several orders, see "Several packages in one order" below
orders[].referencesobjectNo{ "reference1": "…", "reference2": "…" }, each ≀ 50 characters; stored on the order, and printed on the label when the carrier supports it

How it is processed

  1. Accept first, then buy: each item that passes validation is created as an order right away (from that moment the order info endpoint can find it), and orders with confirm: true are then rated and get their labels bought in the background.
  2. When 20 or fewer orders in this request pass validation (several packages in one order count as that many orders), the endpoint waits up to 15 seconds and returns the orders that already have an outcome (CREATED or FAILED); those without an outcome yet are PROCESSING. With more than 20, it replies immediately.
  3. Items that are PROCESSING have success: true (accepted, not failed); poll them with the order info endpoint and do not resend with a new number.
  4. Items not yet accepted when time runs out return ACCEPT_TIMEOUT (retryable; resending unchanged is safe).

About prices

  • maxCharge caps our rate at the moment right before the purchase (all charges included).
  • At the actual purchase we rate once more, and the price may only stay the same or go down: if it went up, the order is not bought and nothing is charged, with status FAILED / PRICE_CHANGED (retryable: resending unchanged tries again at the current price).
  • For an order whose label was bought, the amount charged is the order's totalCharge.
  • To raise maxCharge: maxCharge is part of the order content, so changing it means "different content" and needs a new customer order number.

About the ship-from address: some services are bound to a fixed shipping warehouse. With such a service, shipFrom is only recorded, and the parcel actually ships from the bound warehouse address.

Each result

  • Accepted / existing order returned: { index, success, code, message, retryable, replayed, …all order view fields (6.3) }. code is OK; when the order is FAILED, code is the failure reason code and success: false.
  • Refused (nothing was created for this item this time and nothing was charged): { index, success: false, code, message, retryable, customerOrderNo, errors? }; code can be:
codeMeaningNext step
INVALID_ORDERA field is invalid, see errors[] (including maxCharge with several packages, or more than 50 packages)Fix it and resend; since nothing was created, you can keep using the same customer order number
DUPLICATE_IN_BATCHThe customer order number repeats within the same requestKeep only one
SERVICE_NOT_AVAILABLEThe service code is not yours or is disabledCall the rates endpoint first to confirm the services you can use
SERVICE_CODE_GROUP_NOT_FOUNDYour account has no service code group with this exact name (group names are case-sensitive)Check the group name and resend; since nothing was created, you can keep using the same customer order number
SERVICE_CODE_GROUP_EMPTYThis service code group has no service you can use right nowContact us, or use serviceCode instead
RECEIVER_PHONE_INVALIDThe shipTo.phone of a US recipient address is filled in but is not exactly 10 digits (no +1, extension, spaces, dashes or parentheses); see errors[]. Checked only when this request buys the label (confirm: false only creates a draft and is not checked)Fix it and send it again; since nothing was created, you can keep using the same customer order number (unless this number already holds a draft from an earlier confirm: false or a failed order: its phone cannot be changed, so use a new number)
CUSTOMER_ORDER_NO_CONFLICTThis number already has an order with different content (or an order created before 2026-11-04 with several packages on one label, which can no longer be bought)Use a new number
CUSTOMER_ORDER_NO_USEDThe order with this number was deleted in the dashboardUse a new number
ACCEPT_TIMEOUTIt could not be accepted in time for this requestResend unchanged

Note the difference: an INVALID_ORDER from the entry validation created nothing, so you can resend with the same number; but when an order that was already created fails at purchase because of a data problem (order FAILED, reason INVALID_ORDER), the number already belongs to that failed order, and changing the content needs a new number.

Failure reason codes (the code / statusReason.code when the order is FAILED)

FAILED always means no label was bought and nothing was charged (we only report FAILED when we can confirm that; when unsure, it is always PROCESSING):

ReasonDescriptionNext step
INSUFFICIENT_BALANCENot enough available balance (available = balance βˆ’ amounts reserved for orders in progress βˆ’ amounts frozen by us); for an order with several packages, a balance that does not cover all of them refuses the whole item with nothing created, with required / shortfall (see "Several packages in one order" below)Top up, or contact us to unfreeze the frozen amount, then resend the same number unchanged
PRICE_ABOVE_MAXThe rate is above maxCharge; the rate at that time is in statusReason.quotedChargeTo accept the new price, use a new number and raise maxCharge
PRICE_CHANGEDThe price went up when it was rechecked right before the purchaseResend the same number unchanged
CARRIER_REJECTEDThe carrier rejected the shipment, see statusReason.carrierCode / carrierMessageChange the content and use a new number
NO_RATEThe carrier gave no rate for this packageChange the service or the packages (with a new number)
CARRIER_RATE_ERRORThe carrier's rating service returned an errorResend the same number unchanged
SERVICE_NOT_AVAILABLEThe service is temporarily unavailable (when the cause is on our side, the message says to contact us)Contact us or change the service
SERVICE_CODE_GROUP_NOT_FOUNDThe service code group was deleted before the purchaseUse another group or serviceCode (with a new number)
SERVICE_CODE_GROUP_EMPTYThe group no longer had a service you can use at the time of the purchaseContact us, or use serviceCode (with a new number)
INVALID_ORDERThe order data was not acceptedChange the content and use a new number
SUBMIT_PAUSEDWe have paused label purchases (maintenance)Resend the same number unchanged later
SUBMIT_FAILEDThe label could not be bought for a reason on our side, and we are certain that nothing was charged (with a service code group, it can also mean the service picked by the rate left the group before the purchase)Resend the same number unchanged (a service code group is rated again); if it keeps failing, please contact us

Success example

Request:

{
  "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", "address1": "1000 E Example Ave", "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", "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", "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": 1 } ]
    }
  ]
}

Reply (the first order's label was bought; the second is still processing):

{
  "success": true,
  "code": "OK",
  "message": "Processed 2 item(s).",
  "data": {
    "summary": { "total": 2, "succeeded": 2, "failed": 0 },
    "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
      }
    ]
  },
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}

Failure example (one item has an invalid field, one has insufficient balance)

{
  "success": true,
  "code": "OK",
  "message": "Processed 2 item(s).",
  "data": {
    "summary": { "total": 2, "succeeded": 0, "failed": 2 },
    "results": [
      {
        "index": 0, "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[0].shipTo.city", "code": "REQUIRED", "message": "This field is required." } ]
      },
      {
        "index": 1, "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"
}

Several packages in one order

  • An order with several packages (quantity counted; for example one package with quantity: 2 plus another package = 3 packages) is split into 3 independent orders, each with 1 package, each rated, charged and getting its own label and tracking number. At most 50 packages per order.
  • The customer order number does not change and is the number of the group: resending the same number unchanged returns the same group of orders (nothing new is created, nothing is charged again); a different number of packages or different content is judged by Section 3. Each order also has its own order number orderNo.
  • The item has exactly one result, with packageCount (how many packages) and orders[] (one entry per package, in package order: packageIndex + that order's success / code / message / retryable / replayed + all order view fields). The item's 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.
  • When refused (INVALID_ORDER, CUSTOMER_ORDER_NO_CONFLICT and so on), the result has only the same few keys as for one package, and nothing of the group was created or charged.
  • The money must cover the whole group before anything is bought: when confirm is true, we first rate every package this request would buy, the way its own order will be rated, and your available balance must cover all of them (the sum of each package's rate plus its price-change allowance); if it does not, the whole item gets INSUFFICIENT_BALANCE, its message says how much is missing, it carries required (the amount needed) and shortfall (the amount missing), and no package is created, bought or charged β€” top up, then resend the same number unchanged. A package that cannot be rated refuses the whole item the same way (code is that package's rate code, message starts with Package k:).
  • Once the balance is enough, each package is bought on its own, so some packages may still have their labels bought while others are FAILED (for example when the carrier rejects one of them, or the same money is being spent elsewhere at the same time); resending the same number unchanged retries only the failed ones, and the bought ones are never charged again.
  • maxCharge cannot be used yet with several packages in one order (that item gets INVALID_ORDER); to cap the price, send each package as its own order, each with its own customer order number and maxCharge.
  • The order info, labels and cancel endpoints act on every order of the group when you name it by this customer order number (see 5.3 / 5.4 / 5.5); by orderNo or trackingNumber they act on that one order only.
  • An order holds only one package so that every package has its own tracking number; you cannot add packages to these orders in the OminiShip dashboard either.

Request:

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

Reply (all 3 packages have their labels bought):

{
  "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", "totalCharge": "14.20", "trackingNumber": "9400111899223344556601", "packageCount": 3, "...": "other order view fields (6.3)" },
          { "packageIndex": 2, "success": true, "code": "OK", "message": "", "retryable": false, "replayed": false, "customerOrderNo": "WMS-10005", "orderNo": "ORD-20261104-000202", "status": "CREATED", "totalCharge": "14.20", "trackingNumber": "9400111899223344556602", "packageCount": 3, "...": "other order view fields (6.3)" },
          { "packageIndex": 3, "success": true, "code": "OK", "message": "", "retryable": false, "replayed": false, "customerOrderNo": "WMS-10005", "orderNo": "ORD-20261104-000203", "status": "CREATED", "totalCharge": "6.92", "trackingNumber": "9400111899223344556603", "packageCount": 3, "...": "other order view fields (6.3)" }
        ]
      }
    ]
  },
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}

5.3 Batch order info POST /v1/orders/info

#

Request: { "orders": [ one identifier each, … ] }, 1–100 items (Section 4); a customer order number 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.

Each result

  • Found: { index, success: true, code: "OK", message: "", retryable: false, …all order view fields (6.3) }.
  • Not found: INVALID_IDENTIFIER / ORDER_NOT_FOUND / AMBIGUOUS_TRACKING_NUMBER (with orderNos) / DUPLICATE_IN_BATCH, echoing back the identifier field you sent.
  • If our read fails, the whole request gets 503 SERVICE_UNAVAILABLE (we never report a failure as "no such order"); retry later.
  • Looking up an order with several packages by its customer order number (see 5.2): one item comes back, with packageCount and orders[] (one entry per package: packageIndex + success / code / message / retryable + all order view fields); a package that cannot be found is ORDER_NOT_FOUND in its entry. By orderNo / trackingNumber you get only that one order, whose order view also carries packageIndex / packageCount (6.3). Asking for the group and for one of its orders in the same request β‡’ the later item gets DUPLICATE_IN_BATCH.

Notes:

  • You can only find the orders of the customer bound to the key; orders placed by hand in the OminiShip dashboard can be found too (customerOrderNo is null; look them up by OminiShip order number or tracking number).
  • The carrier is not queried in real time: trackingStatus is the latest tracking status we have stored, and trackingUpdatedAt is when it was updated.
  • labelUrl is given only when the label file is already prepared; when labelReady: true but labelUrl is null, get it from the labels endpoint.

Success example

Request:

{ "orders": [ { "customerOrderNo": "WMS-10001" }, { "orderNo": "ORD-20261019-000124" }, { "trackingNumber": "1Z999AA10123456784" } ] }

Reply (the first two are the same two orders as in the 5.2 example; only the third is shown in full here):

{
  "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", "...": "the rest of the order view fields" },
      { "index": 1, "success": true, "code": "OK", "message": "", "retryable": false, "customerOrderNo": "WMS-10002", "orderNo": "ORD-20261019-000124", "status": "PROCESSING", "...": "the rest of the order view fields" },
      { "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"
}

Failure example (the tracking number matches two of your orders)

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

The candidate order numbers are in that item's orderNos field.

5.4 Batch labels POST /v1/orders/labels

#

Request

FieldTypeRequiredDescription
formatstringNourl (default) / base64 / merged
ordersarrayYesOne identifier each; the limit depends on format: url 500, base64 20, merged 100; a customer order number naming a split group counts every order of the group, with the same limit on orders, otherwise the whole request is a 400 BATCH_TOO_LARGE and no label is read

Labels of an order with several packages by its customer order number (see 5.2): one item comes back, with one entry per package in orders[] (each with its own code, numbers and label fields); with merged, every package's label goes into the same PDF in package order. By orderNo / trackingNumber you get only that one label.

The three formats

formatFields of each successful itemDescription
urlfileType, labelUrl, expiresAtOur download link, valid for 1 hour; after it expires, call this endpoint again for a new link
base64fileType, contentBase64One reply carries at most about 5 MB of label content in total (measured after base64 encoding): the item that would push it over the limit returns RESPONSE_TOO_LARGE (retryable; fetch it with a separate request), and smaller labels after it that fit are still returned
mergedmerged: trueAll labels that can be merged are combined into one PDF, linked in data.merged = { labelUrl, expiresAt, pageCount } (null when none can be merged); an item in a format that cannot be merged (such as ZPL) returns LABEL_FORMAT_UNSUPPORTED and can be fetched on its own with url
  • Every item (successful, or failed for a label reason) carries customerOrderNo, orderNo and trackingNumber.
  • fileType: PDF, PNG, JPEG, or another format exactly as the carrier gives it (such as ZPL); UNKNOWN when it cannot be recognized.
  • Links are our links and their host name may change; treat them as opaque URLs and download them directly. The downloaded file is named after the OminiShip order number.
  • Orders being cancelled or cancelled no longer get labels (LABEL_BLOCKED_CANCELLED). A link handed out before the cancellation keeps working at most until its own 1-hour validity ends.
  • With some services, the label file is ready a little after the label is bought: LABEL_NOT_READY is returned (retryable). An order that is still processing also returns LABEL_NOT_READY.
  • Draft or failed orders have no label: ORDER_NOT_SHIPPED.
  • Items not ready when this request's time runs out: LABEL_PREPARING (retryable); the carrier's file temporarily cannot be fetched: LABEL_UNAVAILABLE (retryable).

Success example

Request:

{ "format": "url", "orders": [ { "customerOrderNo": "WMS-10001" }, { "customerOrderNo": "WMS-10009" } ] }

Reply (the second order is cancelled):

{
  "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 example

Request:

{ "format": "merged", "orders": [ { "customerOrderNo": "WMS-10001" }, { "orderNo": "ORD-20261019-000140" } ] }

Reply:

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

Failure example (more than 20 items with base64, whole request 400)

{
  "success": false,
  "code": "BATCH_TOO_LARGE",
  "message": "At most 20 items per request.",
  "data": { "maxItems": 20, "maxPackages": 20, "packages": null },
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}

5.5 Batch cancel POST /v1/orders/cancel

#

Read Section 8 first: cancellation needs our approval, and the API never says "cancelled successfully".

Request

FieldTypeRequiredDescription
ordersarrayYes1–500 items, each with one identifier; a customer order number 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
orders[].reasonstringNoCancellation reason, ≀ 200 characters. Not a string, or too long β‡’ the whole request gets 400 and nothing is sent

Each result: { index, success, code, message, retryable, customerOrderNo, orderNo, trackingNumber, status, cancel } (status is the order status; for cancel, see 6.5).

Cancelling an order with several packages by its customer order number (see 5.2): a cancellation request is filed for each order of the group that can be cancelled (each reviewed and refunded on its own), and the others are answered by the table below; one item comes back, with one entry per package in orders[] (the fields above + packageIndex). By orderNo / trackingNumber only that one order is cancelled.

Current order statusResult for the item
CREATED (label bought)Accepted: OK, cancel.status = PROCESSING. When this request has 20 or fewer items, it waits up to 15 seconds and may directly get PENDING_REVIEW (the carrier has cancelled; waiting for our refund review) or FAILED (that item's code is the carrier's reason for refusing, and success: false)
CREATED with a cancellation already in progressOK, cancel.status = PROCESSING; it is not sent again
CANCEL_PENDING (requested)CANCEL_ALREADY_REQUESTED (success: true), cancel.status = PENDING_REVIEW
CANCELLED (cancelled)ALREADY_CANCELLED (success: true), cancel.status = APPROVED
DRAFT / FAILEDORDER_NOT_SHIPPED: no label was bought and nothing was charged, so there is nothing to cancel (drafts can be deleted in the dashboard)
PROCESSINGORDER_PROCESSING (retryable): the label is still being bought; try again later
Could not be sent this timeCANCEL_TEMPORARILY_UNAVAILABLE (retryable): nothing changed; resend later
Identifier problemINVALID_IDENTIFIER / ORDER_NOT_FOUND / AMBIGUOUS_TRACKING_NUMBER / DUPLICATE_IN_BATCH

For items without a final result in this reply, check cancel with the order info endpoint.

Success example

Request:

{ "orders": [ { "customerOrderNo": "WMS-10001", "reason": "Customer changed mind" }, { "customerOrderNo": "WMS-10002" } ] }

Reply:

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

Failure example (the carrier refuses to cancel)

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

5.6 Check your balance POST /v1/balance

#

Request: {} (an empty object; any keys in it are ignored). A body that is not a JSON object gets a 400 INVALID_REQUEST for the whole request. Read-only; it changes nothing.

Reply: data always has the six keys below (every amount is a string with two decimal places, in USD):

FieldTypeDescription
currencystringAlways USD
balancestringYour balance; negative while you are using a credit
reservedstringReserved for orders: money held for orders whose labels are being bought; once the purchase finishes it becomes a charge or is released
frozenstringFrozen amount: frozen by us; only we can unfreeze it
availablestringWhat you can spend on new orders right now = balance βˆ’ reserved βˆ’ frozen + credit (with a credit, plus credit.limit)
creditobject | nullYour credit; null when you have none, otherwise three keys: limit (the credit limit), used (how much is used, i.e. how far the balance is below zero) and remaining (what is left)

Notes:

  • available is the very same figure the create-orders endpoint checks: an order whose required amount (its rate plus the price-change allowance) is not more than available can be bought; more than that is INSUFFICIENT_BALANCE (see 5.2); several orders in one request use it up one after another.
  • The balance can change at any moment (other orders being bought, refunds, top-ups); this is the figure at the moment we read it, and whether an order can be bought is decided by the create-orders reply.
  • We read the latest data, not a cache.
  • A test key returns your account's real balance, read-only; test orders never charge and never refund, so they never change it (Section 9).
  • If our read fails, the whole request gets 503 SERVICE_UNAVAILABLE; we never report a failure as a zero balance.

Example

Request:

{}

Reply (no credit):

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

Reply (a credit in use):

{
  "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"
}
curl -X POST https://openapi.ominiship.com/v1/balance \
  -H "Authorization: Bearer zsk_live_<your live key>" \
  -H "Content-Type: application/json" \
  -d '{}'

5.7 List orders by creation time POST /v1/orders/list

#

Lists every order of the customer bound to the key by creation time (orders placed by hand in the dashboard, uploaded in bulk, created automatically from a connected store, or created through this API), for reconciliation and incremental sync.

Request

FieldTypeRequiredDescription
createdFromstringYesStart time (inclusive). An ISO 8601 date-time with a time zone, such as 2026-11-15T00:00:00Z or 2026-11-15T00:00:00-08:00; a date alone (2026-11-15) or a time without a time zone is refused
createdTostringYesEnd time (exclusive), same format; must be later than createdFrom, and the two may be at most 31 days apart
statusstring[]NoList only orders in these statuses (for the values see 7.1), such as ["CREATED", "CANCELLED"]; omitted = every status
limitintegerNoAt most this many orders per page, 1–100, default 50
cursorstringNonextCursor from the previous page's reply, unchanged; omit it for the first page

Times are compared to the whole second: an order is listed when its creation time satisfies createdFrom ≀ createdAt < createdTo. So "all of yesterday" is createdFrom = yesterday at midnight and createdTo = today at midnight; back-to-back windows meet exactly, with no overlap and no gap. A field that is wrong gets a 400 INVALID_REQUEST for the whole request, with every field to fix listed in data.errors.

Reply: data = { orders, nextCursor, query }

FieldDescription
ordersThe orders, oldest first by creation time; each one is all order view fields (6.3), field for field the same as the order info endpoint (an order split from an order with several packages also carries packageIndex / packageCount)
nextCursorA string when there may be another page: put it unchanged into the next request's cursor; null when there is nothing more
queryThe query that was applied: createdFrom / createdTo (whole seconds, UTC), status (null when omitted) and limit

Notes:

  • Only orders of the customer bound to the key are listed; another customer's orders never appear, and deleted orders do not appear either.
  • A page can hold fewer orders than limit, even none; as long as nextCursor is not null, keep paging. With a status filter we look at no more than 500 orders per request, and we reply even when that does not fill a page.
  • An order with several packages placed by hand in the dashboard is listed as the orders its packages were split into, one by one (each with its own order number, tracking number and charge), at the original order's position and always on the same page; when it has more packages than limit, that page holds more orders than limit.
  • Orders created in the same second always come in the same order, so paging never repeats or skips one.
  • An order being cancelled or cancelled carries no label link (the same as the order info endpoint); labelUrl is given only when the label file is already prepared.
  • A cursor works only for the same customer account, the same kind of key (live / test) and the same createdFrom / createdTo / status (limit may change); otherwise the whole request gets 400 INVALID_CURSOR and nothing is read. To start over, omit cursor.
  • If our read fails, the whole request gets 503 SERVICE_UNAVAILABLE, never an empty list; resend it unchanged.

Example

Request (first page):

{ "createdFrom": "2026-11-15T00:00:00Z", "createdTo": "2026-11-16T00:00:00Z", "status": ["CREATED", "CANCELLED"], "limit": 2 }

Reply:

{
  "success": true,
  "code": "OK",
  "message": "Listed 2 order(s).",
  "data": {
    "orders": [
      { "customerOrderNo": "WMS-10001", "orderNo": "ORD-20261115-000123", "status": "CREATED", "totalCharge": "6.92", "currency": "USD", "createdAt": "2026-11-15T08:00:00Z", "...": "the other order view fields" },
      { "customerOrderNo": null, "orderNo": "ORD-20261115-000188", "status": "CANCELLED", "totalCharge": "8.15", "currency": "USD", "createdAt": "2026-11-15T09:30:12Z", "...": "the other order view fields" }
    ],
    "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"
}

Request (next page: the same query + cursor):

{ "createdFrom": "2026-11-15T00:00:00Z", "createdTo": "2026-11-16T00:00:00Z", "status": ["CREATED", "CANCELLED"], "limit": 2, "cursor": "eyJ2IjoxLCJiIjoiN2ZrUTJ4" }

Failure example (the cursor does not match this query)

{
  "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"
}
curl -X POST https://openapi.ominiship.com/v1/orders/list \
  -H "Authorization: Bearer zsk_live_<your live key>" \
  -H "Content-Type: application/json" \
  -d '{ "createdFrom": "2026-11-15T00:00:00-08:00", "createdTo": "2026-11-16T00:00:00-08:00" }'

6. Data structures

#

6.1 Address (shipFrom / shipTo)

#
FieldTypeRequiredLimits / description
namestringYes≀ 100
companystringNo≀ 100
phonestringNo≀ 30; for a US recipient address (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 is not checked
emailstringNo≀ 100
address1stringYes≀ 100
address2stringNo≀ 100
citystringYes≀ 60
statestringYes≀ 30; for a US address, it must be the 2-letter state code (such as CA); converted to upper case
postalCodestringYes≀ 20; for a US address, it must be 12345 or 12345-6789
countrystringNo2-letter country code, default US, converted to upper case
residentialbooleanNoWhether it is a residential address (affects the residential surcharge); default false

Strings are trimmed of leading and trailing spaces; unknown fields are ignored.

6.2 Package (packages[])

#

Each shipment has 1–50 package entries; counting quantity, at most 50 packages per shipment, and each package becomes its own order (see 5.2). Units are set by the top-level unitSystem of the request.

FieldTypeRequiredLimits
weightnumberYesWeight of a single piece, > 0 and ≀ 2000
length / width / heightnumberYes> 0 and ≀ 500
quantityintegerNoNumber of identical pieces, 1–100, default 1; each piece is one package

6.3 Order view

#

Every item of the order info endpoint, every accepted result of the create-orders endpoint and every order of the list-orders endpoint carries all of the fields below (the keys are always present; null when there is no value):

FieldTypeDescription
customerOrderNostring | nullCustomer order number; null for orders placed by hand in the dashboard
orderNostring | nullOminiShip order number ORD-… (SBX-… for test orders)
statusstringOrder status, see 7.1
statusReasonobject | nullHas a value only for FAILED / PROCESSING, see 6.4
serviceCodestring | nullGiven only for orders created through this API with a serviceCode; null for orders created in the dashboard or with a service code group
carrierstring | nullCarrier, such as usps; null until the label is bought for an order created with a service code group
servicestring | nullCarrier service, such as usps_ground_advantage; null until the label is bought for an order created with a service code group
totalChargestring | nullAmount charged; has a value only for CREATED / CANCEL_PENDING / CANCELLED
currencystringAlways USD
trackingNumberstring | nullTracking number; has a value only for CREATED / CANCEL_PENDING / CANCELLED
labelReadybooleanWhether the label can be fetched now
labelStatusstringLabel status, see 7.2
labelUrlstring | nullLabel link (valid for 1 hour), given only when the label file is prepared; otherwise fetch it with the labels endpoint
labelUrlExpiresAtstring | nullWhen the link above expires
trackingStatusstring | nullTracking status, see 7.3; null before the label is bought
trackingUpdatedAtstring | nullWhen we last updated the tracking status
cancelobject | nullCancellation progress, see 6.5; null if a cancellation was never requested
createdAtstring | nullWhen the order was created
submittedAtstring | nullWhen the label was bought

An order split from an order with several packages (see 5.2) carries two more fields: packageIndex (which package it is, from 1) and packageCount (how many packages the group has); an order with only one package has neither.

6.4 statusReason

#

Not null only when the order status is FAILED or PROCESSING; the five keys are always present:

FieldDescription
codeORDER_PROCESSING for PROCESSING; for FAILED, the failure reason code (see 5.2, "Failure reason codes")
messageEnglish description and next step
carrierCodeHas a value only for CARRIER_REJECTED when the carrier gave a code. Always null for a service code group order (the raw code could also reveal which service in the group it is)
carrierMessageThe carrier's own words (sensitive information removed, truncated to one line). Always null for a service code group order (the words could reveal which service in the group it is); code / message give the reason and the next step
quotedChargeOnly for PRICE_ABOVE_MAX: the rate quoted right before the purchase (an amount string)

6.5 cancel

#

null if a cancellation was never requested; otherwise the nine keys are always present:

FieldDescription
statusCancellation status, see 7.4
codeHas a value only for FAILED: CARRIER_CANCEL_REJECTED / CARRIER_ORDER_NOT_FOUND / CARRIER_CANCEL_UNCONFIRMED / CANCEL_TEMPORARILY_UNAVAILABLE / ORDER_NOT_SHIPPED / ORDER_PROCESSING
messageEnglish description and next step
carrierMessageThe carrier's own words. null when the carrier simply refuses to cancel (CARRIER_CANCEL_REJECTED); it may carry the carrier's words only when "the carrier cannot find this label" or "the carrier's answer cannot confirm the cancellation"
requestedAtWhen it was requested
reviewedAtWhen it was reviewed (APPROVED / REJECTED)
refundAmountOnly for APPROVED: the refund amount (a string)
currencyAlways USD
rejectReasonOnly for REJECTED: the rejection reason

6.6 Field errors errors[]

#

The data.errors of a whole-request 400 INVALID_REQUEST, and the errors of a per-item INVALID_ORDER / INVALID_SHIPMENT, all have elements like this:

FieldDescription
fieldFull JSON path, such as orders[1].shipTo.postalCode
codeREQUIRED (missing) / INVALID_TYPE (wrong type) / INVALID_VALUE (wrong value) / TOO_LONG (too long) / OUT_OF_RANGE (out of range)
messageEnglish description (never echoes the value you sent)

7. Statuses

#

7.1 Order status status

#
ValueMeaningWhat you should do
DRAFTDraft: the order was only created; no label was bought and nothing was charged (created with confirm: false)When you need the label, call the create-orders endpoint again with the same content + confirm: true, or submit it in the dashboard
PROCESSINGProcessing: accepted and the label is being bought, or we are automatically checking an order whose outcome is not yet confirmed. Not a failurePoll with the order info endpoint; do not resend with a new number
CREATEDLabel bought and chargedFetch the label
FAILEDA definite failure: no label was bought and nothing was charged; the reason is in statusReasonHandle it as described under "Failure reason codes" in 5.2
CANCEL_PENDINGA cancellation request was submitted and the carrier has cancelled; waiting for our refund review (not refunded yet)Wait; check cancel with the order info endpoint
CANCELLEDCancelled and refundedβ€”

7.2 Label status labelStatus

#
ValueMeaning
NOT_CREATEDNo label bought yet (draft / processing / failed)
PENDINGThe label was bought, but the file comes later (some services); fetch it later
READYThe label can be fetched
BLOCKED_CANCELLEDBeing cancelled or cancelled; labels are no longer provided

7.3 Tracking status trackingStatus

#
ValueMeaning
PRE_SHIPMENTThe label was bought; the carrier has not picked up the parcel yet
IN_TRANSITIn transit
OUT_FOR_DELIVERYOut for delivery
DELIVEREDDelivered
RETURNEDReturned
EXCEPTIONException
UNKNOWNCannot be determined yet

This API does not provide individual tracking events; it only gives the latest status.

7.4 Cancellation status cancel.status

#
ValueMeaningMoney
PROCESSINGAccepted; cancelling with the carrierNot refunded
PENDING_REVIEWThe carrier has cancelled; waiting for our refund review (order CANCEL_PENDING)Not refunded
APPROVEDApproved and refunded (order CANCELLED); the amount is in refundAmountRefunded
REJECTEDRejected in review (the order goes back to CREATED); the reason is in rejectReasonNot refunded
FAILEDThe cancellation did not succeed (see cancel.code); the order is still CREATEDNot refunded

8. Cancellation and refunds (two-step approval)

#
  1. You call the cancel endpoint β‡’ we cancel the label with the carrier right away.
  2. The carrier cancels it β‡’ the order becomes CANCEL_PENDING, cancel.status = PENDING_REVIEW. No refund has been issued at this point.
  3. We review it:
    • Approved β‡’ refunded; the order is CANCELLED, cancel.status = APPROVED, and the refund amount is in refundAmount.
    • Rejected β‡’ not refunded; the order goes back to CREATED, cancel.status = REJECTED, and the reason is in rejectReason. After a rejection you can request cancellation again.

Key points:

  • The API never replies "cancelled successfully". The best immediate result is PENDING_REVIEW (the carrier has cancelled; waiting for review). A refund happens only after approval.
  • The carrier refuses to cancel (CARRIER_CANCEL_REJECTED, usually because the parcel was already picked up): the order is unchanged, nothing is refunded and cancel.carrierMessage is null; if you need it handled, please contact us with the requestId.
  • The carrier cannot find this label (CARRIER_ORDER_NOT_FOUND) or its answer cannot confirm the cancellation (CARRIER_CANCEL_UNCONFIRMED): we need to check it by hand, so do not submit it again; please contact us with the requestId.
  • Orders being cancelled / cancelled no longer get labels; a label link handed out before the cancellation keeps working at most until its 1-hour validity ends.
  • The customer order number of a cancelled order cannot be reused; to ship again, use a new number.

9. Test keys (sandbox)

#

9.1 How test keys differ from live keys

#
ItemTest key (zsk_test_…)
Base URL, endpoints, fields, error codesExactly the same as with a live key
CarriersNever contacts any carrier
MoneyNever charges, never refunds (the balance does not change); the balance endpoint returns your account's real balance, read-only (see 5.6)
RatesReturns the services really available to your account, but at a test price: 5.00 + 1.00 Γ— total weight (lb) (total weight = the sum of each package's weight Γ— quantity; metric weights are converted from kg to lb; with several packages in one order, each package is priced on its own weight and the prices are added up), rounded up to the cent, the same price for every service. The test price does not reflect real prices; to see real prices, get rates with a live key: getting rates is free
Several packages in one orderThe same as with a live key: split into several test orders, each package with the test price of its own weight; info, labels and cancel by the customer order number act on every package
Order numbersTest order numbers SBX-YYYYMMDD-NNNNNN; test tracking numbers TEST + 16 digits
LabelsA sample PDF with the large text SAMPLE - NOT VALID FOR SHIPPING and the order number printed on it; all three formats url / base64 / merged are supported
Status progressionAdvances automatically over time: PROCESSING for about 5 seconds after acceptance, then CREATED (with ≀ 20 items the endpoint waits out these 5 seconds before replying); after a cancellation, PENDING_REVIEW for about 60 seconds, then automatically APPROVED (order CANCELLED, refundAmount is the test price)
Tracking statusAlways PRE_SHIPMENT
Customer order numbersExactly the same rules as with live keys (Section 3), but unrelated to the numbers under live keys
VisibilityTest orders never appear in the order list, billing or transaction history of the OminiShip dashboard
RetentionTest orders are deleted automatically after 30 days
Listing ordersLists test orders only (never live ones), filtered and sorted by the time each test order was accepted; a cursor does not carry over between test and live keys
Simulated carrier wordsStart with SANDBOX:, for example SANDBOX: simulated carrier response.

9.2 Magic values that trigger error scenarios

#
Scenario to testHow to trigger itResult
Carrier rejects the shipmentSet shipTo.name to SANDBOX_REJECT when creating the orderOrder FAILED / CARRIER_REJECTED
Insufficient balanceA customer order number ending in -NOFUNDS (such as T-1-NOFUNDS)Order FAILED / INSUFFICIENT_BALANCE
Rate above the capSet maxCharge to an amount below the test priceOrder FAILED / PRICE_ABOVE_MAX (statusReason.quotedCharge is the test price)
Delayed labelA customer order number ending in -SLOWLABELFor about 60 seconds after the label is bought, labels return LABEL_NOT_READY
Cancellation rejectedSet reason to SANDBOX_REJECT when cancellingFirst PENDING_REVIEW, then REJECTED after about 60 seconds (the order goes back to CREATED; you can request again)
Carrier refuses to cancelSet reason to SANDBOX_CARRIER_REJECT when cancellingcancel.status = FAILED / CARRIER_CANCEL_REJECTED; the order stays CREATED

Magic values are case-sensitive and must match exactly (leading and trailing spaces are trimmed before comparing). Under a test key, such simulated carrier words start with SANDBOX: (in production, carrierMessage is null when the carrier simply refuses to cancel).


10. Error codes

#

"Retryable" = whether resending the same request unchanged (the same customer order numbers) could succeed.

10.1 Request-level (the reply's code)

#
codeHTTPMeaning and next stepRetryable
OK200The request was processed; for batch endpoints, check results[i].success item by itemNo (success)
INVALID_API_KEY401The key is missing, does not exist or is malformed. Check Authorization: Bearer <key>No
API_KEY_REVOKED401The key has been revoked or has expired; generate a new key in the dashboard under Settings β†’ API KeysNo
API_KEY_LOOKUP_UNAVAILABLE503We cannot verify keys right now (not a problem with your key); retry unchanged shortly, and do not switch keysYes
IMPERSONATION_UNSUPPORTED400The request carries the X-Impersonate-Session request header; remove it and resendNo
RATE_LIMITED429Too many requests this minute; wait data.retryAfter secondsYes
QUOTA_EXCEEDED429Today's (UTC) requests are used up; wait data.retryAfter seconds (resets at UTC midnight)Yes
ACCOUNT_NOT_ENABLED403The account bound to the key is not enabled for this feature; contact usNo
ACCOUNT_DEACTIVATED403The customer account bound to the key has been deactivated (live and test keys alike). A new key will not help; contact us to reactivate the account, and the existing keys work again afterwardsNo
INVALID_REQUEST400The request body is malformed (not a JSON object, missing unitSystem, an empty array and so on); fix it according to data.errorsNo
BATCH_TOO_LARGE400Too many items or packages / orders (data.maxItems, data.maxPackages, and this request's count in data.packages; rates also has data.maxCombinations); split the batchNo
INVALID_CURSOR400The 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 cursorNo
NOT_FOUND404No such path; check the method (POST) and the pathNo
SERVICE_UNAVAILABLE503A temporary failure on our side (it may also be HTTP 500). Resending unchanged is safe; if it keeps happening, contact us with the requestIdYes

10.2 Per item (results[i].code, plus statusReason.code, cancel.code and unavailable[i].code)

#
codeAppears inMeaning and next stepRetryable
OKAllSuccess / acceptedNo (success)
INVALID_IDENTIFIERinfo / labels / cancelThe identifier is not given correctly (0 of the three, more than one, or malformed)No
ORDER_NOT_FOUNDinfo / labels / cancelNo such order (including orders that are not yours)No
AMBIGUOUS_TRACKING_NUMBERinfo / labels / cancelThe 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)No
DUPLICATE_IN_BATCHcreate / info / labels / cancelRepeats an earlier item of the same request; skippedNo
INVALID_ORDERcreateAn order field is invalid (see errors); also one of the failure reasons (see 5.2); also for maxCharge with several packages, or more than 50 packagesNo
INVALID_SHIPMENTratesA field of the rate item is invalid (see errors)No
SERVICE_NOT_AVAILABLErates / createThe service code is not yours, is disabled, or is temporarily unavailable; call the rates endpoint first to confirmNo
SERVICE_CODE_GROUP_NOT_FOUNDrates / createNo 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)No
SERVICE_CODE_GROUP_EMPTYrates / createThere are no usable services in this service code group. Contact us, or use serviceCode insteadNo
RECEIVER_PHONE_INVALIDrates / createThe shipTo.phone of a US recipient address is not exactly 10 digits (no +1, extension, spaces, dashes or parentheses); see errors. Nothing was rated, created or charged; fix it and send it again (create orders may keep the same customer order number; if this customer order number already holds an order β€” a draft from an earlier confirm: false or a failed order β€” its phone cannot be changed, so use a new number)No
NO_RATErates / createThe carrier gave no rate for this package (its own words are in carrierMessage)No
CARRIER_RATE_ERRORrates / createThe carrier's rating service returned an errorYes
RATE_TIMEOUTratesRating this service did not finish in time for this requestYes
PRICE_ABOVE_MAXcreateThe rate is above maxCharge; nothing was bought or charged (the rate is in statusReason.quotedCharge)No
INSUFFICIENT_BALANCEcreateNot enough available balance (balance βˆ’ amounts reserved for orders in progress βˆ’ frozen amounts); nothing was bought or charged; top up or contact us to unfreeze the frozen amount, then resend the same number unchangedYes
CARRIER_REJECTEDcreateThe carrier rejected the shipment (see carrierCode / carrierMessage); nothing was charged; change the content and use a new numberNo
SUBMIT_PAUSEDcreateWe have paused label purchases (maintenance); nothing was chargedYes
PRICE_CHANGEDcreateThe price went up when it was rechecked right before the purchase; nothing was bought or charged; resending the same number unchanged tries again at the current priceYes
SUBMIT_FAILEDcreateThe label could not be bought for a reason on our side, and we are certain that nothing was charged; resend the same number unchangedYes
CUSTOMER_ORDER_NO_CONFLICTcreateThis customer order number already has an order with different content (or an old multi-package order that can no longer be bought); use a new numberNo
CUSTOMER_ORDER_NO_USEDcreateThe order with this customer order number was deleted in the dashboard; use a new numberNo
ACCEPT_TIMEOUTcreateIt could not be accepted in time for this request; resending unchanged is safeYes
LABEL_NOT_READYlabelsThe label is not ready yet (delayed with some services, or the order is still processing)Yes
LABEL_PREPARINGlabelsWe are preparing the fileYes
LABEL_BLOCKED_CANCELLEDlabelsBeing cancelled / cancelled; labels are no longer providedNo
LABEL_UNAVAILABLElabelsThe carrier's label file cannot be fetched right nowYes
LABEL_FORMAT_UNSUPPORTEDlabels (merged)This label format cannot be merged (such as ZPL); fetch it on its own with urlNo
RESPONSE_TOO_LARGElabels (base64)This reply is already full at about 5 MB; request the remaining labels in a separate callYes
ORDER_NOT_SHIPPEDcancel / labels / cancel.codeNo label was bought for the order and nothing was charged (draft or failed), so there is nothing to cancel and no labelNo
ORDER_PROCESSINGcancel / statusReason.code / cancel.codeThe order is still processing; try again laterYes
CANCEL_ALREADY_REQUESTEDcancelAlready under review (a successful item; not refunded yet)No (success)
ALREADY_CANCELLEDcancelAlready cancelled and refunded (a successful item)No (success)
CARRIER_CANCEL_REJECTEDcancel / cancel.codeThe carrier refuses to cancel (usually: already picked up); the order is unchanged and nothing was refunded; carrierMessage is nullNo
CARRIER_ORDER_NOT_FOUNDcancel / cancel.codeThe carrier cannot find this label, so we need to check it by hand; do not submit it again, and contact us with the requestIdNo
CARRIER_CANCEL_UNCONFIRMEDcancel / cancel.codeThe carrier's answer cannot confirm the cancellation, so we need to check it by hand; do not submit it again, and contact us with the requestIdNo
CANCEL_TEMPORARILY_UNAVAILABLEcancel / cancel.codeThe cancellation could not be sent this time, and nothing changed (when it is a configuration issue on our side, the message says to contact us)Yes

11. FAQ

#

Q: The create-orders reply says PROCESSING. Should I resend?
No. PROCESSING means "accepted, the label is being bought"; just check with the order info endpoint every few seconds. If you must resend, resend unchanged with the same customer order number: you only get the same order back. Never switch to a new number, because that buys another label.

Q: The request timed out / the connection dropped, and I do not know whether the order went through. What should I do?
Resend unchanged with exactly the same request body (the same customer order numbers). Orders already created are returned as they are, and orders whose labels were already bought are not charged again.

Q: Could a FAILED order actually have been charged?
No. We only report FAILED when we can confirm "no label was bought and nothing was charged"; anything uncertain always shows as PROCESSING, and we check it automatically.

Q: How do I change an order that has already been submitted?
An order whose label was bought cannot be changed through the API. If you need to, cancel it first (refunded after approval), then place the order again with a new customer order number. Drafts can be edited in the OminiShip dashboard.

Q: How long after cancelling is the refund issued?
Cancellation needs our approval, and the refund is issued only once it is approved. Check cancel.status with the order info endpoint: PENDING_REVIEW means it is waiting for review, and APPROVED means it has been refunded.

Q: Why is labelReady true but labelUrl null?
The order info endpoint only gives a link when the label file is already prepared. Call the labels endpoint directly to get the link.

Q: What if the label link has expired?
Call the labels endpoint again; it gives a new link valid for 1 hour.

Q: Can the same customer order number be used with both a test key and a live key?
Yes; the two are unrelated. Test orders never take up production order numbers.

Q: Why do rates with a test key differ from live ones?
The test price comes from a fixed formula (Section 9) and is only for integration testing. For real prices, get rates with a live key: getting rates is free.

Q: What if a key is lost or leaked?
Revoke it in the dashboard under Settings β†’ API Keys, then generate a new one (see 2.8). We cannot see your full key either, so we cannot recover it for you.

Q: How do I reconcile all of yesterday's orders?
Use the list-orders endpoint (see 5.7): set createdFrom to yesterday at midnight and createdTo to today at midnight (both with your time zone), leave out status, and follow nextCursor until it is null. You get every order created yesterday (including orders placed by hand in the dashboard), each with its status, charge and tracking number.

Q: How do I know whether I have enough money before creating orders?
Call the balance endpoint (see 5.6) and look at available: it is the very figure the create-orders endpoint checks. An order whose required amount (its rate plus the price-change allowance) is not more than it can be bought; several orders at once need their total. The balance can change at any moment, so the create-orders reply is what finally counts.

Q: What should I do about a 5xx or an error I cannot make sense of?
First handle it according to "Retryable"; if it keeps happening, send us the requestId from the reply.


12. Changelog

#
DateVersionChange
2026-10-19v1First release of v1; the earlier beta API has been shut down
2026-10-20v1Keys are now generated, viewed and revoked by you in the OminiShip dashboard under Settings β†’ API Keys (no more requests by email); new section 2.8; endpoints and reply format unchanged
2026-10-27v1Added the English edition of this guide and of the spec, with the same content as the Chinese edition; endpoints and reply format unchanged
2026-10-31v1The rates and create-orders endpoints accept serviceCodeGroup: rate / order by a service code group's name, using the cheapest service in the group (see 5.1); a group rate returns one rate without saying which service it is; new error codes SERVICE_CODE_GROUP_NOT_FOUND and SERVICE_CODE_GROUP_EMPTY; a group order's failed purchase has carrierCode and carrierMessage set to null; requests and replies that only use serviceCode are unchanged
2026-11-04v1One tracking number per package: an order with several packages (quantity counted) is split into several orders when created, each with 1 package, with the customer order number as the group number (see 5.2); rates are given package by package, and with several packages each rate in rates[] carries packageRates; order info, labels and cancel by the customer order number act on the whole group; the order view of a split order carries packageIndex / packageCount; for an order with several packages the balance must cover all of them before anything is bought (otherwise the whole item gets INSUFFICIENT_BALANCE and nothing is created); maxCharge cannot be used yet with several packages in one order; at most 50 packages per shipment; requests and replies with only one package are unchanged
2026-11-14v1Limits now count packages (= orders): create takes at most 500 packages per request in all (quantity counted); order info 100, labels 500 / 20 / 100 and cancel 500 count the orders the identifiers name, and a customer order number 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, with maxPackages and packages added to data; the item limits are unchanged, and requests within the limits and their replies are unchanged
2026-11-16v1Two new read-only endpoints: check your balance POST /v1/balance (balance, reserved, frozen, available amount, credit; see 5.6) and list orders by creation time POST /v1/orders/list (every order, oldest first, page by page, for reconciliation and incremental sync; see 5.7); new error code INVALID_CURSOR; requests and replies of the other endpoints are unchanged
2026-11-18v1When a US recipient 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 with the new error code RECEIVER_PHONE_INVALID (errors[] points at shipTo.phone; nothing is rated, created or charged; see 5.1); creating a draft (confirm: false) and resending a number to get back the order it already has are not affected; sender addresses and non-US recipient addresses are not checked; other requests and replies are unchanged