One contract from warehouse receipt to delivery.

Overview

Base URL: https://api.woolii.com. All endpoints live under /v1/merchant, accept and return JSON, and are bounded to the authenticated merchant account — a resource id alone is never sufficient to read data. Most responses carry an X-Request-Id header; include it when you contact us about a request. Requests are rate-limited per key; a 429 includes a Retry-After header. Webhook endpoints must be public https URLs — loopback, private and cloud-metadata addresses are rejected.

The API covers three connected workflows, and in all of them you (or your supplier) buy and own the goods. The forwarding workflow is pass-through: parcels arrive at the assigned Woolii China warehouse, and WooliiPorter operates receiving, optional inspection, value-added services (relabeling, repacking, FBA prep), consolidation, the packed quote, line-item settlement, dispatch and WooliiPorter tracking. The optional stocking workflow adds merchant-owned inventory on top: register SKUs, pre-alert inbound shipments, and dispatch fulfillment orders from stock — with live ledger-computed inventory, warehouse transfers and a monthly statement that reconciles line by line. The commerce-order workflow lets an enabled WooCommerce store submit one order snapshot and receive a stocked, forwarding or merchant-review outcome, with the selected public product carried through execution. Prefer to let an agent drive it? See the MCP server.

Read shipping products first. A product’s fixed country assignment defines its transport service; quote checks validate cargo, postcode, weight and dimensions. Customer responses carry public product names, sell quotes and stable WooliiPorter tracking identities. Direct estimate/order endpoints use the account default; commerce intents also resolve the registered store default. Pass productCode explicitly to keep the same selection across calls.

Versions & changes

The URL /v1/merchant identifies the API major version. OpenAPI info.version identifies the Merchant API contract release; 3.1.0 is the OpenAPI document format. The documentation revision is a separate audit marker.

We use semantic versions: patches correct compatible defects or documentation; minor versions add compatible capabilities. Incompatible fields, states, payment semantics or webhook payloads require a major version and a documented migration. Published releases are immutable. Deprecation notices specify the replacement and retirement date before an old contract is retired.

Shopify and WordPress/WooCommerce connectors keep their own versions. Each coordinated release records their supported API contract, upgrade instructions and verification results. A new plugin version does not by itself change the API major version.

2.2.0 — changes

2.2.0 is an additive minor release over 2.1.0. Requests and existing fields keep their meaning. A declined value-added service now says why in services[].declineReason; the order object stays open in the OpenAPI, so additional response fields are not a validation change.

• Value-added servicesA services[] entry whose state is declined adds declineReason: customer_declined (you declined it), expired (the approval window closed without a decision) or withdrawn (WooliiPorter operations withdrew it, for example after you asked by phone). state stays declined and no fee is charged in any case. Treat an unknown declineReason as declined.
• OpenAPICreate, retrieve, cancel, simulate and list order responses now reference MerchantOrderResponse / MerchantOrderPage, with services[] typed as MerchantOrderService. The order object remains open (additionalProperties: true); only the service entries are described in detail.

Authentication

Authenticate with a Bearer key. Keys belong to one account, carry a sandbox or production execution mode, and grant explicit scopes. New merchants complete business review and online signing before activation, then create either a wp_sk_test_… (sandbox) or wp_sk_live_… (production) key in the developer console. Start in sandbox and move to production only after the workflow is validated and the applicable account terms are accepted. Each key carries explicit scopes: orders:read, orders:write, tracking:read, finance:read, finance:pay (explicit wallet-payment permission), webhooks:write, console:sso.

Keys can be rotated and revoked without losing the request audit trail. Store them like passwords.

Sandbox

Orders created with a wp_sk_test_… key are sandbox orders: they carry"sandbox": true, and they never enter real fulfilment — no warehouse receiving, no live tracking, no dispatch. They share your account's data space, so use a distinctexternalOrderId range (e.g. a test- prefix) to keep them recognizable.

Because there is no warehouse behind a sandbox order, advance its lifecycle yourself to exercise your webhook receiver end to end:

Simulation is rejected (409 merchant_not_sandbox) for production orders — those advance from real warehouse events only.

Idempotency

Operations explicitly marked requires Idempotency-Key accept any stable unique string up to 200 characters. Retrying one of those operations with the same key and body returns the original stored response; the same key with a different body returns 409 merchant_idempotency_conflict. The direct forwarding create/cancel operations and every fulfillment-intent mutation use this stored-response contract.

Other writes are not interchangeable: SKU and Store registration are natural upserts, fulfillment creation deduplicates by externalOrderId, while payment, sandbox simulation, inbound, transfer and webhook creation have endpoint-specific behavior. Unless an endpoint says it is replay-safe, reconcile with a GET before retrying after an ambiguous timeout.

Errors

The standard error envelope is shown alongside. Endpoint-specific responses take precedence:

• PUT /transport-products validation errors (422) use a top-level string error, with code or issues when supplied.
• POST /inbound-shipments returns a top-level string error and code: merchant_agreement_required (403) when the signed agreement does not cover the service. This response does not include a request ID.

