OAuth2 grant type: client_credentials (channel code + secret) or password (OMS account + password). May be omitted: if username is given it is treated as password, otherwise client_credentials.
client_id
string
Channel code (the OAuth2 client_id), issued by your account manager; for the client_credentials grant. Use sandbox to try things out.
max length 32 · format ^[A-Za-z0-9_-]+$
client_secret
string
Channel secret (the OAuth2 client_secret); for the client_credentials grant. Use sandbox to try things out (the sandbox returns demo data and never touches real stock).
max length 256
username
string
Your OMS website login account (password grant), e.g. 100470admin; we recommend a dedicated sub-account for system integration. Use sandbox to try things out.
max length 64
password
string
Your OMS login password (password grant). Only handled at token exchange — the gateway never stores or logs it. Use sandbox to try things out.
max length 256
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Auth
Who this token is: account, channel, usable warehouses, permissions, business switches (OMS profile for OMS logins; warehouse allowlist and gateway scopes for channel-secret tokens)
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Warehouses & stock
Stock in one warehouse: no filter = whole warehouse (page / page_size; X-Stock-Version header for incremental sync); sku= one variant; product_code= all variants of a style
Warehouse code: AU (Australia, all warehouses — aggregate view), AUSYD2 (Sydney main, Rosehill), AUSYD1 (Sydney accessories), CN (China, all warehouses — aggregate view), CHNZJ1 (Zhenjiang). Full list: GET /api/v1/warehouses.
Query parameters
Name
Type
Description
sku
string
SKU / barcode — the colour + size level, e.g. OB0021611. For the whole style use product_code instead.
max length 64 · format ^[A-Za-z0-9_./-]+$
product_code
string
Style code — one style (every colour / size variant), e.g. OB002. For a single variant use sku. When querying prices, several can be comma-separated.
max length 64 · format ^[A-Za-z0-9_./-]+$
page
number
Page number, from 1 (optional). Whole-warehouse stock returns everything when omitted — 30,000+ rows, paging recommended.
min 1
page_size
number
Rows per page (optional), max 2000.
1–2000
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
A full pull is about 7.2 MB and 60 points. Use /Changes for day-to-day sync; pull the full warehouse only the first time or when the cursor is stale (full=true).
GET/api/v1/warehouses/{warehouse_code}/stock/changesToken requiredstock:readCharged per row returned
Stock changes (incremental). Pass since=the last version; while has_more=true call again with the new version. needs_full_sync=true means since is too old — do one full pull
Path parameters
Name
Type
Description
warehouse_coderequired
string
Warehouse code: AU (Australia, all warehouses — aggregate view), AUSYD2 (Sydney main, Rosehill), AUSYD1 (Sydney accessories), CN (China, all warehouses — aggregate view), CHNZJ1 (Zhenjiang). Full list: GET /api/v1/warehouses.
Query parameters
Name
Type
Description
since
number
The version you received last time. Pass 0 on the first sync (you will get needs_full_sync=true, meaning do one full pull first).
min 0
limit
number
Max changes returned this call (optional, default 1000, max 5000). Soft limit: changes in one version are never split, so you may get slightly more.
1–5000
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Rate limiting charges by rows actually returned: 1 point per call while you are up to date; catching up after a long gap is charged by the rows you pull. A full warehouse pull is a flat 60 points.
Products
Products in one warehouse (deduplicated by style code, with prices)
Warehouse code: AU (Australia, all warehouses — aggregate view), AUSYD2 (Sydney main, Rosehill), AUSYD1 (Sydney accessories), CN (China, all warehouses — aggregate view), CHNZJ1 (Zhenjiang). Full list: GET /api/v1/warehouses.
search
string
Search keyword (optional); fuzzy match on style code or product name.
max length 128
business_type
string
Business type (optional): wholesale or dropship. Omitted = both.
page
number
Page number, from 1 (optional). Whole-warehouse stock returns everything when omitted — 30,000+ rows, paging recommended.
min 1
page_size
number
Rows per page (optional), max 2000.
1–2000
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Products
Product detail by style code (images / description / prices + all variants; Chinese name / weight / materials not yet fed from upstream, present only when set)
Style code — one style (every colour / size variant), e.g. OB002. For a single variant use sku. When querying prices, several can be comma-separated.
max length 64 · format ^[A-Za-z0-9_./-]+$
Query parameters
Name
Type
Description
warehouse_code
string
Warehouse code: AU (Australia, all warehouses — aggregate view), AUSYD2 (Sydney main, Rosehill), AUSYD1 (Sydney accessories), CN (China, all warehouses — aggregate view), CHNZJ1 (Zhenjiang). Full list: GET /api/v1/warehouses.
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
SKU / barcode — the colour + size level, e.g. OB0021611. For the whole style use product_code instead.
max length 64 · format ^[A-Za-z0-9_./-]+$
Query parameters
Name
Type
Description
warehouse_code
string
Warehouse code: AU (Australia, all warehouses — aggregate view), AUSYD2 (Sydney main, Rosehill), AUSYD1 (Sydney accessories), CN (China, all warehouses — aggregate view), CHNZJ1 (Zhenjiang). Full list: GET /api/v1/warehouses.
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Warehouse code: AU (Australia, all warehouses — aggregate view), AUSYD2 (Sydney main, Rosehill), AUSYD1 (Sydney accessories), CN (China, all warehouses — aggregate view), CHNZJ1 (Zhenjiang). Full list: GET /api/v1/warehouses.
search
string
Search keyword (optional); fuzzy match on style code or product name.
max length 128
business_type
string
Business type (optional): wholesale or dropship. Omitted = both.
page
number
Page number, from 1 (optional). Whole-warehouse stock returns everything when omitted — 30,000+ rows, paging recommended.
min 1
page_size
number
Rows per page (optional), max 2000.
1–2000
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Prices
Your channel's product prices (paged; product_code may be comma-separated)
Warehouse code: AU (Australia, all warehouses — aggregate view), AUSYD2 (Sydney main, Rosehill), AUSYD1 (Sydney accessories), CN (China, all warehouses — aggregate view), CHNZJ1 (Zhenjiang). Full list: GET /api/v1/warehouses.
product_code
string
Style code — one style (every colour / size variant), e.g. OB002. For a single variant use sku. When querying prices, several can be comma-separated.
max length 4096
search
string
Search keyword (optional); fuzzy match on style code or product name.
max length 128
page
number
Page number, from 1 (optional). Whole-warehouse stock returns everything when omitted — 30,000+ rows, paging recommended.
min 1
page_size
number
Rows per page (optional), max 2000.
1–2000
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Shipping methods available to your account. Put shipping_method_id into shipping when creating a wholesale order
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Carriers your account can choose from. carrier_id is optional on a wholesale order
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Your OMS delivery address book. Put address_id into shipping when creating a wholesale order
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Wholesale orders
Create a wholesale order (draft by default; auto_confirm=true submits for review)
Warehouse code: AU (Australia, all warehouses — aggregate view), AUSYD2 (Sydney main, Rosehill), AUSYD1 (Sydney accessories), CN (China, all warehouses — aggregate view), CHNZJ1 (Zhenjiang). Full list: GET /api/v1/warehouses.
linesrequired
array<object>
Line array, each { sku, quantity }. At least one; quantity=0 removes the line when adjusting a reservation.
1–1000
lines[].skurequired
string
SKU / barcode — the colour + size level, e.g. OB0021611. For the whole style use product_code instead.
max length 64
lines[].quantityrequired
integer
Quantity, a positive integer, e.g. 2. In reservation adjustments / carts, 0 removes the line.
0–99999
note
string
Remark (optional, up to 500 characters).
max length 500
client_order_number
string
The order number in your own system (the one you sent when creating the drop-ship order).
max length 64
auto_confirm
boolean
Submit immediately (optional). Omitted = draft only, someone confirms it in the ERP before it takes effect — this default is intentional. A submitted drop-ship order is allocated at once and can no longer be edited.
shipping
object
Shipping info (required when placing a wholesale order signed in with an OMS account). Inside: shipping_method_id (see GET /api/v1/shipping-methods), address_id (see GET /api/v1/addresses), carrier_id (optional), pickup_at (only for pickup). Omit the whole object to use the defaults set on your OMS account; if none are set you get an error pointing here.
shipping.shipping_method_id
string
Shipping method id, from GET /api/v1/shipping-methods.
max length 64
shipping.carrier_id
string
Carrier id (optional), from GET /api/v1/carriers.
max length 64
shipping.address_id
string
Delivery address id, from GET /api/v1/addresses. The address book is maintained on the OMS site under User → Preferences.
max length 64
shipping.pickup_at
string
Pickup time (optional, only for the pickup method), e.g. 2026-09-10T14:00:00.
max length 32
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Send an Idempotency-Key header (any unique string, e.g. a UUID) on writes: a network retry never creates a second order. Orders are drafts by default until a person confirms them in the ERP.
Wholesale orders
Your channel's wholesale orders within a date range
max length 10 · format ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
end_daterequired
string
End date, YYYY-MM-DD (inclusive).
max length 10 · format ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
status
string
逗号分隔：draft / confirmed / cancelled
max length 128 · format ^[A-Za-z0-9,\s_-]*$
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Wholesale order id, from the order list. Own channel only.
max length 64
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Wholesale orders
Void the wholesale order and release the stock it was holding
Void the wholesale order and release the stock it was holding. Orders already shipped cannot be voided
Path parameters
Name
Type
Description
order_idrequired
string
Wholesale order id, from the order list. Own channel only.
max length 64
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Send an Idempotency-Key header (any unique string, e.g. a UUID) on writes: a network retry never creates a second order. Orders are drafts by default until a person confirms them in the ERP.
Wholesale orders
Allocation preview: per line, how much can be allocated, how much is owed, when pre-sale stock arrives, the amount payable and whether the balance covers it
Allocation preview: per line, how much can be allocated, how much is owed, when pre-sale stock arrives, the amount payable and whether the balance covers it. Note: the preview holds stock — submit or cancel afterwards
Path parameters
Name
Type
Description
order_idrequired
string
Wholesale order id, from the order list. Own channel only.
max length 64
Request body (JSON)
Field
Type
Description
use_reservation
boolean
Whether to draw on your reserved (locked) stock for this allocation. Omit = do not use it.
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Send an Idempotency-Key header (any unique string, e.g. a UUID) on writes: a network retry never creates a second order. Orders are drafts by default until a person confirms them in the ERP.
Wholesale orders
Submit the wholesale order (lines can no longer be changed)
Submit the wholesale order (lines can no longer be changed). payment_method defaults to invoice (pay on invoice)
Path parameters
Name
Type
Description
order_idrequired
string
Wholesale order id, from the order list. Own channel only.
max length 64
Request body (JSON)
Field
Type
Description
payment_method
string
How to pay: balance / invoice (pay on invoice) / wechat / alipay. Defaults to invoice, i.e. monthly settlement.
use_reservation
boolean
Whether to draw on your reserved (locked) stock for this allocation. Omit = do not use it.
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Send an Idempotency-Key header (any unique string, e.g. a UUID) on writes: a network retry never creates a second order. Orders are drafts by default until a person confirms them in the ERP.
Warehouse code: AU (Australia, all warehouses — aggregate view), AUSYD2 (Sydney main, Rosehill), AUSYD1 (Sydney accessories), CN (China, all warehouses — aggregate view), CHNZJ1 (Zhenjiang). Full list: GET /api/v1/warehouses.
skurequired
string
SKU / barcode — the colour + size level, e.g. OB0021611. For the whole style use product_code instead.
max length 64
quantityrequired
integer
Quantity, a positive integer, e.g. 2. In reservation adjustments / carts, 0 removes the line.
1–99999
recipientrequired
object
Recipient object { name, phone, address, country_code, state, city, postal_code }. country_code is AU / CN / NZ; state, city and postal_code are required for AU and NZ. Include the country code in the phone for cross-border parcels (e.g. +61…) and the street number in the address — incomplete addresses are the top cause of failed delivery.
recipient.namerequired
string
Recipient name.
max length 128
recipient.phonerequired
string
Recipient phone; include the country code for cross-border parcels, e.g. +61…
max length 64
recipient.addressrequired
string
Delivery address including the street number — incomplete addresses are the top cause of failed delivery.
max length 512
recipient.country_coderequired
string
Destination country: AU / CN / NZ (drop-ship supports these three).
recipient.state
string
State / province, e.g. NSW. Required for AU and NZ addresses.
max length 64
recipient.city
string
City, e.g. Sydney. Required for AU and NZ addresses.
max length 128
recipient.postal_code
string
Postcode, e.g. 2000. Required for AU and NZ addresses.
max length 16
sender
object
Sender object { name, phone } (optional), printed on the waybill.
sender.name
string
Recipient name.
max length 128
sender.phone
string
Recipient phone; include the country code for cross-border parcels, e.g. +61…
max length 64
shipping_method
string
Shipping method: normal (default), express or ems.
auto_confirm
boolean
Submit immediately (optional). Omitted = draft only, someone confirms it in the ERP before it takes effect — this default is intentional. A submitted drop-ship order is allocated at once and can no longer be edited.
client_order_number
string
The order number in your own system (the one you sent when creating the drop-ship order).
max length 64
note
string
Remark (optional, up to 500 characters).
max length 500
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Send an Idempotency-Key header (any unique string, e.g. a UUID) on writes: a network retry never creates a second order. Orders are drafts by default until a person confirms them in the ERP.
Drop-ship orders
Drop-ship orders: by warehouse + date range, or look one up by client_order_number / serial_number
Warehouse code: AU (Australia, all warehouses — aggregate view), AUSYD2 (Sydney main, Rosehill), AUSYD1 (Sydney accessories), CN (China, all warehouses — aggregate view), CHNZJ1 (Zhenjiang). Full list: GET /api/v1/warehouses.
start_date
string
Start date, YYYY-MM-DD (inclusive).
max length 10 · format ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
end_date
string
End date, YYYY-MM-DD (inclusive).
max length 10 · format ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
shipped
boolean
Only shipped (true) or unshipped (false) orders (optional).
client_order_number
string
The order number in your own system (the one you sent when creating the drop-ship order).
max length 64
serial_number
string
Drop-ship serial number, from the drop-ship order list. Own channel only.
max length 64
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Warehouse code: AU (Australia, all warehouses — aggregate view), AUSYD2 (Sydney main, Rosehill), AUSYD1 (Sydney accessories), CN (China, all warehouses — aggregate view), CHNZJ1 (Zhenjiang). Full list: GET /api/v1/warehouses.
start_daterequired
string
Start date, YYYY-MM-DD (inclusive).
max length 10 · format ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
end_daterequired
string
End date, YYYY-MM-DD (inclusive).
max length 10 · format ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
page
number
Page number, from 1 (optional). Whole-warehouse stock returns everything when omitted — 30,000+ rows, paging recommended.
min 1
page_size
number
Rows per page (optional), max 2000.
1–2000
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Drop-ship order id, from the drop-ship order list. Own channel only.
max length 64
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Drop-ship orders
Void the drop-ship line and release the stock it was holding
Void the drop-ship line and release the stock it was holding. Lines already shipped cannot be voided
Path parameters
Name
Type
Description
dropship_order_idrequired
string
Drop-ship order id, from the drop-ship order list. Own channel only.
max length 64
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Send an Idempotency-Key header (any unique string, e.g. a UUID) on writes: a network retry never creates a second order. Orders are drafts by default until a person confirms them in the ERP.
Drop-ship orders
Drop-ship pre-allocation: per line, whether it can be filled, how much is short, when pre-sale stock arrives and what is payable
Drop-ship pre-allocation: per line, whether it can be filled, how much is short, when pre-sale stock arrives and what is payable. Note: pre-allocation holds stock — submit, or call DELETE …/{dropship_order_id}/allocation to release it
Request body (JSON)
Field
Type
Description
warehouse_coderequired
string
Warehouse code: AU (Australia, all warehouses — aggregate view), AUSYD2 (Sydney main, Rosehill), AUSYD1 (Sydney accessories), CN (China, all warehouses — aggregate view), CHNZJ1 (Zhenjiang). Full list: GET /api/v1/warehouses.
dropship_order_idsrequired
array<string>
Array of drop-ship serial numbers (the serial_number returned when the line was created). Up to 200 per call.
1–200
use_reservation
boolean
Whether to draw on your reserved (locked) stock for this allocation. Omit = do not use it.
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Send an Idempotency-Key header (any unique string, e.g. a UUID) on writes: a network retry never creates a second order. Orders are drafts by default until a person confirms them in the ERP.
Submit drop-ship lines (no changes afterwards). Preview first, then submit with the preview_key; payment_method defaults to invoice
Request body (JSON)
Field
Type
Description
warehouse_coderequired
string
Warehouse code: AU (Australia, all warehouses — aggregate view), AUSYD2 (Sydney main, Rosehill), AUSYD1 (Sydney accessories), CN (China, all warehouses — aggregate view), CHNZJ1 (Zhenjiang). Full list: GET /api/v1/warehouses.
dropship_order_idsrequired
array<string>
Array of drop-ship serial numbers (the serial_number returned when the line was created). Up to 200 per call.
1–200
preview_key
string
The preview_key returned by the allocation preview. Sending it means "submit exactly what that preview showed"; omit it and allocation is recalculated at submit time.
max length 128
payment_method
string
How to pay: balance / invoice (pay on invoice) / wechat / alipay. Defaults to invoice, i.e. monthly settlement.
use_reservation
boolean
Whether to draw on your reserved (locked) stock for this allocation. Omit = do not use it.
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Send an Idempotency-Key header (any unique string, e.g. a UUID) on writes: a network retry never creates a second order. Orders are drafts by default until a person confirms them in the ERP.
Drop-ship orders
Release the stock this drop-ship line holds from a pre-allocation you decided not to submit
Drop-ship order id, from the drop-ship order list. Own channel only.
max length 64
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Send an Idempotency-Key header (any unique string, e.g. a UUID) on writes: a network retry never creates a second order. Orders are drafts by default until a person confirms them in the ERP.
Warehouse code: AU (Australia, all warehouses — aggregate view), AUSYD2 (Sydney main, Rosehill), AUSYD1 (Sydney accessories), CN (China, all warehouses — aggregate view), CHNZJ1 (Zhenjiang). Full list: GET /api/v1/warehouses.
start_date
string
Start date, YYYY-MM-DD (inclusive).
max length 10 · format ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
end_date
string
End date, YYYY-MM-DD (inclusive).
max length 10 · format ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Shipments & logistics
Upload recipient ID images ⚠️ front and back of the end consumer's ID (PII)
Upload recipient ID images ⚠️ front and back of the end consumer's ID (PII). Off by default, apply to enable; pass-through only, never logged or cached
Request body (JSON)
Field
Type
Description
front_imagerequired
string
⚠️ Front of the ID document (base64). Sensitive personal data of the end consumer: we pass it through only, never log or cache it. Off by default; apply explicitly.
max length 8000000
back_imagerequired
string
⚠️ Back of the ID document (base64). Same as above.
max length 8000000
shipment_ids
array<string>
Related shipment ids (optional).
0–100
recipient
object
Recipient object { name, phone, address, country_code, state, city, postal_code }. country_code is AU / CN / NZ; state, city and postal_code are required for AU and NZ. Include the country code in the phone for cross-border parcels (e.g. +61…) and the street number in the address — incomplete addresses are the top cause of failed delivery.
recipient.name
string
Recipient name.
max length 128
recipient.phone
string
Recipient phone; include the country code for cross-border parcels, e.g. +61…
max length 64
document_number
string
ID number (optional).
max length 64
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Send an Idempotency-Key header (any unique string, e.g. a UUID) on writes: a network retry never creates a second order. Orders are drafts by default until a person confirms them in the ERP.
Shipment id (also used for tracking), from the shipment list. Own channel only.
max length 64
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Shipments & logistics
Tracking events (Auexpress; off by default, apply to enable)
Shipment id (also used for tracking), from the shipment list. Own channel only.
max length 64
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Warehouse code: AU (Australia, all warehouses — aggregate view), AUSYD2 (Sydney main, Rosehill), AUSYD1 (Sydney accessories), CN (China, all warehouses — aggregate view), CHNZJ1 (Zhenjiang). Full list: GET /api/v1/warehouses.
start_date
string
Start date, YYYY-MM-DD (inclusive).
max length 10 · format ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
end_date
string
End date, YYYY-MM-DD (inclusive).
max length 10 · format ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
status
string
Status filter (optional), comma-separated. Wholesale orders: draft / confirmed / cancelled; reservations: reserved / cancelled. No filter when omitted (reservations default to reserved + cancelled). The response uses the same words in status, with the raw code in status_raw.
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Reservation id, from the reservation list. Own channel only (read / adjust).
max length 64
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Reservation id, from the reservation list. Own channel only (read / adjust).
max length 64
Request body (JSON)
Field
Type
Description
linesrequired
array<object>
Line array, each { sku, quantity }. At least one; quantity=0 removes the line when adjusting a reservation.
1–1000
lines[].skurequired
string
SKU / barcode — the colour + size level, e.g. OB0021611. For the whole style use product_code instead.
max length 64
lines[].quantityrequired
integer
Quantity, a positive integer, e.g. 2. In reservation adjustments / carts, 0 removes the line.
0–99999
note
string
Remark (optional, up to 500 characters).
max length 500
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Send an Idempotency-Key header (any unique string, e.g. a UUID) on writes: a network retry never creates a second order. Orders are drafts by default until a person confirms them in the ERP.
Finance
Your account balances (Australia / China / New Zealand — whichever you have)
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Finance
Transactions (top-up / payment / refund) with the balance after each; amount_total is the page total
Transactions (top-up / payment / refund) with the balance after each; amount_total is the page total. The main reconciliation table
Query parameters
Name
Type
Description
start_date
string
Start date, YYYY-MM-DD (inclusive).
max length 10 · format ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
end_date
string
End date, YYYY-MM-DD (inclusive).
max length 10 · format ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
type
string
Show only one kind of transaction (optional): recharge (top-up) / payment (deduction) / refund. Omit for all.
page
number
Page number, from 1 (optional). Whole-warehouse stock returns everything when omitted — 30,000+ rows, paging recommended.
min 1
page_size
number
Rows per page (optional), max 2000.
1–2000
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Finance
Monthly bills by warehouse and month, including whether they are paid
max length 10 · format ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
end_date
string
End date, YYYY-MM-DD (inclusive).
max length 10 · format ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
page
number
Page number, from 1 (optional). Whole-warehouse stock returns everything when omitted — 30,000+ rows, paging recommended.
min 1
page_size
number
Rows per page (optional), max 2000.
1–2000
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Finance
Refund notes (wholesale / drop-ship) with review status and reason
max length 10 · format ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
end_date
string
End date, YYYY-MM-DD (inclusive).
max length 10 · format ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
page
number
Page number, from 1 (optional). Whole-warehouse stock returns everything when omitted — 30,000+ rows, paging recommended.
min 1
page_size
number
Rows per page (optional), max 2000.
1–2000
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
max length 10 · format ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
end_date
string
End date, YYYY-MM-DD (inclusive).
max length 10 · format ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
page
number
Page number, from 1 (optional). Whole-warehouse stock returns everything when omitted — 30,000+ rows, paging recommended.
min 1
page_size
number
Rows per page (optional), max 2000.
1–2000
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Cart owner account (the OMS site login, e.g. 100470admin).
max length 64
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Cart owner account (the OMS site login, e.g. 100470admin).
max length 64
Request body (JSON)
Field
Type
Description
linesrequired
array<object>
Line array, each { sku, quantity }. At least one; quantity=0 removes the line when adjusting a reservation.
1–500
lines[].skurequired
string
SKU / barcode — the colour + size level, e.g. OB0021611. For the whole style use product_code instead.
max length 64
lines[].quantityrequired
integer
Quantity, a positive integer, e.g. 2. In reservation adjustments / carts, 0 removes the line.
0–99999
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Send an Idempotency-Key header (any unique string, e.g. a UUID) on writes: a network retry never creates a second order. Orders are drafts by default until a person confirms them in the ERP.
Cart owner account (the OMS site login, e.g. 100470admin).
max length 64
skurequired
string
SKU / barcode — the colour + size level, e.g. OB0021611. For the whole style use product_code instead.
max length 64
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Send an Idempotency-Key header (any unique string, e.g. a UUID) on writes: a network retry never creates a second order. Orders are drafts by default until a person confirms them in the ERP.
Cart owner account (the OMS site login, e.g. 100470admin).
max length 64
product_coderequired
string
Style code — one style (every colour / size variant), e.g. OB002. For a single variant use sku. When querying prices, several can be comma-separated.
max length 64
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Send an Idempotency-Key header (any unique string, e.g. a UUID) on writes: a network retry never creates a second order. Orders are drafts by default until a person confirms them in the ERP.
Feeds
Build a product feed (Google Merchant spec — this is also the bulk export): produces csv / xml / json in one go and stores them for scheduled fetch
Build a product feed (Google Merchant spec — this is also the bulk export): produces csv / xml / json in one go and stores them for scheduled fetch. Requires an OMS account login: only an OMS session can return YOUR channel price, and a feed built from the master price would have you selling at the wrong price.
Query parameters
Name
Type
Description
warehouse_coderequired
string
Warehouse code: AU (Australia, all warehouses — aggregate view), AUSYD2 (Sydney main, Rosehill), AUSYD1 (Sydney accessories), CN (China, all warehouses — aggregate view), CHNZJ1 (Zhenjiang). Full list: GET /api/v1/warehouses.
format
string
csv（默认）/ xml / json
max length 8
link_template
string
你站上的商品页地址模板，里面用 {product_code} 或 {sku} 占位，我们替你拼。不给就不出 link，而 link 是必填项
max length 300
image_base
string
图片链接的绝对前缀。不给用服务端配置。必须走加密链接（TLS），明文图片链接各平台基本都会拒
max length 200
rebuild
boolean
强制重拼。不会再给你旧的那份 —— 回 202，拼好了再来取
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
Feeds
Check where the product feed build stands: building / done / failed (with the failure reason), plus the row count, build time and issues of the latest artifact
Check where the product feed build stands: building / done / failed (with the failure reason), plus the row count, build time and issues of the latest artifact. A build takes minutes and runs in the background — nobody sees a background failure, so the reason surfaces here.
Query parameters
Name
Type
Description
warehouse_coderequired
string
Warehouse code: AU (Australia, all warehouses — aggregate view), AUSYD2 (Sydney main, Rosehill), AUSYD1 (Sydney accessories), CN (China, all warehouses — aggregate view), CHNZJ1 (Zhenjiang). Full list: GET /api/v1/warehouses.
Response
The envelope is decided by the HTTP status alone: 2xx with { data: … } (lists also carry page / page_size / has_more or total_count); 4xx / 5xx with { error: { code, message, hint, request_id, doc_url } }.
One flow = one job to be done, with the endpoints it calls in order. The AI assistant and MCP use this same definition, so it cannot drift from the code.
check_stock
Check a batch of SKUs at once: pass a list of barcodes and get, for each, the available quantity, your settlement price and the expected arrival date when it is short. Use this for "are these in stock" instead of querying them one by one.
#
Step
Endpoint
1
me
GET /api/v1/me
2
stock_list
GET /api/v1/warehouses/{warehouse_code}/stock
Permission：stock:read
find_products
Find products by keyword: pass part of a style code or product name and get matching styles with your settlement price and whether they can be replenished. To see colours, sizes and stock for one style, then use check_stock or the product_get endpoint.
#
Step
Endpoint
1
me
GET /api/v1/me
2
product_list
GET /api/v1/products
Permission：product:read
get_statement
Reconcile a period: returns your account balances, the total for the period and the transactions behind it. Use this for "how much did we spend this month", "what is my balance", "reconcile the account".
#
Step
Endpoint
1
balance_list
GET /api/v1/balances
2
transaction_list
GET /api/v1/transactions
Permission：finance:read
quote_order write
See the allocation before committing to a wholesale order: creates a draft and runs the allocation preview, telling you per line how much can be allocated, how much is short, when it arrives and the total payable. It does NOT submit. Then use place_order to commit, or cancel_order to drop it (a draft left behind keeps holding allocation).
#
Step
Endpoint
1
me
GET /api/v1/me
2
order_create
POST /api/v1/orders
3
order_allocation_preview
POST /api/v1/orders/{order_id}/allocation-preview
Permission：order:write
place_order write
Submit a wholesale order (lines can no longer be changed). Run quote_order first to see the allocation and the amount. Payment defaults to pay-on-invoice.
#
Step
Endpoint
1
order_submit
POST /api/v1/orders/{order_id}/submit
Permission：order:write
cancel_order write
Void a wholesale order and release the allocation it was holding. Use this to clean up after deciding not to buy.
#
Step
Endpoint
1
order_cancel
DELETE /api/v1/orders/{order_id}
Permission：order:write
quote_dropship write
Pre-allocate before committing a drop-ship batch: creates the lines and runs the pre-allocation, telling you line by line whether it can be filled, how much is short and what is payable. It does NOT submit. This is the standard drop-ship flow, look at the shortages first. Then place_dropship to commit, or release_dropship to let the stock go.
#
Step
Endpoint
1
me
GET /api/v1/me
2
dropship_order_create
POST /api/v1/dropship-orders
3
dropship_order_allocation_preview
POST /api/v1/dropship-orders/allocation-preview
Permission：df:write
place_dropship write
Submit drop-ship lines (no changes afterwards). Pass the preview_key from quote_dropship to commit exactly what that pre-allocation showed.
#
Step
Endpoint
1
me
GET /api/v1/me
2
dropship_order_submit
POST /api/v1/dropship-orders/submit
Permission：df:write
release_dropship write
Release the stock held by a drop-ship pre-allocation you decided not to submit. Without this the stock stays held.
error.code in error responses is stable — branch on it, never on the text. error.docUrl points at the matching row here.
Code
Meaning
How to fix
AUTH_MISSING_TOKEN
Missing authentication token
Send Bearer <token> in the Authorization header (?token= is not accepted on /api/v1). Get a token from POST /api/v1/auth/token with client_id + client_secret in the body.
AUTH_INVALID_TOKEN
Invalid token
The token is malformed or its signature is wrong. Get a fresh one from POST /api/v1/auth/token; make sure it is not truncated and has no stray spaces.
AUTH_EXPIRED
Token expired
The token passed its expiry. Fetch a new one; we recommend refreshing automatically shortly before exp.
SCOPE_DENIED
Operation not permitted
Your channel role does not include this capability. Pick a plan under “Plans & access” and request it — it takes effect as soon as your account manager approves.
WAREHOUSE_DENIED
Warehouse not permitted
Your channel is not on this warehouse allowlist. Ask your account manager to add the warehouse to your channel, or clear the list to allow all.
AUTHZ_UNAVAILABLE
Authorization service unavailable
The authorisation service is temporarily unavailable. Retry shortly; if it persists, contact your account manager with the requestId.
VALIDATION_FAILED
Invalid request parameters
Fix the field named in error.param. Full field specs for every endpoint are at /swagger.
NOT_FOUND
Not found
That product code / SKU / sheet id does not exist or is misspelled. Double-check and retry.
OWNERSHIP_DENIED
Document does not belong to you
This document belongs to another channel. You can only read orders / shipments / holds for your own channel.
UPSTREAM_ERROR
Upstream ERP error
The upstream ERP is temporarily failing. Retry shortly; quote the requestId to support and we can trace that exact call.
UPSTREAM_TIMEOUT
Upstream timeout
The upstream ERP is slow or unreachable. Please retry shortly.
INTERNAL
Gateway internal error
An error inside the gateway itself (rare). Contact support with the requestId.
ADMIN_UNAUTHORIZED
Wrong admin token
Check that x-admin-token matches ADMIN_TOKEN in the server .env file.
ADMIN_DISABLED
Admin console disabled
ADMIN_TOKEN is not set on the server. Set it and restart.
IDEMPOTENCY_IN_PROGRESS
An identical request is still running
A previous request with the same Idempotency-Key has not finished. Retry shortly with the SAME key — changing the key risks creating a duplicate.
IDEMPOTENCY_MISMATCH
Idempotency-Key reused
This key was already used for a request with different content. Use a fresh key per business operation (a UUID, or your own order number).
IDEMPOTENCY_INVALID_KEY
Invalid Idempotency-Key
The key must be at most 255 characters. A UUID is recommended.
RATE_LIMITED
Rate limit exceeded
Check the RateLimit-Remaining / Retry-After response headers and back off. Pulling a whole warehouse is expensive (60 points); the incremental endpoint /Changes?since= costs only 1. If you genuinely need more, ask your account manager to raise your quota.
BAD_REQUEST
Bad request
Check the HTTP method, path and request body.
READ_ONLY_MODE
This environment is read-only
Writes to the upstream ERP are intentionally disabled here (WRITES_ENABLED=0) so this server is safe to test against. Reads work normally. Use the production environment to place real orders.
ENDPOINT_GONE
Endpoint retired
The API moved to /api/v1/** (lowercase paths, snake_case parameters). error.message names the replacement; the full list is at /reference or /llms.txt.
WAREHOUSE_UNKNOWN
Unknown warehouse
Use one of the codes listed by GET /api/v1/warehouses (AU / AUSYD2 / AUSYD1 / CN / CHNZJ1); aliases such as AuStock no longer exist.
UPSTREAM_REJECTED
Rejected by the ERP
The ERP did not accept this request (insufficient stock, unknown id, invalid field …); the reason is in error.message. Fix and retry; if it keeps happening send the request_id to your contact.
AUTH_BAD_CREDENTIALS
Wrong credentials
Channel grant: check client_id and client_secret (the secret is shown once at issue time; ask your admin to re-issue if lost). OMS grant (grant_type=password): check your OMS website login account and password. To try things out use sandbox / sandbox.
AUTH_LOCKED
Too many failed sign-ins — temporarily locked
Repeated wrong passwords lock the OMS account for 15 minutes. Check the account and password, then retry; to try things out use sandbox / sandbox.
DUPLICATE_SUSPECTED
Possible duplicate drop-ship line
The upstream flags the same recipient + SKU submitted twice in quick succession. If you meant it, use a different client_order_number or retry later.
OMS_LOGIN_REQUIRED
This endpoint needs an OMS account sign-in
Get a token with POST /api/v1/auth/token using grant_type=password and your OMS account (channel-secret tokens cannot use the ordering flow because allocation rules follow the OMS account).
SHIPPING_REQUIRED
Shipping info missing
A wholesale order needs a shipping method: pick a shipping_method_id from GET /api/v1/shipping-methods and put it in shipping; for delivery also pick an address_id from GET /api/v1/addresses. You can also set defaults on the OMS site under User → Preferences.
The domain model behind the business: entities, fields, relations. Only externally visible fields are listed. Machine-readable JSON-LD is at /ontology.
Relations
Product
hasMany
Sku
A style has several colour / size variants
Sku
hasStockIn
Warehouse
A SKU has stock in each warehouse (Stock)
Stock
refersTo
Sku
A stock row refers to one SKU
Stock
belongsTo
Warehouse
Every stock row carries its warehouse_code
Channel
hasAccessTo
Warehouse
Warehouses a channel may access (allowlist)
Channel
hasPriceFor
Product
A channel's own price for a style (Price)
Order
belongsTo
Channel
An order belongs to a channel (ownership check)
DropshipOrder
belongsTo
Channel
A drop-ship order belongs to a channel
Shipment
belongsTo
Channel
A shipment belongs to a channel
Shipment
belongsTo
Order
A shipment comes from a wholesale order (order_id)
StockReservation
belongsTo
Order
A reservation comes from a wholesale order (order_id); confirming an order creates the reservation, shipping creates the shipment
StockReservation
belongsTo
Channel
A reservation belongs to a channel
Cart
belongsTo
Channel
A cart (via account) belongs to a channel
Transaction
belongsTo
Channel
A transaction is booked against one channel account
Transaction
refersTo
Order
Most transactions carry an order number and a reservation number
Product Product (style)
One style code, containing several colour / size variants (SKUs).
Field
Type
Description
product_code
string
Style code
product_name
string
Product name (English)
product_name_zh
string
Product name in Chinese (present only when set; not yet fed from upstream)
brand
string
Brand
price_wholesale
number
Wholesale price
price_retail
number
Retail price
currency
string
Currency (AUD / CNY)
weight_grams
integer
Weight in grams (present only when set; not yet fed from upstream)
image_urls
array
Product image URLs
description
string
Specification description
skus
array
Every variant of this style (Sku)
Sku SKU (barcode / variant)
One specific barcode = style × colour × size.
Field
Type
Description
sku
string
SKU / barcode
product_code
string
Owning style code
color_code
string
Colour code
color_name
string
Colour name
color_name_zh
string
Colour name in Chinese (present only when set; not yet fed from upstream)
size
string
Size
Warehouse Warehouse
Where stock sits. warehouse_code is the single identifier used in paths, parameters and responses: AU = Australia (all warehouses) (100003); AUSYD2 = Sydney main warehouse (Rosehill) (AUSYD2); AUSYD1 = Sydney accessories warehouse (AUSYD1); CN = China (all warehouses) (500001); CHNZJ1 = Zhenjiang warehouse (CHNZJ1)
Your AI (Claude Desktop, Cursor, or an agent you wrote) connects to the gateway with your token; the tool list is trimmed to your permissions — connecting an AI never widens access.
Remote MCP
Add a server to your MCP client's config: the URL is this site's /mcp, with your token in the header.
Exchange channel code + secret for a token (POST /api/v1/auth/token).
Paste the JSON on the right into the client config and replace the token.
Once connected the tool list appears automatically; what you can call depends on your roles and warehouse allowlist.
Command-capable AI: use the CLI
Coding assistants like Claude Code and Cursor already live in a terminal: with ever installed they look up stock and read the docs on their own, no MCP setup. Tool names are identical to MCP (both come from the capability catalog).
The docs are shaped for AI too: every page has a Markdown version, and the index is llms.txt · Command line (CLI)
Permissions
Every connection uses the caller's own token: we resolve who you are and your scopes, then trim the tools; every call still goes through the gateway (auth, authorization, warehouse allowlist, rate limit). Writes are never executed automatically.
A2A (agent to agent)
A peer agent can talk directly over the A2A protocol: POST https://connect.everugg.net.au/a2a · agent-card.json