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 do | Endpoint | Limit per request |
|---|---|---|
| Batch rates | POST /v1/rates | 100 items (and "items Γ services" β€ 200) |
| Batch create orders (by default in one step: create the order + charge + buy the label) | POST /v1/orders/create | 500 items, β€ 500 packages in all (see 5.2) |
| Batch order info (status, price, tracking number, label link, tracking status, cancellation progress) | POST /v1/orders/info | 100 items, β€ 100 orders in all (see 5.3) |
| Batch labels (link / base64 / merged PDF) | POST /v1/orders/labels | 500 / 20 / 100 items, same limits on orders (see 5.4) |
| Batch cancel (submits a cancellation request; refunded after our approval) | POST /v1/orders/cancel | 500 items, β€ 500 orders in all (see 5.5) |
| Check your balance (balance, reserved, frozen, available amount, credit) | POST /v1/balance | None (request body {}, see 5.6) |
| List orders by creation time (reconciliation, incremental sync) | POST /v1/orders/list | 1β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.
- 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.
- First generate a test key (starting with
zsk_test_) for integration testing: it never contacts a carrier and never charges you (see Section 9). - Once it works, generate a live key (starting with
zsk_live_) and switch your system to it to go live; no other code changes. - 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).
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
#- 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 withzsk_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. - 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.
- 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
#| Item | Convention |
|---|---|
| Base URL | https://openapi.ominiship.com (production only; test keys and live keys use the same base URL) |
| Method | All 5 endpoints use POST |
| Request headers | Content-Type: application/json; Authorization: Bearer <key> |
| Paths | Only the 5 paths under /v1/... are open. Any other path (including the old paths of the earlier beta) returns 404 NOT_FOUND |
| Field names | Always 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 iszsk_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_REVOKEDfrom 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-Sessionrequest header (it is rejected: 400IMPERSONATION_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:
theX-Impersonate-Sessionrequest header is present β 400IMPERSONATION_UNSUPPORTEDβ
the key is missing or malformed β 401INVALID_API_KEYβ
we cannot verify keys right now β 503API_KEY_LOOKUP_UNAVAILABLEβ
the key is invalid (does not exist β 401INVALID_API_KEY; revoked or expired β 401API_KEY_REVOKED) β
the customer account is deactivated β 403ACCOUNT_DEACTIVATEDβ
over the rate limit β 429RATE_LIMITED/QUOTA_EXCEEDED.
Only after all of these pass do we check whether the account is enabled for this feature (403ACCOUNT_NOT_ENABLED) and the request body (400INVALID_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"
}| Field | Description |
|---|---|
success | Whether the request as a whole was processed |
code | OK on success; on failure, a request-level error code (Section 10.1) |
message | An English description; on failure it states the next step. It is never "Internal server error" |
data | The endpoint's data; on failure it may carry details (such as errors, maxItems, maxPackages, retryAfter) or be null |
requestId | The 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):
| Situation | What you see | What to do |
|---|---|---|
| Platform-wide per-second protective rate limit | HTTP 429, the body is not an envelope | Wait a few seconds and retry |
| Request timeout (about 30 seconds) | HTTP 504, the body is not an envelope | Resending 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 itself | HTTP 404, the body is not an envelope | Check 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 }
]
}resultsis in the same order as the request array, andindexis the position in the request (starting at 0).- A whole reply of
success: true, code: "OK"only means "the request was processed"; checkresults[i].successitem by item. - Every item has the five keys
index,success,code,messageandretryable.retryable: truemeans "resending this item unchanged may succeed". summary.succeededcounts the items withsuccess: true, including items that were "accepted and are processing".
2.5 Amounts, currency, units and time
#| Item | Convention |
|---|---|
| Amounts | Strings 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 |
| Currency | Every amount comes with "currency": "USD" |
| Units | At 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 |
| Timestamps | ISO 8601 UTC, e.g. 2026-10-19T08:00:00Z |
Ship date shipDate | YYYY-MM-DD; when omitted, the UTC date of the day the order is created |
| Empty optional fields | A field with no value in a reply is always null; the key is always present |
2.6 Rate limits
#| Dimension | Default quota | Reply when exceeded |
|---|---|---|
| Per key per minute (UTC calendar minute) | 60 requests | 429 RATE_LIMITED; data.retryAfter = seconds until the next minute |
| Per key per day (UTC calendar day) | 5000 requests | 429 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_REVOKEDfrom 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).
| Rule | Description |
|---|---|
| Format | 1β64 characters: letters, digits and . _ - / only |
| Case-sensitive, never altered | ref-1 and REF-1 are two different order numbers; leading or trailing spaces make it invalid outright |
| Scope | Unique 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 separate | Order numbers under test keys are unrelated to those under live keys |
| Once used, it belongs to that order forever | Resending the same number only returns that order; it never creates an extra order or charges you again |
| Several packages = several orders | An 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 cancellation | A 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 number | The 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 either | Returns 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 has | This time confirm: false (draft only) | This time confirm: true (default, buy the label) |
|---|---|---|
| None | Creates a new draft | Creates the order and buys the label |
Draft DRAFT | Returns this draft | Same content β buys the label for this draft; different content β CUSTOMER_ORDER_NO_CONFLICT (nothing changed, no label bought) |
Processing PROCESSING | Returns its current state | Returns its current state; it is not queued again |
Label bought CREATED | Returns this order | Returns this order; you are not charged again (the content is not compared) |
Failed FAILED | Returns the failure reason | Same content β retries buying the label once with the original content (same number); different content β CUSTOMER_ORDER_NO_CONFLICT |
Being cancelled CANCEL_PENDING / cancelled CANCELLED | Returns this order | Returns this order (it cannot be reused; to ship again, use a new number) |
| Deleted in the dashboard | CUSTOMER_ORDER_NO_USED | CUSTOMER_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):
| Field | What it is | Notes |
|---|---|---|
customerOrderNo | Your customer order number | Recommended: can be looked up right away and is unique |
orderNo | The 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 |
trackingNumber | The carrier's tracking number | May 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
| Field | Type | Required | Description |
|---|---|---|---|
unitSystem | string | Yes | imperial / metric |
shipments | array | Yes | 1β100 items |
shipments[].ref | string | No | β€ 64 characters; echoed back unchanged so you can match the results |
shipments[].serviceCode | string | No | Rate only this service; use either this or serviceCodeGroup; leave both out = rate every service you can use |
shipments[].serviceCodeGroup | string | No | The 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 / shipTo | object | Yes | Address, see 6.1 |
shipments[].packages | array | Yes | Packages, 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
| Field | Description |
|---|---|
index / success / code / message / retryable | See 2.4 |
ref | The 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'scodeis 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
serviceCodeis not yours / is disabled β that item getsSERVICE_NOT_AVAILABLE. The specifiedserviceCodeGroupis 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.countryempty / US / USA) whoseshipTo.phoneis filled in but is not exactly 10 digits (no+1, extension, spaces, dashes or parentheses) β that item getsRECEIVER_PHONE_INVALID, witherrors[]pointing atshipments[i].shipTo.phone(no carrier is asked). serviceCodeis 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/servicearenull); when no service in the group returns a rate,unavailable[]has exactly one entry, whoseserviceCodeandcarrierMessagearenull. To order, put the same group name inserviceCodeGroupof the create-orders endpoint (see 5.2). carrierexamples:ups,usps,fedex;serviceexamples:ups_ground,usps_ground_advantage,fedex_ground.- Several packages (
quantitycounted) 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 tounavailable[], with amessagestartingPackage k:that says which package got no rate. At most 50 packages per shipment (quantitycounted); more β that item getsINVALID_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
| Field | Type | Required | Description |
|---|---|---|---|
unitSystem | string | Yes | imperial / metric |
confirm | boolean | No | Default 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) |
orders | array | Yes | 1β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[].customerOrderNo | string | Yes | Customer order number, see Section 3 |
orders[].serviceCode | string | Either | The service code from the rates endpoint, passed back unchanged (β€ 128 characters); give exactly one of this and serviceCodeGroup |
orders[].serviceCodeGroup | string | Either | The 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[].shipDate | string | No | YYYY-MM-DD; when omitted, the UTC date of the day the order is created |
orders[].maxCharge | string | No | An 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 / shipTo | object | Yes | Address, see 6.1 |
orders[].packages | array | Yes | Packages, see 6.2; several packages (quantity counted) are split into several orders, see "Several packages in one order" below |
orders[].references | object | No | { "reference1": "β¦", "reference2": "β¦" }, each β€ 50 characters; stored on the order, and printed on the label when the carrier supports it |
How it is processed
- 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: trueare then rated and get their labels bought in the background. - 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 (
CREATEDorFAILED); those without an outcome yet arePROCESSING. With more than 20, it replies immediately. - Items that are
PROCESSINGhavesuccess: true(accepted, not failed); poll them with the order info endpoint and do not resend with a new number. - Items not yet accepted when time runs out return
ACCEPT_TIMEOUT(retryable; resending unchanged is safe).
About prices
maxChargecaps 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:maxChargeis 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) }.codeisOK; when the order isFAILED,codeis the failure reason code andsuccess: false. - Refused (nothing was created for this item this time and nothing was charged):
{ index, success: false, code, message, retryable, customerOrderNo, errors? };codecan be:
| code | Meaning | Next step |
|---|---|---|
INVALID_ORDER | A 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_BATCH | The customer order number repeats within the same request | Keep only one |
SERVICE_NOT_AVAILABLE | The service code is not yours or is disabled | Call the rates endpoint first to confirm the services you can use |
SERVICE_CODE_GROUP_NOT_FOUND | Your 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_EMPTY | This service code group has no service you can use right now | Contact us, or use serviceCode instead |
RECEIVER_PHONE_INVALID | The 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_CONFLICT | This 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_USED | The order with this number was deleted in the dashboard | Use a new number |
ACCEPT_TIMEOUT | It could not be accepted in time for this request | Resend unchanged |
Note the difference: an
INVALID_ORDERfrom 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 (orderFAILED, reasonINVALID_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):
| Reason | Description | Next step |
|---|---|---|
INSUFFICIENT_BALANCE | Not 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_MAX | The rate is above maxCharge; the rate at that time is in statusReason.quotedCharge | To accept the new price, use a new number and raise maxCharge |
PRICE_CHANGED | The price went up when it was rechecked right before the purchase | Resend the same number unchanged |
CARRIER_REJECTED | The carrier rejected the shipment, see statusReason.carrierCode / carrierMessage | Change the content and use a new number |
NO_RATE | The carrier gave no rate for this package | Change the service or the packages (with a new number) |
CARRIER_RATE_ERROR | The carrier's rating service returned an error | Resend the same number unchanged |
SERVICE_NOT_AVAILABLE | The 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_FOUND | The service code group was deleted before the purchase | Use another group or serviceCode (with a new number) |
SERVICE_CODE_GROUP_EMPTY | The group no longer had a service you can use at the time of the purchase | Contact us, or use serviceCode (with a new number) |
INVALID_ORDER | The order data was not accepted | Change the content and use a new number |
SUBMIT_PAUSED | We have paused label purchases (maintenance) | Resend the same number unchanged later |
SUBMIT_FAILED | The 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 (
quantitycounted; for example one package withquantity: 2plus 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) andorders[](one entry per package, in package order:packageIndex+ that order'ssuccess/code/message/retryable/replayed+ all order view fields). The item'scode: the code all packages share, if they do; otherwiseOKwhen every package succeeded, else the code of the first package that did not. - When refused (
INVALID_ORDER,CUSTOMER_ORDER_NO_CONFLICTand 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
confirmis 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 getsINSUFFICIENT_BALANCE, itsmessagesays how much is missing, it carriesrequired(the amount needed) andshortfall(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 (codeis that package's rate code,messagestarts withPackage 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. maxChargecannot be used yet with several packages in one order (that item getsINVALID_ORDER); to cap the price, send each package as its own order, each with its own customer order number andmaxCharge.- 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
orderNoortrackingNumberthey 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(withorderNos) /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
packageCountandorders[](one entry per package:packageIndex+success/code/message/retryable+ all order view fields); a package that cannot be found isORDER_NOT_FOUNDin its entry. ByorderNo/trackingNumberyou get only that one order, whose order view also carriespackageIndex/packageCount(6.3). Asking for the group and for one of its orders in the same request β the later item getsDUPLICATE_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 (
customerOrderNoisnull; look them up by OminiShip order number or tracking number). - The carrier is not queried in real time:
trackingStatusis the latest tracking status we have stored, andtrackingUpdatedAtis when it was updated. labelUrlis given only when the label file is already prepared; whenlabelReady: truebutlabelUrlisnull, 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
orderNosfield.
5.4 Batch labels POST /v1/orders/labels
#Request
| Field | Type | Required | Description |
|---|---|---|---|
format | string | No | url (default) / base64 / merged |
orders | array | Yes | One 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
| format | Fields of each successful item | Description |
|---|---|---|
url | fileType, labelUrl, expiresAt | Our download link, valid for 1 hour; after it expires, call this endpoint again for a new link |
base64 | fileType, contentBase64 | One 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 |
merged | merged: true | All 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,orderNoandtrackingNumber. fileType:PDF,PNG,JPEG, or another format exactly as the carrier gives it (such asZPL);UNKNOWNwhen 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_READYis returned (retryable). An order that is still processing also returnsLABEL_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
| Field | Type | Required | Description |
|---|---|---|---|
orders | array | Yes | 1β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[].reason | string | No | Cancellation 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 status | Result 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 progress | OK, 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 / FAILED | ORDER_NOT_SHIPPED: no label was bought and nothing was charged, so there is nothing to cancel (drafts can be deleted in the dashboard) |
PROCESSING | ORDER_PROCESSING (retryable): the label is still being bought; try again later |
| Could not be sent this time | CANCEL_TEMPORARILY_UNAVAILABLE (retryable): nothing changed; resend later |
| Identifier problem | INVALID_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):
| Field | Type | Description |
|---|---|---|
currency | string | Always USD |
balance | string | Your balance; negative while you are using a credit |
reserved | string | Reserved for orders: money held for orders whose labels are being bought; once the purchase finishes it becomes a charge or is released |
frozen | string | Frozen amount: frozen by us; only we can unfreeze it |
available | string | What you can spend on new orders right now = balance β reserved β frozen + credit (with a credit, plus credit.limit) |
credit | object | null | Your 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:
availableis the very same figure the create-orders endpoint checks: an order whose required amount (its rate plus the price-change allowance) is not more thanavailablecan be bought; more than that isINSUFFICIENT_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
| Field | Type | Required | Description |
|---|---|---|---|
createdFrom | string | Yes | Start 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 |
createdTo | string | Yes | End time (exclusive), same format; must be later than createdFrom, and the two may be at most 31 days apart |
status | string[] | No | List only orders in these statuses (for the values see 7.1), such as ["CREATED", "CANCELLED"]; omitted = every status |
limit | integer | No | At most this many orders per page, 1β100, default 50 |
cursor | string | No | nextCursor 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 }
| Field | Description |
|---|---|
orders | The 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) |
nextCursor | A string when there may be another page: put it unchanged into the next request's cursor; null when there is nothing more |
query | The 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 asnextCursoris notnull, keep paging. With astatusfilter 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 thanlimit. - 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);
labelUrlis given only when the label file is already prepared. - A
cursorworks only for the same customer account, the same kind of key (live / test) and the samecreatedFrom/createdTo/status(limitmay change); otherwise the whole request gets 400INVALID_CURSORand nothing is read. To start over, omitcursor. - 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)
#| Field | Type | Required | Limits / description |
|---|---|---|---|
name | string | Yes | β€ 100 |
company | string | No | β€ 100 |
phone | string | No | β€ 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 |
email | string | No | β€ 100 |
address1 | string | Yes | β€ 100 |
address2 | string | No | β€ 100 |
city | string | Yes | β€ 60 |
state | string | Yes | β€ 30; for a US address, it must be the 2-letter state code (such as CA); converted to upper case |
postalCode | string | Yes | β€ 20; for a US address, it must be 12345 or 12345-6789 |
country | string | No | 2-letter country code, default US, converted to upper case |
residential | boolean | No | Whether 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.
| Field | Type | Required | Limits |
|---|---|---|---|
weight | number | Yes | Weight of a single piece, > 0 and β€ 2000 |
length / width / height | number | Yes | > 0 and β€ 500 |
quantity | integer | No | Number 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):
| Field | Type | Description |
|---|---|---|
customerOrderNo | string | null | Customer order number; null for orders placed by hand in the dashboard |
orderNo | string | null | OminiShip order number ORD-β¦ (SBX-β¦ for test orders) |
status | string | Order status, see 7.1 |
statusReason | object | null | Has a value only for FAILED / PROCESSING, see 6.4 |
serviceCode | string | null | Given only for orders created through this API with a serviceCode; null for orders created in the dashboard or with a service code group |
carrier | string | null | Carrier, such as usps; null until the label is bought for an order created with a service code group |
service | string | null | Carrier service, such as usps_ground_advantage; null until the label is bought for an order created with a service code group |
totalCharge | string | null | Amount charged; has a value only for CREATED / CANCEL_PENDING / CANCELLED |
currency | string | Always USD |
trackingNumber | string | null | Tracking number; has a value only for CREATED / CANCEL_PENDING / CANCELLED |
labelReady | boolean | Whether the label can be fetched now |
labelStatus | string | Label status, see 7.2 |
labelUrl | string | null | Label link (valid for 1 hour), given only when the label file is prepared; otherwise fetch it with the labels endpoint |
labelUrlExpiresAt | string | null | When the link above expires |
trackingStatus | string | null | Tracking status, see 7.3; null before the label is bought |
trackingUpdatedAt | string | null | When we last updated the tracking status |
cancel | object | null | Cancellation progress, see 6.5; null if a cancellation was never requested |
createdAt | string | null | When the order was created |
submittedAt | string | null | When 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:
| Field | Description |
|---|---|
code | ORDER_PROCESSING for PROCESSING; for FAILED, the failure reason code (see 5.2, "Failure reason codes") |
message | English description and next step |
carrierCode | Has 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) |
carrierMessage | The 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 |
quotedCharge | Only 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:
| Field | Description |
|---|---|
status | Cancellation status, see 7.4 |
code | Has a value only for FAILED: CARRIER_CANCEL_REJECTED / CARRIER_ORDER_NOT_FOUND / CARRIER_CANCEL_UNCONFIRMED / CANCEL_TEMPORARILY_UNAVAILABLE / ORDER_NOT_SHIPPED / ORDER_PROCESSING |
message | English description and next step |
carrierMessage | The 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" |
requestedAt | When it was requested |
reviewedAt | When it was reviewed (APPROVED / REJECTED) |
refundAmount | Only for APPROVED: the refund amount (a string) |
currency | Always USD |
rejectReason | Only 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:
| Field | Description |
|---|---|
field | Full JSON path, such as orders[1].shipTo.postalCode |
code | REQUIRED (missing) / INVALID_TYPE (wrong type) / INVALID_VALUE (wrong value) / TOO_LONG (too long) / OUT_OF_RANGE (out of range) |
message | English description (never echoes the value you sent) |
7. Statuses
#7.1 Order status status
#| Value | Meaning | What you should do |
|---|---|---|
DRAFT | Draft: 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 |
PROCESSING | Processing: accepted and the label is being bought, or we are automatically checking an order whose outcome is not yet confirmed. Not a failure | Poll with the order info endpoint; do not resend with a new number |
CREATED | Label bought and charged | Fetch the label |
FAILED | A definite failure: no label was bought and nothing was charged; the reason is in statusReason | Handle it as described under "Failure reason codes" in 5.2 |
CANCEL_PENDING | A 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 |
CANCELLED | Cancelled and refunded | β |
7.2 Label status labelStatus
#| Value | Meaning |
|---|---|
NOT_CREATED | No label bought yet (draft / processing / failed) |
PENDING | The label was bought, but the file comes later (some services); fetch it later |
READY | The label can be fetched |
BLOCKED_CANCELLED | Being cancelled or cancelled; labels are no longer provided |
7.3 Tracking status trackingStatus
#| Value | Meaning |
|---|---|
PRE_SHIPMENT | The label was bought; the carrier has not picked up the parcel yet |
IN_TRANSIT | In transit |
OUT_FOR_DELIVERY | Out for delivery |
DELIVERED | Delivered |
RETURNED | Returned |
EXCEPTION | Exception |
UNKNOWN | Cannot be determined yet |
This API does not provide individual tracking events; it only gives the latest status.
7.4 Cancellation status cancel.status
#| Value | Meaning | Money |
|---|---|---|
PROCESSING | Accepted; cancelling with the carrier | Not refunded |
PENDING_REVIEW | The carrier has cancelled; waiting for our refund review (order CANCEL_PENDING) | Not refunded |
APPROVED | Approved and refunded (order CANCELLED); the amount is in refundAmount | Refunded |
REJECTED | Rejected in review (the order goes back to CREATED); the reason is in rejectReason | Not refunded |
FAILED | The cancellation did not succeed (see cancel.code); the order is still CREATED | Not refunded |
8. Cancellation and refunds (two-step approval)
#- You call the cancel endpoint β we cancel the label with the carrier right away.
- The carrier cancels it β the order becomes
CANCEL_PENDING,cancel.status = PENDING_REVIEW. No refund has been issued at this point. - We review it:
- Approved β refunded; the order is
CANCELLED,cancel.status = APPROVED, and the refund amount is inrefundAmount. - Rejected β not refunded; the order goes back to
CREATED,cancel.status = REJECTED, and the reason is inrejectReason. After a rejection you can request cancellation again.
- Approved β refunded; the order is
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 andcancel.carrierMessageisnull; if you need it handled, please contact us with therequestId. - 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 therequestId. - 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
#| Item | Test key (zsk_test_β¦) |
|---|---|
| Base URL, endpoints, fields, error codes | Exactly the same as with a live key |
| Carriers | Never contacts any carrier |
| Money | Never charges, never refunds (the balance does not change); the balance endpoint returns your account's real balance, read-only (see 5.6) |
| Rates | Returns 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 order | The 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 numbers | Test order numbers SBX-YYYYMMDD-NNNNNN; test tracking numbers TEST + 16 digits |
| Labels | A 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 progression | Advances 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 status | Always PRE_SHIPMENT |
| Customer order numbers | Exactly the same rules as with live keys (Section 3), but unrelated to the numbers under live keys |
| Visibility | Test orders never appear in the order list, billing or transaction history of the OminiShip dashboard |
| Retention | Test orders are deleted automatically after 30 days |
| Listing orders | Lists 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 words | Start with SANDBOX:, for example SANDBOX: simulated carrier response. |
9.2 Magic values that trigger error scenarios
#| Scenario to test | How to trigger it | Result |
|---|---|---|
| Carrier rejects the shipment | Set shipTo.name to SANDBOX_REJECT when creating the order | Order FAILED / CARRIER_REJECTED |
| Insufficient balance | A customer order number ending in -NOFUNDS (such as T-1-NOFUNDS) | Order FAILED / INSUFFICIENT_BALANCE |
| Rate above the cap | Set maxCharge to an amount below the test price | Order FAILED / PRICE_ABOVE_MAX (statusReason.quotedCharge is the test price) |
| Delayed label | A customer order number ending in -SLOWLABEL | For about 60 seconds after the label is bought, labels return LABEL_NOT_READY |
| Cancellation rejected | Set reason to SANDBOX_REJECT when cancelling | First PENDING_REVIEW, then REJECTED after about 60 seconds (the order goes back to CREATED; you can request again) |
| Carrier refuses to cancel | Set reason to SANDBOX_CARRIER_REJECT when cancelling | cancel.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)
#| code | HTTP | Meaning and next step | Retryable |
|---|---|---|---|
OK | 200 | The request was processed; for batch endpoints, check results[i].success item by item | No (success) |
INVALID_API_KEY | 401 | The key is missing, does not exist or is malformed. Check Authorization: Bearer <key> | No |
API_KEY_REVOKED | 401 | The key has been revoked or has expired; generate a new key in the dashboard under Settings β API Keys | No |
API_KEY_LOOKUP_UNAVAILABLE | 503 | We cannot verify keys right now (not a problem with your key); retry unchanged shortly, and do not switch keys | Yes |
IMPERSONATION_UNSUPPORTED | 400 | The request carries the X-Impersonate-Session request header; remove it and resend | No |
RATE_LIMITED | 429 | Too many requests this minute; wait data.retryAfter seconds | Yes |
QUOTA_EXCEEDED | 429 | Today's (UTC) requests are used up; wait data.retryAfter seconds (resets at UTC midnight) | Yes |
ACCOUNT_NOT_ENABLED | 403 | The account bound to the key is not enabled for this feature; contact us | No |
ACCOUNT_DEACTIVATED | 403 | The 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 afterwards | No |
INVALID_REQUEST | 400 | The request body is malformed (not a JSON object, missing unitSystem, an empty array and so on); fix it according to data.errors | No |
BATCH_TOO_LARGE | 400 | Too many items or packages / orders (data.maxItems, data.maxPackages, and this request's count in data.packages; rates also has data.maxCombinations); split the batch | No |
INVALID_CURSOR | 400 | 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 | No |
NOT_FOUND | 404 | No such path; check the method (POST) and the path | No |
SERVICE_UNAVAILABLE | 503 | A temporary failure on our side (it may also be HTTP 500). Resending unchanged is safe; if it keeps happening, contact us with the requestId | Yes |
10.2 Per item (results[i].code, plus statusReason.code, cancel.code and unavailable[i].code)
#| code | Appears in | Meaning and next step | Retryable |
|---|---|---|---|
OK | All | Success / accepted | No (success) |
INVALID_IDENTIFIER | info / labels / cancel | The identifier is not given correctly (0 of the three, more than one, or malformed) | No |
ORDER_NOT_FOUND | info / labels / cancel | No such order (including orders that are not yours) | No |
AMBIGUOUS_TRACKING_NUMBER | info / labels / cancel | The 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_BATCH | create / info / labels / cancel | Repeats an earlier item of the same request; skipped | No |
INVALID_ORDER | create | An 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 packages | No |
INVALID_SHIPMENT | rates | A field of the rate item is invalid (see errors) | No |
SERVICE_NOT_AVAILABLE | rates / create | The service code is not yours, is disabled, or is temporarily unavailable; call the rates endpoint first to confirm | No |
SERVICE_CODE_GROUP_NOT_FOUND | rates / create | 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) | No |
SERVICE_CODE_GROUP_EMPTY | rates / create | There are no usable services in this service code group. Contact us, or use serviceCode instead | No |
RECEIVER_PHONE_INVALID | rates / create | The 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_RATE | rates / create | The carrier gave no rate for this package (its own words are in carrierMessage) | No |
CARRIER_RATE_ERROR | rates / create | The carrier's rating service returned an error | Yes |
RATE_TIMEOUT | rates | Rating this service did not finish in time for this request | Yes |
PRICE_ABOVE_MAX | create | The rate is above maxCharge; nothing was bought or charged (the rate is in statusReason.quotedCharge) | No |
INSUFFICIENT_BALANCE | create | Not 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 unchanged | Yes |
CARRIER_REJECTED | create | The carrier rejected the shipment (see carrierCode / carrierMessage); nothing was charged; change the content and use a new number | No |
SUBMIT_PAUSED | create | We have paused label purchases (maintenance); nothing was charged | Yes |
PRICE_CHANGED | create | The 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 price | Yes |
SUBMIT_FAILED | create | The label could not be bought for a reason on our side, and we are certain that nothing was charged; resend the same number unchanged | Yes |
CUSTOMER_ORDER_NO_CONFLICT | create | This 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 number | No |
CUSTOMER_ORDER_NO_USED | create | The order with this customer order number was deleted in the dashboard; use a new number | No |
ACCEPT_TIMEOUT | create | It could not be accepted in time for this request; resending unchanged is safe | Yes |
LABEL_NOT_READY | labels | The label is not ready yet (delayed with some services, or the order is still processing) | Yes |
LABEL_PREPARING | labels | We are preparing the file | Yes |
LABEL_BLOCKED_CANCELLED | labels | Being cancelled / cancelled; labels are no longer provided | No |
LABEL_UNAVAILABLE | labels | The carrier's label file cannot be fetched right now | Yes |
LABEL_FORMAT_UNSUPPORTED | labels (merged) | This label format cannot be merged (such as ZPL); fetch it on its own with url | No |
RESPONSE_TOO_LARGE | labels (base64) | This reply is already full at about 5 MB; request the remaining labels in a separate call | Yes |
ORDER_NOT_SHIPPED | cancel / labels / cancel.code | No label was bought for the order and nothing was charged (draft or failed), so there is nothing to cancel and no label | No |
ORDER_PROCESSING | cancel / statusReason.code / cancel.code | The order is still processing; try again later | Yes |
CANCEL_ALREADY_REQUESTED | cancel | Already under review (a successful item; not refunded yet) | No (success) |
ALREADY_CANCELLED | cancel | Already cancelled and refunded (a successful item) | No (success) |
CARRIER_CANCEL_REJECTED | cancel / cancel.code | The carrier refuses to cancel (usually: already picked up); the order is unchanged and nothing was refunded; carrierMessage is null | No |
CARRIER_ORDER_NOT_FOUND | cancel / cancel.code | The carrier cannot find this label, so we need to check it by hand; do not submit it again, and contact us with the requestId | No |
CARRIER_CANCEL_UNCONFIRMED | cancel / cancel.code | The 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 requestId | No |
CANCEL_TEMPORARILY_UNAVAILABLE | cancel / cancel.code | The 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
#| Date | Version | Change |
|---|---|---|
| 2026-10-19 | v1 | First release of v1; the earlier beta API has been shut down |
| 2026-10-20 | v1 | Keys 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-27 | v1 | Added 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-31 | v1 | The 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-04 | v1 | One 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-14 | v1 | Limits 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-16 | v1 | Two 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-18 | v1 | When 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 |