Check the API connection

GET/v1/merchant/connection

Scope orders:read

Validates the key and returns the merchant account, environment, granted scopes and enabled features. Call this before registering a store and enabling automatic order submission. The legacy smartRouting flag controls commerce fulfillment-intent access; shipping uses your selected product and its configured destination coverage.

mcp: false means no hosted remote MCP endpoint is enabled. mcpStdioPreview: true identifies the optional standalone stdio adapter, which uses this same API key and scopes.

Register a WooCommerce store

PUT/v1/merchant/stores/{externalStoreId}

Scope orders:write

Creates or updates one WooCommerce installation in the API-key environment. The operation is naturally idempotent because the account, environment, platform and externalStoreId form the upsert key. The official plugin generates the Store identity once and keeps it stable across reconnects.

Production storeUrl and webhookUrl values must use HTTPS. Explicit loopback URLs are accepted only by the isolated local release harness.

Read the store onboarding checklist

GET/v1/merchant/stores/{externalStoreId}/onboarding

Scope orders:read

Returns the same seven-step onboarding snapshot as the merchant console: account, channel services, product sync, SKU links, inbound stocking, shipping product and first-order validation, plus wallet funding. The official plugin uses this response to show the next setup action.

Warehouse work is gated on wallet funds (ON_HOLD_BALANCE). The wizard should route merchants to the console finance workspace through the console-sso handoff rather than collecting payment details inside WordPress.

Sync the WooCommerce catalog and link SKUs

POST/v1/merchant/stores/{externalStoreId}/catalog

Scope orders:write

Registers up to 250 WooCommerce products or variations per call and links them to warehouse SKUs. A row with an explicit skuCode is linked to that SKU; a row whose channel sku exactly matches one active warehouse SKU is linked automatically; every other row is returned as unmatched for a manual decision. The sync never creates warehouse SKUs and never guesses a link. A successful call records the catalog sync evidence used by onboarding step 3.

An invalid or inactive explicit skuCode rejects the whole batch with merchant_sku_code_invalid so a typo never half-links a catalog.

Open the Woolii merchant console

POST/v1/merchant/console-sso

Scope console:sso

Creates a 60-second, single-use merchant-console handoff for one registered WooCommerce Store. The official plugin calls this endpoint from WordPress after a manage_woocommerce nonce check; the API key never enters the browser or handoff URL. The returned URL must be opened immediately and must never be logged, cached, emailed or persisted.

This is a connector handoff, not a general authentication API. It requires an active member linked to the Store account and rejects expiry or replay.

Submit a commerce order for fulfillment

POST/v1/merchant/fulfillment-intents

Scope orders:write · requires Idempotency-Key

Submits a versioned WooCommerce order snapshot. WooliiPorter resolves productCode, then the registered store default, then the account default, and validates the product against destination, cargo and purpose. Stocked lines reserve inventory; forwarding lines await domestic supplier parcels; mixed orders return the merchant actions needed to proceed. Access requires a registered store and features.smartRouting=true.

Possible statuses include MAPPING_REQUIRED, WAITING_SUPPLIER_TRACKING, MIXED_REVIEW_REQUIRED, ROUTED_FULFILLMENT, ROUTED_FORWARDING, ON_HOLD_BALANCE, STALE, ROUTING_BLOCKED and CANCELLED. Follow requiredActions and the optional cancellation projection rather than inferring the next action from status text.

A changed externalOrderVersion may replace only an intent with no child order and no submitted supplier parcel. Otherwise the intent becomes STALE for human review.

The official WooCommerce plugin always sends externalOrderName for display and search. externalOrderId remains the stable identity used for idempotent intent upserts.

Retrieve a fulfillment intent

GET/v1/merchant/fulfillment-intents/{id}

Scope orders:read

Returns the selected public product, inventory/forwarding decisions per line, routingVersion, requiredActions, editable supplier parcels, child orders, complete public parcel delivery facts and any cancellation lifecycle. routingVersion is an optimistic concurrency token for fulfillment decisions; refresh it before every mutation.

delivery contains complete (boolean) and shipments[]. Each shipment contains shipmentNumber, status, handedOverAt and parcels[] with parcelNumber, trackingNumber, trackingUrl and trackingStatus. Cancelled replacement shipments are omitted. No upstream carrier identifiers are exposed.

Use delivery.complete for whole-order delivery. A delivered child, a carrier scan before warehouse handover, or a split route whose other child is not created is not complete. Re-read the intent for the current state after every callback or missed callback; older releases may omit delivery.

cancellation is omitted until a cancellation has been requested. Its status is the durable lifecycle projection: WAREHOUSE_STOPPED and WAREHOUSE_RETURNED require operational follow-up, ADMIN_REVIEW requires an authorized recall or after-sales decision, and CANCELLED is terminal.

Cancel a fulfillment intent

POST/v1/merchant/fulfillment-intents/{id}/cancel

Scope orders:write · requires Idempotency-Key

Requests cancellation against the unified commerce fulfillment intent, so the API evaluates its stocked-fulfillment or supplier-forwarding child and the real physical execution stage. A 200 response means every linked operation was safely cancelled. A 202 response means the request was accepted but warehouse return or authorized admin review must finish before the intent is terminal.

200 outcome CANCELLED: the intent and its safe linked work are terminally cancelled; cancellation.status is CANCELLED and resolvedAt is populated.

202 outcome WAREHOUSE_REVIEW_REQUIRED: warehouse work was stopped and the cancellation projection advances through WAREHOUSE_STOPPED and WAREHOUSE_RETURNED before an authorized operator closes settlement.

202 outcome ADMIN_REVIEW_REQUIRED: transport or another protected stage requires an authorized recall or after-sales decision; cancellation.status is ADMIN_REVIEW.

The response repeats cancellation at the top level for immediate disposition handling and inside fulfillmentIntent as the canonical status projection. A terminal 200 response replays unchanged; a request first accepted with 202 keeps the same request identity but later retries project the current lifecycle, including eventual 200 CANCELLED after authorized closure.

Cancellation and retry projections preserve externalOrderName so operators can continue reconciling the WooCommerce order while externalOrderId remains unchanged.

Save supplier parcel drafts

PUT/v1/merchant/fulfillment-intents/{id}/supplier-parcels

Scope orders:write · requires Idempotency-Key

Replaces the complete editable supplier-parcel draft for an intent that is waiting for forwarding. Each real China domestic tracking number carries one or more externalLineId quantity allocations. Draft allocations may be partial, but cannot over-allocate a line or reuse a tracking number.

A routingVersion mismatch returns 409 merchant_intent_version_conflict. Submitted or received parcels are locked and cannot be replaced.

Submit supplier forwarding

POST/v1/merchant/fulfillment-intents/{id}/submit-forwarding

Scope orders:write · requires Idempotency-Key

Locks the supplier parcels and atomically creates the forwarding child order. Submission succeeds only when the saved parcel allocations exactly cover every forwarding line. The plugin deliberately separates draft saving from this irreversible warehouse handoff.

Incomplete exact coverage returns 422 merchant_supplier_parcels_incomplete with expected and allocated quantities per line.

Choose how a mixed order proceeds

POST/v1/merchant/fulfillment-intents/{id}/select-route

Scope orders:write · requires Idempotency-Key

Resolves an unexecuted mixed order. FORWARD_ALL moves every line to supplier forwarding. WAIT_FOR_STOCK records the merchant decision but leaves the intent in review until stock changes and the merchant explicitly re-evaluates. Automatic split fulfillment is intentionally disabled in this release.

Re-evaluate stock and fulfillment readiness

POST/v1/merchant/fulfillment-intents/{id}/re-evaluate

Scope orders:write · requires Idempotency-Key

Re-runs an unexecuted mixed, mapping-required or routing-blocked intent against current mappings, route configuration and inventory. It never re-routes an intent that already has a child order or submitted supplier parcel.

List shipping products and defaults

GET/v1/merchant/transport-products

Scope orders:read

Returns public shipping products, cargo types, fulfillment purposes, product families, country readiness and saved account/store defaults. stores contains only registrations in this API key environment; the account default is shared by the merchant account. Use countries[].available to check operational readiness, then estimate the selected product with actual destination and measurements.

Product codes and coverage come from this catalog; names shown here are illustrative. A listed country with available=false remains a configured destination but is not ready for a quote.

This endpoint returns the product catalog and defaults without an X-Request-Id success header. Authentication failures use the standard merchant error envelope.

Save a default shipping product

PUT/v1/merchant/transport-products

Scope orders:write

Saves an explicit product selection for new orders. Specify storeId to change that registered store, or omit it for the account default. Existing intents and shipments keep their selected product. Send null to clear a default.

storeId is the internal store resource ID returned by GET /transport-products, not externalStoreId. Store defaults are environment-scoped; omitting storeId updates the shared account default.

This endpoint currently returns validation errors as {error: string, issues: [...]}, or {error: string, code: "transport_product_unavailable" | "store_not_found"} with HTTP 422. Successful writes return {productCode} without an X-Request-Id header.

Read historical delivery rules

GET/v1/merchant/routing-rules

Scope orders:read

Historical records only. These rules no longer select a product for new orders.

Retired delivery-rule writes

PUT/v1/merchant/routing-rules

Scope orders:write

Returns HTTP 410. Use productCode on orders or save a default through /transport-products.

Estimate cost and transit

POST/v1/merchant/orders/estimate

Scope orders:read

Estimates freight and requested warehouse services for your selected product, destination and package measurements. The product has a fixed country assignment. The result uses current published prices, your merchant settlement policy and quote-time exchange rate. Final packed pricing uses warehouse measurements and adds applicable declaration-based taxes and fees.

This request accepts productCode, packageTypeId, destination, packages and services. Use the store-selected productCode explicitly when estimating for a store. A non-USD estimate returns totals.estimatedTotal=null because warehouse service lines are quoted in USD.

The estimate has no declaration or IOSS input, so it does not calculate VAT or the EU per-HS charge. Send the full customer declaration on the order/SKU and read final settlement after packing and HS review.

A missing or ambiguous WooliiPorter service, route, rate version, settlement policy, postal zone or FX snapshot returns 422 merchant_estimate_unavailable. No legacy tariff fallback is used. Value-added service requests are validated here with the same rules as order creation — incomplete label-class jobs return 422 merchant_vas_incomplete before any pricing runs.

Create an order pre-alert

POST/v1/merchant/orders

Scope orders:write · requires Idempotency-Key

Registers a forwarding pre-alert with a destination, domestic supplier parcels and a selected shipping product. Each product uses its assigned full-service supplier for that country. Transit-band and price/speed overrides are retired. Returns the Woolii order, its receiving instructions and the recorded parcels. externalOrderId is unique per account.

New forwarding creates return HTTP 201. The initial response confirms warehouse intake; a supplied product is fully checked against packed measurements at pricing. Quote readiness also requires complete declarations and confirmed HS classification.

Declare the complete customer value, at least USD 1 per unit when supplied. VAT uses quantity × declaredUnitPrice. New applicable EU non-IOSS quotes use the configured EUR 3 charge per distinct confirmed HS code per physical parcel. Read the final settlement lines rather than hard-coding fees; existing quote snapshots remain unchanged. IOSS treatment requires administrator verification for this order and a matching tax snapshot; an account tax number alone is insufficient. This request has no iossNumber or hsCode field; use the declaration and operations review workflows.

transitBandId, bandPreference and maxTransitDays return 422 merchant_routing_retired. serviceType is not an accepted field on this strict create schema. Use productCode.

Requires an Idempotency-Key header. Replaying the same key with the same body returns the stored response; a different body returns 409 merchant_idempotency_conflict.

A tracking number that already belongs to another active order returns 409 merchant_parcel_conflict.

List orders

GET/v1/merchant/orders

Scope orders:read

Cursor-paginated list of your orders, newest first. Filter by externalOrderId, state, or updatedSince (ISO 8601).

Pass nextCursor back as ?cursor= to fetch the next page. limit is capped at 100.

Retrieve an order

GET/v1/merchant/orders/{id}

Scope orders:read

Returns one order with its parcels, receiving instructions and the live progress of every value-added service you requested. Order ids from another account return 404 — resource existence is never disclosed across accounts.

Each services[] entry tracks one job: stage (receive | sort | pack) pins it to a warehouse step, state moves requested → done, and the fee line reappears verbatim in the settlement. A declined entry adds declineReason (customer_declined | expired | withdrawn) and is not charged.

Cancel an order

POST/v1/merchant/orders/{id}/cancel

Scope orders:write · requires Idempotency-Key

Cancels a direct forwarding pre-alert only before any parcel has been received and before payment has settled. The aggregate awaiting_parcels state alone does not prove that no goods are in the warehouse. Receipt and cancellation share a transaction lock.

If any parcel has arrived, returns 409 merchant_order_conflict. Contact support for cancellation review; goods, photos and warehouse locations remain recorded.

Channel-linked orders return 409 with details.fulfillmentIntentId. Cancel through POST /fulfillment-intents/{id}/cancel so the channel and child order remain synchronized.

Retry an ambiguous response with the same Idempotency-Key. A different key is a new request and is checked against the current order state.

Simulate a sandbox lifecycle event

POST/v1/merchant/orders/{id}/simulate

Scope orders:write

Advances a sandbox forwarding order and emits the matching signed webhook without touching real warehouse, payment or carrier systems. Use the events in order when testing an end-to-end receiver. Production orders are always rejected.

Calling this endpoint for a production order returns 409 merchant_not_sandbox. The simulator does not require Idempotency-Key; do not retry it blindly after an ambiguous network failure.

List shippable countries

GET/v1/merchant/countries

Scope orders:read

Country-level candidates backed by a current published carrier buy-rate version and an executable published WooliiPorter route. This endpoint no longer reads legacy ShippingRate rows. Postal zone, cargo type, weight and dimension eligibility remain authoritative in the estimate endpoint.

Retrieve the quote state

GET/v1/merchant/orders/{id}/quote

Scope orders:read

Read packed freight, packaging, insurance and transit estimates for the selected product. New amounts come from each parcel’s current versioned sell quote; historical orders retain their legacy quote projection. For versioned quotes, amounts.total is the shipping/packaging/insurance subtotal. Read settlement for the complete itemized bill, including warehouse services and applicable taxes.

stage: pending_packed_quote | final_packed_quote | unavailable. The final versioned quote is visible after every packed parcel has a current quote in one currency.

For source=versioned_shipment_quote, amounts.total excludes VAS, VAT and per-HS fees. Use GET /settlement and its total to display the payment amount.

Retrieve the settlement

GET/v1/merchant/orders/{id}/settlement

Scope orders:read

Read the complete itemized bill from merchant FeeItems, the merchant wallet payment and refunded amounts. Total is the sum of the returned fee rows in the order currency. Lines remain empty before the final quote. Copy settlementVersion into an explicit wallet-payment request after confirming the current total.

stage retains pending_final_quote | payable | paid | cancelled. A historical paid stage does not prove current funds: inspect payment.status and validForDispatch, especially after a refund or declaration correction.

payment includes provider, status, amount, currency, paidAt and refundedAmount. Wallet status may be open, completed, refund_pending, partially_refunded, refunded or void. billId identifies the merchant ledger bill.

settlementVersion is null before final pricing. A changed price, parcel, address or discount produces another version. Never substitute a client-entered amount.

validForDispatch checks current settlement evidence; booking, labels, exceptions and physical PDA handover remain separate gates. Sandbox is never eligible for real dispatch.

Existing legacy aggregate-only fees require reconciliation before wallet payment; the candidate no longer invents aggregate rows absent from the merchant fee ledger. This difference requires compatibility review.

Pay from the merchant wallet

POST/v1/merchant/orders/{id}/wallet-payment

Scope finance:pay · requires Idempotency-Key

Pay the confirmed final quote from the merchant wallet using the same bill and debit transaction as the console. Requires explicit finance:pay, Idempotency-Key and settlementVersion. Sandbox simulates payment without spending wallet funds. No card secret is returned.

Create a payment-enabled key in the developer console as an authorized account owner. finance:pay is never added to existing or default keys automatically. Wallet funding uses the existing merchant console top-up flow.

402 merchant_insufficient_balance leaves the bill OPEN and moves no money. Top up, reread settlement and use a new Idempotency-Key. The original key continues replaying the original response.

409 merchant_quote_changed requires rereading and confirming the revised quote. Other payment blocks require the existing review workflow. Cancelled, refunded and under-review orders cannot be charged again here.

A replay is the original response snapshot; GET /settlement returns the current refund and dispatch eligibility. After a timeout retry the same key and version. The debit, order advancement, notification, webhook and replay response commit together. A different key for an already validly settled order returns its settlement without another debit.

payment.completed indicates settled funds; it is not a carrier booking or physical dispatch event.

Legacy card payment entry

POST/v1/merchant/orders/{id}/pay

Scope orders:write

Deprecated candidate behavior: production returns 503 merchant_payment_unavailable without collecting money because the personal Stripe completion rail rejects merchant orders. Use the merchant console or explicitly migrate to wallet-payment. Sandbox retains its simulated response. This is a compatibility-impacting safety change, not an automatic wallet debit.

Do not retry this production response automatically or expect a Stripe clientSecret. First upgrade the integration, obtain an explicitly authorized key and confirm a current quote. No JSON body is required here.

Existing sandbox simulation and pre-payment validation errors remain. Production rollout requires the migration and client-compatibility gate in the release plan; this candidate is not yet published.

Retrieve the timeline

GET/v1/merchant/orders/{id}/timeline

Scope orders:read

One time-ordered event stream for the whole journey: the China private leg (receiving, inspection, value-added services, packing, payment) merged with the international carrier leg. "Where is my order?" has a single answer from a single endpoint.

segment: cn (private China leg) | intl (carrier network). CN event types: order.created, parcel.received, inspection.completed, vas.completed, package.packed, payment.completed; carrier events are type carrier.event.

A carrier lookup failure never blocks the timeline — the China leg is always complete.

Retrieve tracking

GET/v1/merchant/orders/{id}/tracking

Scope tracking:read

Order-keyed tracking projection for every outbound package on the order. It returns the stable WooliiPorter WP number and the same delivery timeline available on woolii.com/track.

List unified shipments

GET/v1/merchant/shipments

Scope orders:read

Lists the immutable outbound-shipment ledger across forwarding and stocked fulfillment. Use cursor pagination for continuous synchronization. The carrier is always WooliiPorter and each row uses the same stable public reference shown to the customer.

Shipment creation is warehouse-controlled. Merchants create orders or fulfillment orders; after packing, WooliiPorter materializes and routes the shipment. This endpoint is read-only and never accepts a carrier choice.

The public service is a WooliiPorter transport product such as international small parcel or express. It is distinct from the warehouse fulfillment workflow selected for the order.

Collection rows are intentionally compact: parcel lines, measurements and event history are available from the shipment detail resource. This keeps high-volume incremental synchronization bounded.

BOOKING_UNKNOWN is a reconciliable technical state, not proof of failure. Continue reading the shipment or wait for webhook updates; do not submit a duplicate order.

Retrieve a unified shipment

GET/v1/merchant/shipments/{shipmentNumber}

Scope orders:read

Returns one outbound shipment by its WooliiPorter shipment number, including public parcel measurements, merchant-owned line snapshots, the latest merchant sell quote and the WooliiPorter delivery timeline. actionRequired lists holds that keep a not-yet-booked shipment in the warehouse; it is empty otherwise.

A held US shipment returns, for example, "actionRequired": [ { "code": "cpsc_filing_required", "message": "…", "skus": [ { "skuCode": "TOY-BLOCKS-50", "reason": "CERTIFICATE_REFERENCES_MISSING", "merchantAction": true, "message": "…" } ] } ].

Reasons: CERTIFICATE_REFERENCES_MISSING and FILING_REJECTED need you to update the certificate (merchantAction true); FILING_PENDING and SERVICE_UNSUPPORTED are handled by WooliiPorter operations. Treat unknown codes and reasons as holds you cannot clear yourself.

Retrieve shipment-native tracking

GET/v1/merchant/shipments/{shipmentNumber}/tracking

Scope tracking:read

Returns the compact tracking projection for every parcel in one unified shipment. New integrations should prefer this shipment-native endpoint; the order-keyed endpoint is only an alternate projection of the same Shipment ledger.

Customer lookup is available without a merchant key at GET /public/tracking/{WP-number}; it is IP rate-limited and returns only carrier=WooliiPorter, status, public location and timestamps.

The authenticated tracking-publication feed is a separate partner contract and cannot be read with merchant keys.

Register a SKU

POST/v1/merchant/skus

Scope orders:write

Registers or updates a SKU in your catalog — an upsert keyed on skuCode, so replaying the same registration is safe without an Idempotency-Key. SKUs are the master data for stocking: inbound shipments and fulfillment orders reference skuCode and are rejected with 422 merchant_sku_unregistered until the SKU exists — stock is never put away against a guessed product. Re-registering reactivates an inactive SKU.

List SKUs

GET/v1/merchant/skus

Scope orders:read

Your active SKUs, sorted by skuCode. Up to 500 entries are returned.

cpscRegulated is true when the SKU has a US CPSC certificate on file; read it with GET /skus/{skuCode}/cpsc.

Retrieve a SKU CPSC certificate

GET/v1/merchant/skus/{skuCode}/cpsc

Scope orders:read

Returns the US CPSC certificate (Children's Product Certificate or General Certificate of Conformity) kept for one SKU and the filing status for your key environment. certificate is null when the SKU is not regulated. A SKU with a certificate is held from US shipment until WooliiPorter has filed the current certificate for the selected service; the shipment's actionRequired list is authoritative for a specific shipment.

filing.status: NOT_FILED (nothing filed yet), ACCEPTED (the current certificate was accepted), REJECTED (the latest filing of the current certificate was rejected — review the data or contact support), UNCONFIRMED (the result was not confirmed; WooliiPorter files again) or OUTDATED (filed before the certificate last changed).

Carrier identities, filing request bodies and raw carrier responses are never returned.

Save a SKU CPSC certificate

PUT/v1/merchant/skus/{skuCode}/cpsc

Scope orders:write

Creates or replaces the US CPSC certificate of a registered SKU. Replaying the same content is a no-op, so the call is safe to retry without an Idempotency-Key. Any change to the content invalidates earlier filings: the SKU is held from US shipment until WooliiPorter files the new version. Send expectedVersion from your last read to avoid overwriting a concurrent edit.

404 merchant_sku_not_found when the SKU is not registered; register it with POST /skus first.

403 merchant_sandbox_read_only for sandbox keys: the certificate is shared with production, where a change re-holds live US shipments until it is filed again.

Remove a SKU CPSC certificate

DELETE/v1/merchant/skus/{skuCode}/cpsc

Scope orders:write

Removes a certificate entered by mistake, which also lifts the US CPSC hold for that SKU. A certificate that was already filed with a carrier is kept as evidence and returns 409 merchant_cpsc_already_filed; update it instead.

Create an inbound shipment

POST/v1/merchant/inbound-shipments

Scope orders:write

Creates stored-inventory intake or an enabled Amazon FBA prep/first-mile workflow. The compatibility MARKETPLACE_FBM input is normalized to STORED_FULFILLMENT for new stocking receipts. WooliiPorter returns a public IB number and assigned receiving address; place the IB number on every carton.

Unregistered SKU codes return 422 merchant_sku_unregistered with every missing code in details.missing — register them via POST /skus first.

AMAZON_FBA requires fba.region, fulfillmentCenter and shipmentId plus explicit RELABEL, POLYBAG and PALLETIZE prep covering every declared unit. Use an available product supporting AMAZON_FBA and an actual destination country for an EU shipment. Activation also requires the dedicated FBA warehouse workflow.

WooliiPorter assigns the receiving warehouse from the enabled business route. If no active route exists, the API returns a 409 routing error instead of guessing a receiving address.

The returned IB number is the customer/PDA receiving identity. Do not invent a tracking number or send a supplier carrier number in this endpoint.

exceptions contains only WooliiPorter-branded status, type and customer-action flags. Internal warehouse providers, evidence paths, liability, supplier costs and payable records are never exposed.

Stored inventory follows expected → receiving → processing → putaway → stocked (or cancelled); sellable stock is available after putaway. FBA uses its dedicated prep/first-mile workflow. firstMile appears after recorded physical dispatch and contains WooliiPorter and dispatchedAt only; upstream carrier names and tracking/booking numbers are internal.

List inbound shipments

GET/v1/merchant/inbound-shipments

Scope orders:read

Your inbound shipments, newest first, with IB numbers, per-line quantities and customer-safe exceptions. source distinguishes inbound_delivery from stored_inventory replenishment. Replenishment has null declared/received cartons and no new receiving instructions; dispatchUnits reports actual carton and pallet counts. Cursor pagination returns up to 100 entries per page.

Retrieve an inbound shipment

GET/v1/merchant/inbound-shipments/{inboundNumber}

Scope orders:read

Retrieves one tenant-scoped inbound by public IB number. Database IDs are internal and never become customer-facing references. The response uses the same projection as create/list and includes current customer-safe exception status.

A missing or cross-tenant IB number returns the same 404 merchant_inbound_not_found response.

Provider identities, quarantine bins, internal notes, evidence URLs, responsibility findings, customer receivable drafts and provider payables are excluded.

Retrieve inventory

GET/v1/merchant/inventory

Scope orders:read

Live stock levels per SKU per warehouse — onHand, reserved, available — plus stock aging (the receipt date of the oldest lot still holding stock). Every number is computed on read by summing the immutable stock-movement ledger, the same source the storage lines on your statement are computed from: inventory and billing can never disagree. Filter one SKU with ?sku=.

Create a fulfillment order

POST/v1/merchant/fulfillment-orders

Scope orders:write

Creates a dropship fulfillment order shipped from your stocked inventory — one destination address, one or more SKU lines. externalOrderId is the idempotency key: replaying an id that already exists returns the stored order with replayed: true instead of creating a duplicate. By default the order is confirmed automatically on creation; set draftOnly to hold it in draft for an explicit confirm call.

Reservation is atomic and consumes stock oldest-first (FIFO) within the assigned warehouse. Product eligibility, a valid freight quote, full SKU declarations, confirmed HS classification and sufficient wallet funds are checked before reservation. When a prerequisite or stock is missing, the order is on_hold with holdReason; correct it, then call confirm.

Unregistered SKU codes return 422 merchant_sku_unregistered with the codes in details.missing.

state can be awaiting_payment, draft, confirmed, reserved, on_hold, picking, packed, dispatched, in_transit, delivered, cancelled or exception. Read holdReason and cancellation when present; do not treat an unfamiliar state as dispatch permission.

Fulfillment fees must be settled from the merchant wallet before dispatch. fees[] and monthly statements report ledger entries; neither is permission to ship before payment.

List fulfillment orders

GET/v1/merchant/fulfillment-orders

Scope orders:read

Your fulfillment orders in this API key environment, most recently updated first, with lines and fee items. Incremental polling uses updatedSince and cursor; continue until nextCursor is null.

Confirm a fulfillment order

POST/v1/merchant/fulfillment-orders/{id}/confirm

Scope orders:write

Confirms a draft order, or retries reservation on an on_hold order after restocking — the same atomic, FIFO, all-or-nothing reservation as auto-confirm. With default auto-confirm you only need this call for draftOnly orders and for releasing holds.

Only draft and on_hold orders can be confirmed; any other state returns 409 merchant_fo_state with the current state in the message.

Cancel a fulfillment order

POST/v1/merchant/fulfillment-orders/{id}/cancel

Scope orders:write

Requests cancellation. Returns HTTP 200 only when cancellation is complete. HTTP 202 means warehouse handling or administrative review is still required; inventory and any refund are finalized only after that workflow completes.

cancellationStatus is CANCELLED (200), or WAREHOUSE_STOPPED, WAREHOUSE_RETURNED or ADMIN_REVIEW (202). HTTP 202 is not confirmation of a refund or released stock. Read the order again to follow completion.

Before warehouse work or booking, cancellation can release reservations and refund prepaid fees automatically. After work has begun, warehouse handling and administrative cost review must finish first.

A standalone order already handed over returns 409 merchant_fo_state. A channel-linked order follows its fulfillment-intent cancellation workflow and may enter administrative review.

Repeating a completed cancellation returns HTTP 200. This endpoint does not use Idempotency-Key response replay; subsequent requests reflect the current cancellation state.

Retrieve the monthly statement

GET/v1/merchant/statements

Scope finance:read

The monthly stocking bill, computed live from the same ledger as inventory — never a stored snapshot, so the statement and your stock can never disagree. Storage is billed per lot: on-hand units × the lot’s unit volume (CBM) × the per-CBM-per-day price × billable days, where billing starts only after a free period from receipt. Fulfillment fees incurred in the month are listed line by line alongside. ?month=YYYY-MM; defaults to the current month.

freeDays and pricePerCbmDay are account-level billing parameters echoed in every response — read them from your statement rather than assuming fixed values; this page intentionally promises none.

Every line is explainable: a storage line names the SKU, the on-hand quantity and the billed days; a fulfillment line is exactly the fee recorded on the order it came from.

Create a warehouse transfer

POST/v1/merchant/transfer-orders

Scope orders:write

Requests a China-to-overseas-warehouse stock transfer. The source is the active China warehouse; the destination must be an active international warehouse supplied by operations. Dispatch and receiving remain warehouse-controlled actions, and the resulting quantities appear as in transit until receiving completes. Overseas warehouse services are not open yet: until they launch this endpoint returns 403 overseas_warehouse_unavailable.

Creation returns HTTP 201 with a frozen quote and OPEN bill; warehouse execution starts after payment. Fee amounts in this example are placeholders, not a rate promise. freightPending=true means freight still requires an operational quote; it is not free shipping. This strict V1 request accepts toWarehouseId, lines and notes only.

This POST is not protected by Idempotency-Key in V1. Do not retry it automatically after an ambiguous network failure; list transfers and reconcile before creating another request.

List warehouse transfers

GET/v1/merchant/transfer-orders

Scope orders:read

Returns up to 100 transfer orders plus an inTransit summary by SKU. Use the individual lines for audit and the aggregate to avoid double-counting stock that has left China but has not yet been received overseas. Overseas warehouse services are not open yet: until they launch this endpoint returns 403 overseas_warehouse_unavailable.

Create a webhook endpoint

POST/v1/merchant/webhook-endpoints

Scope webhooks:write

Registers an HTTPS endpoint for the event types you select. The signing secret is returned exactly once — store it immediately. Up to 5 active endpoints per account.

List webhook endpoints

GET/v1/merchant/webhook-endpoints

Scope webhooks:write

Lists your endpoints with status and failure counters. Signing secrets are never returned again.

Disable a webhook endpoint

DELETE/v1/merchant/webhook-endpoints/{id}

Scope webhooks:write

Disables the endpoint. The delivery ledger is evidence and is retained; nothing is deleted.

Webhook events

Deliveries are at-least-once with bounded backoff (1 minute to 24 hours, 8 attempts); deduplicate by eventId. Sustained failures disable the endpoint, and the delivery ledger is always retained.

Verifying signatures

Every delivery is signed with your endpoint's secret: an HMAC-SHA256 over `${timestamp}.${rawBody}`. Headers: X-Woolii-Event-Id, X-Woolii-Timestamp (unix seconds), X-Woolii-Signature (v1=<hex>). Verify against the raw body before parsing.

MCP server

Let your AI agent operate forwarding directly. The WooliiPorter MCP (Model Context Protocol) server exposes the Merchant API above as agent-callable tools, so Claude, Cursor or your own copilot can pre-alert orders, estimate costs, watch the timeline, settle shipments and run the optional stocking workflow — SKUs, inbound shipments, inventory, fulfillment orders and the monthly statement — without custom glue code. It is a single zero-dependency file — Node >= 18, no install step — and it uses your existing API key with the same scopes, sandbox behavior and fool-proof value-added-service rules as raw HTTP.

Start with a sandbox key: your agent can create orders, simulate the lifecycle and settle them without moving real funds. The same constraints apply as over HTTP — label-class services still require instructions, illustrations and printable label files, and pay only succeeds once the final packed quote exists.

The agent-facing page for this server — what it calls, where autonomy stops and how to get a key — is the MCP server page. Key issuance and scoping, webhook signature verification and staff access are described at Security.

Running WooCommerce? WooliiPorter Fulfillment for WooCommerce connects the store directly to fulfillment-intent endpoints. Use the standalone MCP server to connect an authorized assistant in your own runtime with the same merchant API key and scopes.

Running Shopify? The fulfillment-service app is listed on the Shopify App Store. Install it there to handle installation, product-to-SKU linking and assigned fulfillment orders inside Shopify itself. Shopify-managed authorization connects those assigned orders to the shared fulfillment backend and sends eligible shipment updates back to the store.

WooliiPorter Fulfillment for WooCommerce

Plugin version 0.9.0 connects one WooCommerce installation to Woolii-operated fulfillment in China. Test and connect validates the account, API-key environment, required scopes and compatibility smartRouting feature flag, then registers the store. When an eligible order reaches processing, the plugin sends a versioned snapshot through Action Scheduler—never in the checkout request—and stores the fulfillment intent, per-line route facts, required action and diagnostic request ID on the WooCommerce order.

The WordPress.org listing currently offers stable version 0.9.0 through standard WordPress updates. Active merchants can download the reviewed 0.9.0 package from the Integrations workspace for the latest product-selection workflow. WordPress.org publication of that package is tracked separately from the merchant download.

The connector synchronizes store identity, order snapshots, catalog/SKU links and supplier-parcel allocations with the shared WooliiPorter backend. Its privacy disclosure explains the operational data used for those workflows.

Get access

Create a merchant login, submit business details and expected order volume, then complete human review and online signing. Your offer specifies services, freight discount and settlement currency. Shopify, WooCommerce, Amazon and direct API merchants follow the same process. Signing activates the merchant console and API-key management.

While your application is under review or awaiting signature, you can sign in, view your application and agreements, and use the public shipping calculator. API-key creation stays closed until the account is active.

Eligible existing merchant accounts retain their access without retroactive signing; no signature record is created on their behalf.

Apply for API accessOpen the developer console

The developer console manages sandbox and production keys, webhook endpoints and one-time secrets. Store every revealed secret immediately; it is not shown again.