{"openapi":"3.1.0","info":{"title":"WooliiPorter Merchant API","version":"2.2.0","description":"Merchant integration contract for product selection, forwarding, merchant-owned inventory, fulfillment, unified WooliiPorter shipments, settlement, tracking and signed webhooks. Select a public product or save an explicit default; destination coverage and parcel restrictions are validated by WooliiPorter."},"servers":[{"url":"https://api.woolii.com","description":"WooliiPorter Merchant API"}],"externalDocs":{"description":"Human-readable developer documentation","url":"https://porter.woolii.com/developers"},"tags":[{"name":"Getting started"},{"name":"WooCommerce order automation"},{"name":"Products & defaults"},{"name":"Direct forwarding API"},{"name":"Billing & settlement"},{"name":"Tracking"},{"name":"Stocking & fulfillment"},{"name":"Webhooks"},{"name":"Public tracking"}],"paths":{"/v1/merchant/connection":{"get":{"operationId":"checkConnection","summary":"Check the API connection","description":"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.","tags":["Getting started"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#check-connection"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/connection \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}]}},"/v1/merchant/stores/{externalStoreId}":{"put":{"operationId":"registerStore","summary":"Register a WooCommerce store","description":"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.","tags":["WooCommerce order automation"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#register-store"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl -X PUT https://api.woolii.com/v1/merchant/stores/wcstore_550e8400-e29b-41d4-a716-446655440000 \\\n  -H \"Authorization: Bearer wp_sk_test_...\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"platform\": \"WOOCOMMERCE\",\n    \"storeUrl\": \"https://shop.example.com/\",\n    \"pluginVersion\": \"0.8.0\",\n    \"webhookUrl\": \"https://shop.example.com/wp-json/wooliiporter/v1/webhook\"\n  }'"}],"parameters":[{"name":"externalStoreId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/v1/merchant/stores/{externalStoreId}/onboarding":{"get":{"operationId":"getStoreOnboarding","summary":"Read the store onboarding checklist","description":"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.","tags":["WooCommerce order automation"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#get-store-onboarding"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/stores/wcstore_550e8400-e29b-41d4-a716-446655440000/onboarding \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}],"parameters":[{"name":"externalStoreId","in":"path","required":true,"schema":{"type":"string"}}]}},"/v1/merchant/stores/{externalStoreId}/catalog":{"post":{"operationId":"syncStoreCatalog","summary":"Sync the WooCommerce catalog and link SKUs","description":"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.","tags":["WooCommerce order automation"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#sync-store-catalog"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl -X POST https://api.woolii.com/v1/merchant/stores/wcstore_550e8400-e29b-41d4-a716-446655440000/catalog \\\n  -H \"Authorization: Bearer wp_sk_test_...\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"products\": [\n      { \"externalProductId\": \"101\", \"externalVariationId\": \"101\", \"name\": \"Ceramic mug\", \"sku\": \"MUG-01\" }\n    ]\n  }'"}],"parameters":[{"name":"externalStoreId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/v1/merchant/console-sso":{"post":{"operationId":"createConsoleHandoff","summary":"Open the Woolii merchant console","description":"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.","tags":["WooCommerce order automation"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"console:sso","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#create-console-handoff"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl -X POST https://api.woolii.com/v1/merchant/console-sso   -H \"Authorization: Bearer wp_sk_test_...\"   -H \"Content-Type: application/json\"   -d '{\n    \"externalStoreId\": \"wcstore_550e8400-e29b-41d4-a716-446655440000\",\n    \"returnPath\": \"/merchant/integrations\"\n  }'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/v1/merchant/fulfillment-intents":{"post":{"operationId":"createFulfillmentIntent","summary":"Submit a commerce order for fulfillment","description":"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.","tags":["WooCommerce order automation"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":true,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#create-fulfillment-intent"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/fulfillment-intents \\\n  -H \"Authorization: Bearer wp_sk_test_...\" \\\n  -H \"Idempotency-Key: woocommerce:wcstore_…:1042:8f37…\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"platform\": \"WOOCOMMERCE\",\n    \"externalStoreId\": \"wcstore_550e8400-e29b-41d4-a716-446655440000\",\n    \"externalOrderId\": \"1042\",\n    \"externalOrderName\": \"WEB-001042\",\n    \"externalOrderVersion\": \"8f37…\",\n    \"productCode\": \"AIR_CARGO\",\n    \"destination\": {\n      \"recipientName\": \"Ada Merchant\", \"phone\": \"+1 415 000 0000\",\n      \"country\": \"US\", \"province\": \"CA\", \"city\": \"San Francisco\",\n      \"street\": \"1 Mission St\", \"postalCode\": \"94105\"\n    },\n    \"lines\": [\n      { \"externalLineId\": \"line-1\", \"productId\": \"501\",\n        \"productName\": \"Ceramic mug\", \"qty\": 2, \"skuCode\": \"MUG-WHT\",\n        \"fulfillmentPreference\": \"AUTO\" }\n    ]\n  }'"}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable caller-generated key. Replays return the stored response; key reuse with a different payload is rejected.","schema":{"type":"string","minLength":1,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommerceFulfillmentIntentRequest"}}}}}},"/v1/merchant/fulfillment-intents/{id}":{"get":{"operationId":"getFulfillmentIntent","summary":"Retrieve a fulfillment intent","description":"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.","tags":["WooCommerce order automation"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#get-fulfillment-intent"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommerceIntentResponse"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/fulfillment-intents/cfi_… \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/v1/merchant/fulfillment-intents/{id}/cancel":{"post":{"operationId":"cancelFulfillmentIntent","summary":"Cancel a fulfillment intent","description":"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.","tags":["WooCommerce order automation"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":true,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#cancel-fulfillment-intent"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Cancellation accepted; warehouse or administration review remains","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl -X POST https://api.woolii.com/v1/merchant/fulfillment-intents/cfi_…/cancel \\\n  -H \"Authorization: Bearer wp_sk_test_...\" \\\n  -H \"Idempotency-Key: wc-1042-cancel-v2\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"routingVersion\": 2, \"reason\": \"Customer requested cancellation\" }'"}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable caller-generated key. Replays return the stored response; key reuse with a different payload is rejected.","schema":{"type":"string","minLength":1,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/v1/merchant/fulfillment-intents/{id}/supplier-parcels":{"put":{"operationId":"saveSupplierParcels","summary":"Save supplier parcel drafts","description":"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.","tags":["WooCommerce order automation"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":true,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#save-supplier-parcels"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl -X PUT https://api.woolii.com/v1/merchant/fulfillment-intents/cfi_…/supplier-parcels \\\n  -H \"Authorization: Bearer wp_sk_test_...\" \\\n  -H \"Idempotency-Key: wc-1042-parcels-v2-8b17…\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"routingVersion\": 2,\n    \"parcels\": [\n      { \"trackingNumber\": \"SF1234567890\", \"carrier\": \"SF Express\",\n        \"lines\": [ { \"externalLineId\": \"line-1\", \"qty\": 2 } ] }\n    ]\n  }'"}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable caller-generated key. Replays return the stored response; key reuse with a different payload is rejected.","schema":{"type":"string","minLength":1,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/v1/merchant/fulfillment-intents/{id}/submit-forwarding":{"post":{"operationId":"submitIntentForwarding","summary":"Submit supplier forwarding","description":"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.","tags":["WooCommerce order automation"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":true,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#submit-intent-forwarding"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl -X POST https://api.woolii.com/v1/merchant/fulfillment-intents/cfi_…/submit-forwarding \\\n  -H \"Authorization: Bearer wp_sk_test_...\" \\\n  -H \"Idempotency-Key: wc-1042-submit-forwarding-v2-8b17…\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"routingVersion\": 2 }'"}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable caller-generated key. Replays return the stored response; key reuse with a different payload is rejected.","schema":{"type":"string","minLength":1,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/v1/merchant/fulfillment-intents/{id}/select-route":{"post":{"operationId":"selectIntentRoute","summary":"Choose how a mixed order proceeds","description":"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.","tags":["WooCommerce order automation"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":true,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#select-intent-route"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl -X POST https://api.woolii.com/v1/merchant/fulfillment-intents/cfi_…/select-route \\\n  -H \"Authorization: Bearer wp_sk_test_...\" \\\n  -H \"Idempotency-Key: wc-1042-route-v1-forward-all\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"routingVersion\": 1, \"selection\": \"FORWARD_ALL\" }'"}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable caller-generated key. Replays return the stored response; key reuse with a different payload is rejected.","schema":{"type":"string","minLength":1,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/v1/merchant/fulfillment-intents/{id}/re-evaluate":{"post":{"operationId":"reevaluateIntent","summary":"Re-evaluate stock and fulfillment readiness","description":"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.","tags":["WooCommerce order automation"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":true,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#reevaluate-intent"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl -X POST https://api.woolii.com/v1/merchant/fulfillment-intents/cfi_…/re-evaluate \\\n  -H \"Authorization: Bearer wp_sk_test_...\" \\\n  -H \"Idempotency-Key: wc-1042-reevaluate-v2\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"routingVersion\": 2 }'"}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable caller-generated key. Replays return the stored response; key reuse with a different payload is rejected.","schema":{"type":"string","minLength":1,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/v1/merchant/transport-products":{"get":{"operationId":"listTransportProducts","summary":"List shipping products and defaults","description":"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.","tags":["Products & defaults"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#list-transport-products"},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransportProductSettings"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/transport-products -H \"Authorization: Bearer wp_sk_test_...\""}]},"put":{"operationId":"saveTransportProduct","summary":"Save a default shipping product","description":"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.","tags":["Products & defaults"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#save-transport-product"},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransportProductDefaultResponse"}}}},"422":{"description":"Product-default validation error; this endpoint uses a top-level string error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransportProductError"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl -X PUT https://api.woolii.com/v1/merchant/transport-products -H \"Authorization: Bearer wp_sk_test_...\" -H \"Content-Type: application/json\" -d '{\"storeId\":\"ms_…\",\"productCode\":\"PARCEL_BATTERY\"}'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransportProductDefaultRequest"}}}}}},"/v1/merchant/routing-rules":{"get":{"operationId":"listRoutingRules","summary":"Read historical delivery rules","description":"Historical records only. These rules no longer select a product for new orders.","tags":["Products & defaults"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#list-routing-rules"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/routing-rules -H \"Authorization: Bearer wp_sk_test_...\""}]},"put":{"operationId":"replaceRoutingRules","summary":"Retired delivery-rule writes","description":"Returns HTTP 410. Use productCode on orders or save a default through /transport-products.","tags":["Products & defaults"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#replace-routing-rules"},"responses":{"410":{"description":"Delivery-rule writes retired; use productCode or /transport-products","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantError"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl -X PUT https://api.woolii.com/v1/merchant/routing-rules -H \"Authorization: Bearer wp_sk_test_...\""}]}},"/v1/merchant/orders/estimate":{"post":{"operationId":"estimateOrder","summary":"Estimate cost and transit","description":"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.","tags":["Direct forwarding API"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#estimate-order"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingEstimateResponse"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/orders/estimate \\\n  -H \"Authorization: Bearer wp_sk_test_...\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"productCode\": \"AIR_CARGO\",\n    \"destination\": { \"country\": \"US\", \"postalCode\": \"94105\" },\n    \"packages\": [\n      { \"weight\": 12.5, \"length\": 40, \"width\": 30, \"height\": 25 }\n    ],\n    \"packageTypeId\": \"1\",\n    \"services\": [ { \"type\": \"POLYBAG\", \"qty\": 24 } ]\n  }'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingEstimateRequest"}}}}}},"/v1/merchant/orders":{"post":{"operationId":"createOrder","summary":"Create an order pre-alert","description":"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.","tags":["Direct forwarding API"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":true,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#create-order"},"responses":{"201":{"description":"Resource created","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantOrderResponse"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/orders \\\n  -H \"Authorization: Bearer wp_sk_test_...\" \\\n  -H \"Idempotency-Key: order-SO-1042-v1\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"externalOrderId\": \"SO-1042\",\n    \"productCode\": \"AIR_CARGO\",\n    \"destination\": {\n      \"recipientName\": \"Ada Merchant\",\n      \"phone\": \"+1 415 000 0000\",\n      \"country\": \"US\",\n      \"province\": \"CA\",\n      \"city\": \"San Francisco\",\n      \"street\": \"1 Mission St\",\n      \"postalCode\": \"94105\"\n    },\n    \"parcels\": [\n      { \"trackingNumber\": \"SF1234567890\",\n        \"productName\": \"Ceramic mugs\",\n        \"quantity\": 24,\n        \"declaredUnitPrice\": 5,\n        \"cargoType\": \"General\" }\n    ],\n    \"shipmentType\": \"CONSOLIDATED\",\n    \"checkoutShippingMethod\": \"flat_rate:2\",\n    \"inspection\": true,\n    \"destinationType\": \"CUSTOMER\",\n    \"services\": [\n      { \"type\": \"RELABEL\",\n        \"trackingNumber\": \"SF1234567890\",\n        \"qty\": 24,\n        \"instructionText\": \"Replace the supplier barcode with the enclosed label, one per unit, over the original.\",\n        \"illustrationImages\": [\"https://cdn.example.com/relabel-expected-result.jpg\"],\n        \"labelFiles\": [\"https://cdn.example.com/labels-SO-1042.pdf\"] }\n    ]\n  }'"}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable caller-generated key. Replays return the stored response; key reuse with a different payload is rejected.","schema":{"type":"string","minLength":1,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForwardingOrderRequest"}}}}},"get":{"operationId":"listOrders","summary":"List orders","description":"Cursor-paginated list of your orders, newest first. Filter by externalOrderId, state, or updatedSince (ISO 8601).","tags":["Direct forwarding API"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#list-orders"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantOrderPage"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl \"https://api.woolii.com/v1/merchant/orders?limit=20&state=quote_ready\" \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}]}},"/v1/merchant/orders/{id}":{"get":{"operationId":"getOrder","summary":"Retrieve an order","description":"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.","tags":["Direct forwarding API"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#get-order"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantOrderResponse"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/orders/ord_cml0… \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/v1/merchant/orders/{id}/cancel":{"post":{"operationId":"cancelOrder","summary":"Cancel an order","description":"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.","tags":["Direct forwarding API"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":true,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#cancel-order"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantOrderResponse"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl -X POST https://api.woolii.com/v1/merchant/orders/ord_cml0…/cancel \\\n  -H \"Authorization: Bearer wp_sk_test_...\" \\\n  -H \"Idempotency-Key: cancel-SO-1042-v1\""}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable caller-generated key. Replays return the stored response; key reuse with a different payload is rejected.","schema":{"type":"string","minLength":1,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/v1/merchant/orders/{id}/simulate":{"post":{"operationId":"simulateOrder","summary":"Simulate a sandbox lifecycle event","description":"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.","tags":["Getting started"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#simulate-order"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantOrderResponse"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl -X POST https://api.woolii.com/v1/merchant/orders/ord_cml0…/simulate \\\n  -H \"Authorization: Bearer wp_sk_test_...\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"event\": \"quote.ready\" }'"}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/v1/merchant/countries":{"get":{"operationId":"listCountries","summary":"List shippable countries","description":"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.","tags":["Direct forwarding API"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#list-countries"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/countries \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}]}},"/v1/merchant/orders/{id}/quote":{"get":{"operationId":"getQuote","summary":"Retrieve the quote state","description":"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.","tags":["Billing & settlement"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#get-quote"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/orders/ord_cml0…/quote \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/v1/merchant/orders/{id}/settlement":{"get":{"operationId":"getSettlement","summary":"Retrieve the settlement","description":"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.","tags":["Billing & settlement"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#get-settlement"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForwardingSettlementResponse"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/orders/ord_example/settlement \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/v1/merchant/orders/{id}/wallet-payment":{"post":{"operationId":"walletPayment","summary":"Pay from the merchant wallet","description":"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.","tags":["Billing & settlement"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"finance:pay","x-woolii-idempotent":true,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#wallet-payment"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForwardingSettlementResponse"}}}},"402":{"description":"Insufficient merchant wallet balance; OPEN bill retained, no debit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantError"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl -X POST https://api.woolii.com/v1/merchant/orders/ord_example/wallet-payment \\\n  -H \"Authorization: Bearer wp_sk_live_...\" \\\n  -H \"Idempotency-Key: payment-attempt-001\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"settlementVersion\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}'"}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable caller-generated key. Replays return the stored response; key reuse with a different payload is rejected.","schema":{"type":"string","minLength":1,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletPaymentRequest"}}}}}},"/v1/merchant/orders/{id}/pay":{"post":{"operationId":"payOrder","summary":"Legacy card payment entry","description":"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.","tags":["Billing & settlement"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#pay-order"},"responses":{"200":{"description":"Sandbox simulated payment only","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Legacy production card payment unavailable; explicit wallet migration required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantError"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl -X POST https://api.woolii.com/v1/merchant/orders/ord_example/pay \\\n  -H \"Authorization: Bearer wp_sk_live_...\""}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"deprecated":true}},"/v1/merchant/orders/{id}/timeline":{"get":{"operationId":"getTimeline","summary":"Retrieve the timeline","description":"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.","tags":["Tracking"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#get-timeline"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/orders/ord_cml0…/timeline \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/v1/merchant/orders/{id}/tracking":{"get":{"operationId":"getTracking","summary":"Retrieve tracking","description":"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.","tags":["Tracking"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"tracking:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#get-tracking"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/orders/ord_cml0…/tracking \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/v1/merchant/shipments":{"get":{"operationId":"listShipments","summary":"List unified shipments","description":"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.","tags":["Tracking"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#list-shipments"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentSummaryPage"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl \"https://api.woolii.com/v1/merchant/shipments?updatedSince=2026-07-31T00%3A00%3A00Z&limit=50\" \\\n  -H \"Authorization: Bearer wp_sk_live_...\""}],"parameters":[{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from nextCursor.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1–100; default 20.","schema":{"type":"integer"}},{"name":"updatedSince","in":"query","required":false,"description":"Only shipments updated at or after this timestamp. A timezone offset is required.","schema":{"type":"string"}},{"name":"externalOrderId","in":"query","required":false,"description":"Exact merchant/store order identity.","schema":{"type":"string"}},{"name":"trackingNumber","in":"query","required":false,"description":"Exact WooliiPorter public tracking number.","schema":{"type":"string"}},{"name":"sourceType","in":"query","required":false,"description":"ORDER | FULFILLMENT_ORDER.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"PACKED | ROUTED | BOOKING_PENDING | BOOKING_UNKNOWN | BOOKED | HANDOVER_PENDING | HANDED_OVER | IN_TRANSIT | DELIVERED | CANCELLED | EXCEPTION.","schema":{"type":"string"}},{"name":"trackingStatus","in":"query","required":false,"description":"UNKNOWN | INFO_RECEIVED | HANDED_OVER | IN_TRANSIT | OUT_FOR_DELIVERY | DELIVERED | EXCEPTION | RETURNED.","schema":{"type":"string"}}]}},"/v1/merchant/shipments/{shipmentNumber}":{"get":{"operationId":"getShipment","summary":"Retrieve a unified shipment","description":"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.","tags":["Tracking"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#get-shipment"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentDetailResponse"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/shipments/WP1785571574479 \\\n  -H \"Authorization: Bearer wp_sk_live_...\""}],"parameters":[{"name":"shipmentNumber","in":"path","required":true,"schema":{"type":"string"}}]}},"/v1/merchant/shipments/{shipmentNumber}/tracking":{"get":{"operationId":"getShipmentTracking","summary":"Retrieve shipment-native tracking","description":"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.","tags":["Tracking"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"tracking:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#get-shipment-tracking"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentTrackingResponse"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/shipments/WP1785571574479/tracking \\\n  -H \"Authorization: Bearer wp_sk_live_...\""}],"parameters":[{"name":"shipmentNumber","in":"path","required":true,"schema":{"type":"string"}}]}},"/v1/merchant/skus":{"post":{"operationId":"registerSku","summary":"Register a SKU","description":"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.","tags":["Stocking & fulfillment"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#register-sku"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/skus \\\n  -H \"Authorization: Bearer wp_sk_test_...\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"skuCode\": \"MUG-CERAMIC-WHT\",\n    \"name\": \"Ceramic mug, white\",\n    \"unitWeight\": 0.4,\n    \"unitLength\": 12, \"unitWidth\": 9, \"unitHeight\": 10,\n    \"declaredValue\": 5,\n    \"customsNameEn\": \"Ceramic mug\",\n    \"hsCode\": \"691200\",\n    \"manufacturerPartNumber\": \"CM-350-W\",\n    \"gtin\": \"4006381333931\"\n  }'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkuRequest"}}}}},"get":{"operationId":"listSkus","summary":"List SKUs","description":"Your active SKUs, sorted by skuCode. Up to 500 entries are returned.","tags":["Stocking & fulfillment"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#list-skus"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/skus \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}]}},"/v1/merchant/skus/{skuCode}/cpsc":{"get":{"operationId":"getSkuCpsc","summary":"Retrieve a SKU CPSC certificate","description":"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.","tags":["Stocking & fulfillment"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#get-sku-cpsc"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkuCpscResponse"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/skus/TOY-BLOCKS-50/cpsc \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}],"parameters":[{"name":"skuCode","in":"path","required":true,"schema":{"type":"string"}}]},"put":{"operationId":"putSkuCpsc","summary":"Save a SKU CPSC certificate","description":"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.","tags":["Stocking & fulfillment"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#put-sku-cpsc"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkuCpscResponse"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl -X PUT https://api.woolii.com/v1/merchant/skus/TOY-BLOCKS-50/cpsc \\\n  -H \"Authorization: Bearer wp_sk_test_...\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"certificateType\": \"CHILDRENS_PRODUCT\",\n    \"certifierId\": \"CERT-00042\",\n    \"productId\": \"PRD-77881\",\n    \"versionId\": \"3\",\n    \"expectedVersion\": 1\n  }'"}],"parameters":[{"name":"skuCode","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkuCpscRequest"}}}}},"delete":{"operationId":"deleteSkuCpsc","summary":"Remove a SKU CPSC certificate","description":"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.","tags":["Stocking & fulfillment"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#delete-sku-cpsc"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkuCpscResponse"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl -X DELETE https://api.woolii.com/v1/merchant/skus/TOY-BLOCKS-50/cpsc \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}],"parameters":[{"name":"skuCode","in":"path","required":true,"schema":{"type":"string"}}]}},"/v1/merchant/inbound-shipments":{"post":{"operationId":"createInboundShipment","summary":"Create an inbound shipment","description":"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.","tags":["Stocking & fulfillment"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#create-inbound-shipment"},"responses":{"201":{"description":"Resource created","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundShipmentResponse"}}}},"403":{"description":"Authentication/access error, or a top-level merchant_agreement_required error when the signed agreement does not cover the requested service","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/MerchantError"},{"$ref":"#/components/schemas/InboundServiceAccessError"}]}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/inbound-shipments \\\n  -H \"Authorization: Bearer wp_sk_test_...\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"externalRef\": \"PO-2207\",\n    \"businessType\": \"STORED_FULFILLMENT\",\n    \"cartonCount\": 4,\n    \"lines\": [ { \"skuCode\": \"MUG-CERAMIC-WHT\", \"expectedQty\": 200 } ],\n    \"services\": []\n  }'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundShipmentRequest"}}}}},"get":{"operationId":"listInboundShipments","summary":"List inbound shipments","description":"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.","tags":["Stocking & fulfillment"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#list-inbound-shipments"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundShipmentPage"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/inbound-shipments \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}],"parameters":[{"name":"cursor","in":"query","required":false,"description":"Opaque versioned cursor returned as nextCursor. Database IDs are never accepted as cursors.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1–100; default 100.","schema":{"type":"integer"}}]}},"/v1/merchant/inbound-shipments/{inboundNumber}":{"get":{"operationId":"getInboundShipment","summary":"Retrieve an inbound shipment","description":"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.","tags":["Stocking & fulfillment"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#get-inbound-shipment"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundShipmentResponse"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/inbound-shipments/IB1785571574479 \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}],"parameters":[{"name":"inboundNumber","in":"path","required":true,"schema":{"type":"string"}}]}},"/v1/merchant/inventory":{"get":{"operationId":"getInventory","summary":"Retrieve inventory","description":"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=.","tags":["Stocking & fulfillment"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#get-inventory"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl \"https://api.woolii.com/v1/merchant/inventory?sku=MUG-CERAMIC-WHT\" \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}]}},"/v1/merchant/fulfillment-orders":{"post":{"operationId":"createFulfillmentOrder","summary":"Create a fulfillment order","description":"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.","tags":["Stocking & fulfillment"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#create-fulfillment-order"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"201":{"description":"Resource created","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/fulfillment-orders \\\n  -H \"Authorization: Bearer wp_sk_test_...\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"externalOrderId\": \"wc-1042\",\n    \"destination\": {\n      \"recipientName\": \"Ada Merchant\", \"phone\": \"+1 415 000 0000\",\n      \"country\": \"US\", \"province\": \"CA\", \"city\": \"San Francisco\",\n      \"street\": \"1 Mission St\", \"postalCode\": \"94105\"\n    },\n    \"lines\": [ { \"skuCode\": \"MUG-CERAMIC-WHT\", \"qty\": 24 } ],\n    \"productCode\": \"AIR_CARGO\"\n  }'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentOrderRequest"}}}}},"get":{"operationId":"listFulfillmentOrders","summary":"List fulfillment orders","description":"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.","tags":["Stocking & fulfillment"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#list-fulfillment-orders"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl \"https://api.woolii.com/v1/merchant/fulfillment-orders?updatedSince=2026-07-20T00:00:00Z\" \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}],"parameters":[{"name":"updatedSince","in":"query","required":false,"description":"ISO 8601 update timestamp.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Continuation value from nextCursor.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1–100; default 100.","schema":{"type":"integer"}}]}},"/v1/merchant/fulfillment-orders/{id}/confirm":{"post":{"operationId":"confirmFulfillment","summary":"Confirm a fulfillment order","description":"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.","tags":["Stocking & fulfillment"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#confirm-fulfillment"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl -X POST https://api.woolii.com/v1/merchant/fulfillment-orders/fo_cml5…/confirm \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/v1/merchant/fulfillment-orders/{id}/cancel":{"post":{"operationId":"cancelFulfillment","summary":"Cancel a fulfillment order","description":"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.","tags":["Stocking & fulfillment"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#cancel-fulfillment"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentCancellationResponse"}}}},"202":{"description":"Cancellation accepted; warehouse or administration review remains","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentCancellationResponse"}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl -X POST https://api.woolii.com/v1/merchant/fulfillment-orders/fo_cml5…/cancel \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/v1/merchant/statements":{"get":{"operationId":"getStatement","summary":"Retrieve the monthly statement","description":"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.","tags":["Stocking & fulfillment"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"finance:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#get-statement"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl \"https://api.woolii.com/v1/merchant/statements?month=2026-07\" \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}]}},"/v1/merchant/transfer-orders":{"post":{"operationId":"createTransferOrder","summary":"Create a warehouse transfer","description":"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.","tags":["Stocking & fulfillment"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:write","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#create-transfer-order"},"responses":{"201":{"description":"Resource created","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/transfer-orders \\\n  -H \"Authorization: Bearer wp_sk_test_...\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"toWarehouseId\": \"wh_us_west_…\",\n    \"lines\": [ { \"skuCode\": \"MUG-CERAMIC-WHT\", \"qty\": 80 } ],\n    \"notes\": \"Replenish US West inventory\"\n  }'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferOrderRequest"}}}}},"get":{"operationId":"listTransferOrders","summary":"List warehouse transfers","description":"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.","tags":["Stocking & fulfillment"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"orders:read","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#list-transfer-orders"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/transfer-orders \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}],"parameters":[{"name":"cursor","in":"query","required":false,"description":"Continuation value from nextCursor.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"1–100; default 100.","schema":{"type":"integer"}}]}},"/v1/merchant/webhook-endpoints":{"post":{"operationId":"createWebhook","summary":"Create a webhook endpoint","description":"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.","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"webhooks:write","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#create-webhook"},"responses":{"201":{"description":"Resource created","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/webhook-endpoints \\\n  -H \"Authorization: Bearer wp_sk_test_...\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"url\": \"https://example.com/webhooks/woolii\",\n    \"eventTypes\": [\"parcel.received\", \"quote.ready\",\n                   \"shipment.dispatched\", \"shipment.delivered\"]\n  }'"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}},"get":{"operationId":"listWebhooks","summary":"List webhook endpoints","description":"Lists your endpoints with status and failure counters. Signing secrets are never returned again.","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"webhooks:write","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#list-webhooks"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl https://api.woolii.com/v1/merchant/webhook-endpoints \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}]}},"/v1/merchant/webhook-endpoints/{id}":{"delete":{"operationId":"deleteWebhook","summary":"Disable a webhook endpoint","description":"Disables the endpoint. The delivery ledger is evidence and is retained; nothing is deleted.","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"x-woolii-scope":"webhooks:write","x-woolii-idempotent":false,"externalDocs":{"description":"Human-readable contract, examples and operational notes","url":"https://porter.woolii.com/developers#delete-webhook"},"responses":{"200":{"description":"Successful response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"$ref":"#/components/responses/MerchantError"},"5XX":{"$ref":"#/components/responses/MerchantError"}},"x-codeSamples":[{"lang":"Shell","source":"curl -X DELETE https://api.woolii.com/v1/merchant/webhook-endpoints/we_cml2… \\\n  -H \"Authorization: Bearer wp_sk_test_...\""}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/public/tracking/{publicTrackingNumber}":{"get":{"operationId":"getPublicTracking","summary":"Track a WooliiPorter public number","description":"Unauthenticated, rate-limited lookup for one stable WooliiPorter WP number. The response contains the WooliiPorter delivery timeline and public locations only.","tags":["Public tracking"],"security":[],"parameters":[{"name":"publicTrackingNumber","in":"path","required":true,"schema":{"type":"string","pattern":"^(?:WP[0-9]{13}|WPTRK-[A-Z0-9]{1,80})$"}}],"responses":{"200":{"description":"WooliiPorter public tracking record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicTrackingRecord"}}}},"404":{"description":"Tracking number not found"},"429":{"description":"Public lookup rate limit exceeded"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"wp_sk_test_… or wp_sk_live_…","description":"Merchant API key scoped to one account and environment."}},"headers":{"RequestId":{"description":"Bounded WooliiPorter request identifier for support and audit correlation.","schema":{"type":"string","pattern":"^req_"}}},"responses":{"MerchantError":{"description":"Stable Merchant API error envelope","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantError"}}}}},"schemas":{"CommerceIntentResponse":{"type":"object","required":["fulfillmentIntent"],"properties":{"fulfillmentIntent":{"type":"object","additionalProperties":true,"properties":{"delivery":{"$ref":"#/components/schemas/CommerceDelivery"}}}}},"CommerceDelivery":{"type":"object","required":["complete","shipments"],"description":"Current public shipment projection; complete requires every child and current parcel to be handed over and delivered. Cancelled replacement shipments are omitted.","properties":{"complete":{"type":"boolean"},"shipments":{"type":"array","items":{"type":"object","properties":{"shipmentNumber":{"type":"string"},"status":{"type":"string"},"handedOverAt":{"type":["string","null"],"format":"date-time"},"parcels":{"type":"array","items":{"type":"object","properties":{"parcelNumber":{"type":"string"},"trackingNumber":{"type":"string"},"trackingUrl":{"type":"string","format":"uri"},"trackingStatus":{"type":"string"}}}}}}}}},"WalletPaymentRequest":{"type":"object","additionalProperties":false,"required":["settlementVersion"],"properties":{"settlementVersion":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Version from the confirmed current GET /settlement response"}}},"ForwardingSettlementResponse":{"type":"object","required":["settlement"],"properties":{"settlement":{"type":"object","required":["stage","currency","lines","settlementVersion","paymentMethod","paymentBlockedReason","validForDispatch"],"properties":{"stage":{"type":"string","enum":["pending_final_quote","payable","paid","cancelled"]},"currency":{"type":"string"},"total":{"type":"number"},"note":{"type":"string"},"billId":{"type":"string"},"lines":{"type":"array","items":{"type":"object","required":["category","label","amount","currency"],"properties":{"category":{"type":"string"},"label":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"}}}},"settlementVersion":{"type":["string","null"],"pattern":"^[a-f0-9]{64}$"},"paymentMethod":{"type":"string","enum":["wallet","sandbox"]},"paymentBlockedReason":{"type":["string","null"]},"validForDispatch":{"type":"boolean","description":"Current settlement evidence only; other dispatch gates still apply. Always false in sandbox."},"payment":{"type":"object","required":["provider","status","amount","currency","refundedAmount"],"properties":{"provider":{"type":"string","enum":["wallet","sandbox"]},"status":{"type":"string","enum":["open","completed","refund_pending","partially_refunded","refunded","void"]},"amount":{"type":"number"},"currency":{"type":"string"},"paidAt":{"type":"string","format":"date-time"},"refundedAmount":{"type":"number"}}}}}}},"TransportProduct":{"type":"object","additionalProperties":false,"required":["code","nameZh","nameEn","cargoTypes","purposes","productFamily","countries"],"properties":{"code":{"type":"string"},"nameZh":{"type":"string"},"nameEn":{"type":"string"},"cargoTypes":{"type":"array","items":{"type":"string"}},"purposes":{"type":"array","items":{"type":"string"}},"productFamily":{"type":"string"},"countries":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["code","available"],"properties":{"code":{"type":"string"},"available":{"type":"boolean"}}}}}},"TransportProductSettings":{"type":"object","additionalProperties":false,"required":["defaultTransportProductCode","stores","products"],"properties":{"defaultTransportProductCode":{"type":["string","null"]},"products":{"type":"array","items":{"$ref":"#/components/schemas/TransportProduct"}},"stores":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","platform","externalStoreId","storeUrl","environment","defaultTransportProductCode"],"properties":{"id":{"type":"string"},"platform":{"type":"string"},"externalStoreId":{"type":"string"},"storeUrl":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","PRODUCTION"]},"defaultTransportProductCode":{"type":["string","null"]}}}}}},"TransportProductDefaultRequest":{"type":"object","additionalProperties":false,"required":["productCode"],"properties":{"productCode":{"type":["string","null"],"minLength":1,"maxLength":64},"storeId":{"type":"string","minLength":1,"description":"Owned store resource id in the key environment. Omit to update the shared account default."}}},"TransportProductDefaultResponse":{"type":"object","additionalProperties":false,"required":["productCode"],"properties":{"productCode":{"type":["string","null"]}}},"TransportProductError":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["transport_product_unavailable","store_not_found"]},"issues":{"type":"array","items":{"type":"object"}}}},"InboundServiceAccessError":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","const":"merchant_agreement_required"}}},"FulfillmentCancellationResponse":{"type":"object","required":["fulfillmentOrder","cancellationStatus"],"properties":{"fulfillmentOrder":{"type":"object","additionalProperties":true},"cancellationStatus":{"type":"string","enum":["CANCELLED","WAREHOUSE_STOPPED","WAREHOUSE_RETURNED","ADMIN_REVIEW"],"description":"Only CANCELLED is complete (HTTP 200). The remaining values require follow-up handling (HTTP 202)."}}},"Destination":{"type":"object","required":["recipientName","phone","country","province","city","street","postalCode"],"properties":{"recipientName":{"type":"string","minLength":1,"maxLength":120},"phone":{"type":"string","minLength":3,"maxLength":40},"country":{"type":"string","minLength":2,"maxLength":60},"province":{"type":"string","minLength":1,"maxLength":120},"city":{"type":"string","minLength":1,"maxLength":120},"street":{"type":"string","minLength":1,"maxLength":300},"postalCode":{"type":"string","minLength":2,"maxLength":20}}},"ShippingEstimateRequest":{"type":"object","additionalProperties":false,"required":["destination","packages"],"properties":{"productCode":{"type":"string","minLength":1,"maxLength":64,"description":"Explicit public product; otherwise account default, then unambiguous AIR_CARGO compatibility. No store selector."},"packageTypeId":{"type":"string","enum":["1","2","3","4"],"default":"1","description":"GENERAL / BATTERY_COSMETIC / SENSITIVE / PURE_BATTERY."},"destination":{"type":"object","required":["country","postalCode"],"properties":{"country":{"type":"string","minLength":2,"maxLength":60},"postalCode":{"type":"string","minLength":2,"maxLength":20}}},"packages":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","required":["weight","length","width","height"],"properties":{"weight":{"type":"number","exclusiveMinimum":0,"maximum":1000},"length":{"type":"number","exclusiveMinimum":0,"maximum":500},"width":{"type":"number","exclusiveMinimum":0,"maximum":500},"height":{"type":"number","exclusiveMinimum":0,"maximum":500},"batteryCount":{"type":"integer","minimum":1,"maximum":100000,"description":"Required per physical parcel for PURE_BATTERY."}}}},"services":{"type":"array","maxItems":40,"items":{"$ref":"#/components/schemas/VasRequest"}}}},"ShippingEstimateResponse":{"type":"object","required":["estimate"],"properties":{"estimate":{"type":"object","required":["currency","service","pricedAt","note","packages","vas","totals","transit"],"properties":{"currency":{"type":"string"},"service":{"type":"object","required":["carrier","code","nameZh","nameEn"],"properties":{"carrier":{"type":"string","const":"WooliiPorter"},"code":{"type":"string"},"nameZh":{"type":"string"},"nameEn":{"type":"string"}}},"pricedAt":{"type":"string","format":"date-time"},"note":{"type":"string"},"packages":{"type":"array","items":{"type":"object","required":["cost","chargeableWeight","volumetricWeight","deliveryTime","deliveryDays","additionalFees"],"properties":{"cost":{"type":"number"},"chargeableWeight":{"type":"number","description":"Chargeable weight in kg. For products priced by chargeable CBM it is max(actual weight, volume × the product's density); the billed quantity is chargeableCbm."},"volumetricWeight":{"type":["number","null"]},"deliveryTime":{"type":["string","null"]},"chargeableUnit":{"type":"string","enum":["CBM"],"description":"Present only for products priced by chargeable cubic metres (bulky sea-to-door)."},"chargeableCbm":{"type":"number","description":"Chargeable cubic metres, present with chargeableUnit CBM."},"deliveryDays":{"type":["object","null"],"properties":{"from":{"type":"integer"},"to":{"type":"integer"}}},"additionalFees":{"type":"array","items":{"type":"object"}}}}},"vas":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"stage":{"type":"string"},"qty":{"type":"integer"},"amount":{"type":"number"},"currency":{"type":"string","const":"USD"}}}},"totals":{"type":"object","required":["shipping","vas","estimatedTotal"],"properties":{"shipping":{"type":"number"},"vas":{"type":"number"},"estimatedTotal":{"type":["number","null"],"description":"Null when settlement currency is not USD; VAS lines remain USD."}}},"transit":{"type":"object","properties":{"estimates":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["CONFIGURED","NOT_CONFIGURED"]}}}}}}},"VasRequest":{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["RELABEL","REPACK","POLYBAG","BUNDLE","COMPLIANCE_STICKER","QC","PHOTO","PALLETIZE","REINFORCE","HANGTAG"]},"qty":{"type":"integer","minimum":1,"maximum":10000,"default":1},"trackingNumber":{"type":"string","minLength":4,"maxLength":64},"instructionText":{"type":"string","maxLength":2000},"illustrationImages":{"type":"array","maxItems":6,"items":{"type":"string","format":"uri"}},"labelFiles":{"type":"array","maxItems":6,"items":{"type":"string","format":"uri"}},"spec":{"type":"object","additionalProperties":true}},"description":"Label-class work requires instructions, illustrations and printable labels; REPACK and BUNDLE require instructions. See the human-readable VAS contract for stage/quantity rules."},"ForwardingOrderRequest":{"type":"object","additionalProperties":false,"required":["externalOrderId","destination","parcels"],"properties":{"externalOrderId":{"type":"string","minLength":1,"maxLength":120},"productCode":{"type":"string","minLength":1,"maxLength":64},"destination":{"$ref":"#/components/schemas/Destination"},"parcels":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["trackingNumber"],"properties":{"trackingNumber":{"type":"string","minLength":4,"maxLength":64},"productName":{"type":"string","minLength":1,"maxLength":200},"quantity":{"type":"integer","minimum":1,"maximum":10000,"default":1},"declaredUnitPrice":{"type":"number","minimum":1,"maximum":1000000,"description":"Complete customer declared per-unit value in USD; optional at intake, minimum 1 when supplied."},"cargoType":{"type":"string","enum":["General","Electronics","PureBattery","Liquid","Branded"],"default":"General"},"description":{"type":"string","maxLength":500}}}},"shipmentType":{"type":"string","enum":["SINGLE","CONSOLIDATED"],"default":"CONSOLIDATED"},"checkoutShippingMethod":{"type":"string","minLength":1,"maxLength":120},"inspection":{"type":"boolean","default":false},"services":{"type":"array","maxItems":40,"items":{"$ref":"#/components/schemas/VasRequest"}},"destinationType":{"type":"string","enum":["CUSTOMER","AMAZON_FBA"],"default":"CUSTOMER"},"fba":{"type":"object","required":["region","fulfillmentCenter"],"properties":{"region":{"type":"string","enum":["US","EU","CA","MX"]},"fulfillmentCenter":{"type":"string","minLength":2,"maxLength":20},"shipmentId":{"type":"string","maxLength":60}}},"notes":{"type":"string","maxLength":1000},"transitBandId":{"type":"string","deprecated":true,"description":"Accepted only to return HTTP 422 merchant_routing_retired."},"bandPreference":{"type":"string","enum":["CHEAPEST","FASTEST"],"deprecated":true,"description":"Returns HTTP 422 merchant_routing_retired."},"maxTransitDays":{"type":"integer","minimum":1,"maximum":365,"deprecated":true,"description":"Returns HTTP 422 merchant_routing_retired."}}},"FulfillmentOrderRequest":{"type":"object","additionalProperties":false,"required":["externalOrderId","destination","lines"],"properties":{"externalOrderId":{"type":"string","minLength":1,"maxLength":120},"productCode":{"type":"string","minLength":1,"maxLength":64},"destination":{"$ref":"#/components/schemas/Destination"},"lines":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["skuCode","qty"],"properties":{"skuCode":{"type":"string","minLength":1,"maxLength":80},"qty":{"type":"integer","minimum":1,"maximum":10000}}}},"serviceType":{"type":"string","enum":["EXPRESS","AIR_CARGO","BULK_SHIPPING"],"default":"AIR_CARGO","deprecated":true},"checkoutShippingMethod":{"type":"string","minLength":1,"maxLength":120},"draftOnly":{"type":"boolean","default":false},"notes":{"type":"string","maxLength":1000}}},"CommerceFulfillmentIntentRequest":{"type":"object","additionalProperties":false,"required":["platform","externalStoreId","externalOrderId","externalOrderVersion","destination","lines"],"properties":{"platform":{"type":"string","const":"WOOCOMMERCE"},"externalStoreId":{"type":"string","minLength":1,"maxLength":200},"externalOrderId":{"type":"string","minLength":1,"maxLength":120},"externalOrderName":{"type":"string","minLength":1,"maxLength":120},"externalOrderVersion":{"type":"string","minLength":1,"maxLength":120},"destination":{"type":"object","additionalProperties":false,"required":["recipientName","phone","country","province","city","street","postalCode"],"properties":{"recipientName":{"type":"string","minLength":1,"maxLength":120},"phone":{"type":"string","minLength":3,"maxLength":40},"country":{"type":"string","minLength":2,"maxLength":60},"province":{"type":"string","maxLength":120,"description":"May be empty when WooCommerce checkout has no region field. Preserve the address; carrier-specific requirements apply before booking."},"city":{"type":"string","minLength":1,"maxLength":120},"street":{"type":"string","minLength":1,"maxLength":300},"postalCode":{"type":"string","minLength":2,"maxLength":20}}},"productCode":{"type":"string","minLength":1,"maxLength":64},"lines":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["externalLineId","productName","qty"],"properties":{"externalLineId":{"type":"string","minLength":1,"maxLength":120},"productId":{"type":"string","minLength":1,"maxLength":120},"variationId":{"type":"string","minLength":1,"maxLength":120},"productName":{"type":"string","minLength":1,"maxLength":200},"qty":{"type":"integer","minimum":1,"maximum":100000},"skuCode":{"type":"string","minLength":1,"maxLength":80},"fulfillmentPreference":{"type":"string","enum":["AUTO","FORWARDING"]}}}},"serviceType":{"type":"string","enum":["EXPRESS","AIR_CARGO","BULK_SHIPPING"],"default":"AIR_CARGO","deprecated":true},"checkoutShippingMethod":{"type":"string","minLength":1,"maxLength":120},"currency":{"type":"string","minLength":3,"maxLength":3},"orderTotal":{"type":"number","minimum":0,"maximum":1000000000}}},"InboundShipmentRequest":{"type":"object","additionalProperties":false,"required":["cartonCount","lines"],"properties":{"externalRef":{"type":"string","maxLength":120},"origin":{"type":"object","additionalProperties":false,"required":["countryCode"],"properties":{"countryCode":{"type":"string","minLength":2,"maxLength":3},"province":{"type":"string","maxLength":120},"city":{"type":"string","maxLength":120}}},"businessType":{"type":"string","enum":["STORED_FULFILLMENT","AMAZON_FBA","MARKETPLACE_FBM"],"default":"STORED_FULFILLMENT"},"fba":{"type":"object","required":["region","fulfillmentCenter","shipmentId","destinationPostalCode","inboundPlanId"],"properties":{"region":{"type":"string","enum":["US","EU","CA","MX"]},"fulfillmentCenter":{"type":"string","minLength":2,"maxLength":80},"shipmentId":{"type":"string","minLength":1,"maxLength":120},"productCode":{"type":"string","minLength":1,"maxLength":64},"firstMileMode":{"type":"string","enum":["EXPRESS","AIR","SEA"],"default":"AIR"},"destinationCountryCode":{"type":"string","pattern":"^[A-Z]{2}$","not":{"const":"EU"}},"destinationPostalCode":{"type":"string","minLength":1,"maxLength":32},"inboundPlanId":{"type":"string","minLength":1,"maxLength":120}}},"marketplace":{"type":"object","required":["platform"],"properties":{"platform":{"type":"string","minLength":2,"maxLength":40},"storeRef":{"type":"string","maxLength":120}}},"cartonCount":{"type":"integer","minimum":1,"maximum":1000},"lines":{"type":"array","minItems":1,"maxItems":200,"items":{"type":"object","required":["skuCode","expectedQty"],"properties":{"skuCode":{"type":"string","minLength":1,"maxLength":80},"expectedQty":{"type":"integer","minimum":1,"maximum":100000}}}},"services":{"type":"array","maxItems":40,"items":{"$ref":"#/components/schemas/VasRequest"}},"notes":{"type":"string","maxLength":1000}},"allOf":[{"if":{"required":["businessType"],"properties":{"businessType":{"const":"AMAZON_FBA"}}},"then":{"required":["fba"],"properties":{"fba":{"required":["shipmentId"],"properties":{"shipmentId":{"minLength":1}}}}}}],"description":"AMAZON_FBA requires fba with a non-empty shipmentId and prep covering every declared unit. MARKETPLACE_FBM is legacy compatibility input normalized to STORED_FULFILLMENT for new stocking receipts. Each SKU appears once. An enabled dedicated FBA workflow and compatible transport product are required."},"SkuRequest":{"type":"object","additionalProperties":false,"required":["skuCode","name"],"properties":{"skuCode":{"type":"string","minLength":1,"maxLength":80},"name":{"type":"string","minLength":1,"maxLength":200},"imageUrl":{"type":"string","format":"uri"},"barcode":{"type":"string","maxLength":64},"unitWeight":{"type":"number","exclusiveMinimum":0,"maximum":500},"unitLength":{"type":"number","exclusiveMinimum":0,"maximum":500},"unitWidth":{"type":"number","exclusiveMinimum":0,"maximum":500},"unitHeight":{"type":"number","exclusiveMinimum":0,"maximum":500},"declaredValue":{"type":"number","minimum":1,"maximum":1000000,"description":"Complete customer per-unit value in USD; optional at registration, minimum 1 when supplied."},"customsNameEn":{"type":"string","maxLength":200},"hsCode":{"type":"string","maxLength":20},"manufacturerPartNumber":{"type":["string","null"],"minLength":1,"maxLength":50,"description":"Manufacturer model / part number (EU PID NS-PID). Omit to keep, null to clear."},"gtin":{"type":["string","null"],"pattern":"^(\\d{8}|\\d{12}|\\d{13}|\\d{14})$","description":"GTIN-8/12/13/14 with a valid check digit (EU PID S-PID). Omit to keep, null to clear."},"routingTags":{"type":"array","maxItems":20,"items":{"type":"string","minLength":1,"maxLength":40}},"lowStockThreshold":{"type":["integer","null"],"minimum":0,"maximum":1000000}}},"CpscFullDeclaration":{"type":"object","additionalProperties":false,"required":["attestation","productName","description","manufacturer","manufactureDate","labTestStatus","lastTestDate","labs","poc"],"description":"Complete PGA data set for a full eFiling. lotNumber requires lotAssignedBy; primaryProductId requires primaryProductIdType.","properties":{"primaryProductId":{"type":"string","minLength":1,"maxLength":19,"pattern":"^[^\\r\\n\\t]+$"},"primaryProductIdType":{"type":"string","minLength":1,"maxLength":3,"pattern":"^[^\\r\\n\\t]+$"},"attestation":{"type":"string","enum":["CPY","CPN"]},"productName":{"type":"string","minLength":1,"maxLength":250,"pattern":"^[^\\r\\n\\t]+$"},"brandName":{"type":"string","minLength":1,"maxLength":35,"pattern":"^[^\\r\\n\\t]+$"},"description":{"type":"string","minLength":1,"maxLength":70,"pattern":"^[^\\r\\n\\t]+$"},"color":{"type":"string","minLength":1,"maxLength":12,"pattern":"^[^\\r\\n\\t]+$"},"style":{"type":"string","minLength":1,"maxLength":12,"pattern":"^[^\\r\\n\\t]+$"},"manufacturer":{"type":"object","additionalProperties":false,"required":["idType","alternateId","name","addressLines","city","province","countryCode","postalCode","phone","email"],"properties":{"idType":{"type":"string","minLength":1,"maxLength":4,"pattern":"^[^\\r\\n\\t]+$"},"alternateId":{"type":"string","minLength":1,"maxLength":19,"pattern":"^[^\\r\\n\\t]+$"},"smallBatchManufacturerId":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[^\\r\\n\\t]+$"},"name":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[^\\r\\n\\t]+$"},"addressLines":{"type":"array","minItems":1,"maxItems":2,"items":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^\\r\\n\\t]+$"}},"aptNumber":{"type":"string","minLength":1,"maxLength":5,"pattern":"^[^\\r\\n\\t]+$"},"city":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[^\\r\\n\\t]+$"},"province":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[^\\r\\n\\t]+$"},"countryCode":{"type":"string","pattern":"^[A-Za-z]{2}$"},"postalCode":{"type":"string","minLength":1,"maxLength":10,"pattern":"^[^\\r\\n\\t]+$"},"phone":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[^\\r\\n\\t]+$"},"email":{"type":"string","format":"email","maxLength":50}}},"manufactureDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"productionStartDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"productionEndDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"lotNumber":{"type":"string","minLength":1,"maxLength":25,"pattern":"^[^\\r\\n\\t]+$"},"lotAssignedBy":{"type":"string","enum":["1","2"]},"pgaLineNumber":{"type":"string","pattern":"^\\d{1,3}$"},"govAgencyProgramCode":{"type":"string","minLength":1,"maxLength":3,"pattern":"^[^\\r\\n\\t]+$"},"govAgencyCode":{"type":"string","minLength":1,"maxLength":3,"pattern":"^[^\\r\\n\\t]+$"},"purposeCode":{"type":"string","maxLength":16},"commodityCode":{"type":"string","minLength":1,"maxLength":4,"pattern":"^[^\\r\\n\\t]+$"},"labTestStatus":{"type":"string","enum":["L","N"]},"lastTestDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"disclaimer":{"type":"string","enum":["A","B"]},"labs":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"object","additionalProperties":false,"required":["type","cpscId","citationCodes","name","addressLines","city","province","countryCode","postalCode","phone","email"],"properties":{"type":{"type":"string","enum":["ITL","LAB"]},"cpscId":{"type":"string","minLength":1,"maxLength":15,"pattern":"^[^\\r\\n\\t]+$"},"citationCodes":{"type":"array","minItems":1,"maxItems":200,"items":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^\\r\\n\\t]+$"}},"testReportId":{"type":"string","minLength":1,"maxLength":72,"pattern":"^[^\\r\\n\\t]+$"},"testReportUrl":{"type":"string","format":"uri","maxLength":72},"reportAccessKey":{"type":"string","minLength":1,"maxLength":72,"pattern":"^[^\\r\\n\\t]+$"},"exemptions":{"type":"array","maxItems":50,"items":{"type":"string","minLength":1,"maxLength":16,"pattern":"^[^\\r\\n\\t]+$"}},"gps":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[^\\r\\n\\t]+$"},"name":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[^\\r\\n\\t]+$"},"addressLines":{"type":"array","minItems":1,"maxItems":2,"items":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^\\r\\n\\t]+$"}},"aptNumber":{"type":"string","minLength":1,"maxLength":5,"pattern":"^[^\\r\\n\\t]+$"},"city":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[^\\r\\n\\t]+$"},"province":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[^\\r\\n\\t]+$"},"countryCode":{"type":"string","pattern":"^[A-Za-z]{2}$"},"postalCode":{"type":"string","minLength":1,"maxLength":10,"pattern":"^[^\\r\\n\\t]+$"},"phone":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[^\\r\\n\\t]+$"},"email":{"type":"string","format":"email","maxLength":50}}}},"certifier":{"type":"object","additionalProperties":false,"required":["name","addressLines","city","province","countryCode","postalCode","phone","email"],"properties":{"name":{"type":"string","minLength":1,"maxLength":32,"pattern":"^[^\\r\\n\\t]+$"},"addressLines":{"type":"array","minItems":1,"maxItems":2,"items":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^\\r\\n\\t]+$"}},"aptNumber":{"type":"string","minLength":1,"maxLength":32,"pattern":"^[^\\r\\n\\t]+$"},"city":{"type":"string","minLength":1,"maxLength":21,"pattern":"^[^\\r\\n\\t]+$"},"province":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[^\\r\\n\\t]+$"},"countryCode":{"type":"string","pattern":"^[A-Za-z]{2}$"},"postalCode":{"type":"string","minLength":1,"maxLength":9,"pattern":"^[^\\r\\n\\t]+$"},"phone":{"type":"string","minLength":1,"maxLength":15,"pattern":"^[^\\r\\n\\t]+$"},"email":{"type":"string","format":"email","maxLength":35}}},"poc":{"type":"object","additionalProperties":false,"required":["name","addressLines","city","province","countryCode","postalCode","phone","email"],"properties":{"gln":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[^\\r\\n\\t]+$"},"alternateId":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[^\\r\\n\\t]+$"},"name":{"type":"string","minLength":1,"maxLength":32,"pattern":"^[^\\r\\n\\t]+$"},"addressLines":{"type":"array","minItems":1,"maxItems":2,"items":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[^\\r\\n\\t]+$"}},"aptNumber":{"type":"string","minLength":1,"maxLength":5,"pattern":"^[^\\r\\n\\t]+$"},"city":{"type":"string","minLength":1,"maxLength":21,"pattern":"^[^\\r\\n\\t]+$"},"province":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[^\\r\\n\\t]+$"},"countryCode":{"type":"string","pattern":"^[A-Za-z]{2}$"},"postalCode":{"type":"string","minLength":1,"maxLength":9,"pattern":"^[^\\r\\n\\t]+$"},"phone":{"type":"string","minLength":1,"maxLength":15,"pattern":"^[^\\r\\n\\t]+$"},"email":{"type":"string","format":"email","maxLength":35}}}}},"SkuCpscRequest":{"type":"object","additionalProperties":false,"required":["certificateType"],"description":"certifierId, productId and versionId are sent together or not at all.","properties":{"certificateType":{"type":"string","enum":["CHILDRENS_PRODUCT","GENERAL_PRODUCT"]},"certifierId":{"anyOf":[{"type":"string","minLength":1,"maxLength":100,"pattern":"^[^\\r\\n\\t]+$"},{"type":"null"}]},"productId":{"anyOf":[{"type":"string","minLength":1,"maxLength":100,"pattern":"^[^\\r\\n\\t]+$"},{"type":"null"}]},"versionId":{"anyOf":[{"type":"string","minLength":1,"maxLength":19,"pattern":"^[^\\r\\n\\t]+$"},{"type":"null"}]},"intendedUseCode":{"anyOf":[{"type":"string","minLength":1,"maxLength":16,"pattern":"^[^\\r\\n\\t]+$"},{"type":"null"}]},"fullDeclaration":{"anyOf":[{"$ref":"#/components/schemas/CpscFullDeclaration"},{"type":"null"}]},"expectedVersion":{"type":"integer","minimum":1,"description":"certificate.version from the last read; a mismatch returns 409."}}},"SkuCpscResponse":{"type":"object","additionalProperties":false,"required":["skuCode","certificate","filing"],"properties":{"skuCode":{"type":"string"},"certificate":{"anyOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["certificateType","certifierId","productId","versionId","intendedUseCode","fullDeclaration","version","updatedAt","hasReferences"],"properties":{"certificateType":{"type":"string","enum":["CHILDRENS_PRODUCT","GENERAL_PRODUCT"]},"certifierId":{"type":["string","null"]},"productId":{"type":["string","null"]},"versionId":{"type":["string","null"]},"intendedUseCode":{"type":["string","null"]},"fullDeclaration":{"anyOf":[{"$ref":"#/components/schemas/CpscFullDeclaration"},{"type":"null"}]},"version":{"type":"integer","minimum":1},"updatedAt":{"type":"string","format":"date-time"},"hasReferences":{"type":"boolean"}}}]},"filing":{"anyOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["status","filedAt"],"properties":{"status":{"type":"string","enum":["NOT_FILED","ACCEPTED","REJECTED","UNCONFIRMED","OUTDATED"]},"filedAt":{"type":["string","null"],"format":"date-time"}}}]}}},"TransferOrderRequest":{"type":"object","additionalProperties":false,"required":["toWarehouseId","lines"],"properties":{"toWarehouseId":{"type":"string","minLength":1},"lines":{"type":"array","minItems":1,"maxItems":200,"items":{"type":"object","required":["skuCode","qty"],"properties":{"skuCode":{"type":"string","minLength":1,"maxLength":80},"qty":{"type":"integer","minimum":1,"maximum":100000}}}},"notes":{"type":"string","maxLength":1000}}},"MerchantError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId","details"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}},"PublicCarrier":{"type":"object","required":["name"],"properties":{"name":{"type":"string","const":"WooliiPorter"}},"description":"The carrier identity exposed to merchants and their customers. The selected public product and destination determine the configured transport service."},"ShipmentStatus":{"type":"string","enum":["PACKED","ROUTED","BOOKING_PENDING","BOOKING_UNKNOWN","BOOKED","HANDOVER_PENDING","HANDED_OVER","IN_TRANSIT","DELIVERED","CANCELLED","EXCEPTION"]},"ShipmentTrackingStatus":{"type":"string","enum":["UNKNOWN","INFO_RECEIVED","HANDED_OVER","IN_TRANSIT","OUT_FOR_DELIVERY","DELIVERED","EXCEPTION","RETURNED"]},"NullableTimestamp":{"type":["string","null"],"format":"date-time"},"MerchantOrderService":{"type":"object","additionalProperties":true,"required":["id","type","stage","state","qty","fee"],"properties":{"id":{"type":"string"},"type":{"type":"string","description":"The declared type in lower case, a catalog code in lower case for catalog services, or adhoc for an extra job logged by the warehouse."},"stage":{"type":"string","enum":["receive","sort","pack","putaway"]},"state":{"type":"string","enum":["draft","awaiting_approval","requested","in_progress","done","skipped","declined"]},"declineReason":{"type":"string","enum":["withdrawn","expired","customer_declined"],"description":"Present only when state is declined: withdrawn by WooliiPorter operations, expired without your decision, or declined by you. Declined services are never charged. Treat an unknown value as declined."},"qty":{"type":"integer"},"fee":{"type":"object","additionalProperties":false,"required":["amount","currency"],"properties":{"amount":{"type":"number"},"currency":{"type":"string"}}},"trackingItemId":{"type":"string"},"completedAt":{"type":"string","format":"date-time"}},"description":"One value-added job on the order. New optional fields may be added."},"MerchantOrder":{"type":"object","additionalProperties":true,"required":["id","state"],"properties":{"id":{"type":"string"},"state":{"type":"string"},"services":{"type":"array","items":{"$ref":"#/components/schemas/MerchantOrderService"}}}},"MerchantOrderResponse":{"type":"object","additionalProperties":true,"required":["order"],"properties":{"order":{"$ref":"#/components/schemas/MerchantOrder"}}},"MerchantOrderPage":{"type":"object","additionalProperties":true,"required":["orders"],"properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/MerchantOrder"}},"nextCursor":{"type":["string","null"]}}},"PublicInboundException":{"type":"object","additionalProperties":false,"required":["caseNumber","type","severity","state","message","customerActionRequired","resolution","detectedAt","updatedAt","closedAt"],"properties":{"caseNumber":{"type":"string","pattern":"^EX[0-9]{13}$"},"type":{"type":"string"},"severity":{"type":"string","enum":["hold","critical"]},"state":{"type":"string"},"message":{"type":"string","description":"Neutral WooliiPorter customer copy."},"customerActionRequired":{"type":"boolean"},"resolution":{"type":["string","null"]},"detectedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"closedAt":{"$ref":"#/components/schemas/NullableTimestamp"}},"description":"Customer-safe receiving discrepancy. Provider identity, liability, evidence and internal financial ledgers are excluded."},"InboundShipmentPublic":{"type":"object","additionalProperties":false,"required":["inboundNumber","state","businessType","source","cartons","dispatchUnits","lines","exceptions","hasBlockingException","createdAt","updatedAt"],"properties":{"inboundNumber":{"type":["string","null"],"pattern":"^IB[0-9]{13}$"},"externalRef":{"type":"string"},"state":{"type":"string"},"businessType":{"type":"string","enum":["STORED_FULFILLMENT","AMAZON_FBA","MARKETPLACE_FBM"]},"workflow":{"type":"object","additionalProperties":true},"source":{"type":"string","enum":["inbound_delivery","stored_inventory"]},"firstMile":{"type":"object","additionalProperties":false,"required":["carrier","dispatchedAt"],"properties":{"carrier":{"type":"string","const":"WooliiPorter"},"dispatchedAt":{"type":"string","format":"date-time"}},"description":"Recorded physical first-mile dispatch. Internal carrier names and booking/tracking identifiers are never returned."},"cartons":{"type":"object","additionalProperties":false,"required":["declared","received"],"properties":{"declared":{"type":["integer","null"],"minimum":0},"received":{"type":["integer","null"],"minimum":0}},"description":"Inbound delivery carton counts. Both are null for replenishment from stored inventory; use dispatchUnits for its actual packaging."},"dispatchUnits":{"type":"object","additionalProperties":false,"required":["cartons","pallets"],"properties":{"cartons":{"type":"integer","minimum":0},"pallets":{"type":"integer","minimum":0}}},"receiving":{"type":"object","additionalProperties":false,"required":["labelNumber","state","actualWeightKg","actualVolumeCbm"],"properties":{"labelNumber":{"type":"string"},"state":{"type":"string"},"receivedAt":{"type":"string","format":"date-time"},"actualWeightKg":{"type":["number","null"]},"actualVolumeCbm":{"type":["number","null"]}}},"lines":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["skuCode","name","expectedQty","receivedQty"],"properties":{"skuCode":{"type":"string"},"name":{"type":"string"},"expectedQty":{"type":"integer","minimum":1},"receivedQty":{"type":"integer","minimum":0}}}},"receivingInstructions":{"type":"object","additionalProperties":false,"required":["warehouse","address","postalCode","note"],"properties":{"warehouse":{"type":"string"},"address":{"type":"string"},"postalCode":{"type":"string"},"note":{"type":"string"}}},"exceptions":{"type":"array","items":{"$ref":"#/components/schemas/PublicInboundException"}},"hasBlockingException":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"InboundShipmentResponse":{"type":"object","additionalProperties":false,"required":["inboundShipment"],"properties":{"inboundShipment":{"$ref":"#/components/schemas/InboundShipmentPublic"}}},"InboundShipmentPage":{"type":"object","additionalProperties":false,"required":["inboundShipments","count","nextCursor"],"properties":{"inboundShipments":{"type":"array","items":{"$ref":"#/components/schemas/InboundShipmentPublic"}},"count":{"type":"integer","minimum":0},"nextCursor":{"type":["string","null"]}}},"PublicShipmentSource":{"type":"object","additionalProperties":false,"required":["type","id","externalOrderId"],"properties":{"type":{"type":"string","enum":["ORDER","FULFILLMENT_ORDER"]},"id":{"type":["string","null"]},"externalOrderId":{"type":["string","null"]}}},"PublicService":{"type":"object","additionalProperties":false,"required":["code","name"],"properties":{"code":{"type":"string"},"name":{"type":"string"}}},"MerchantSellQuote":{"type":["object","null"],"additionalProperties":false,"required":["revision","status","amount","currency","createdAt","acceptedAt","transit"],"properties":{"revision":{"type":"integer","minimum":1},"status":{"type":"string"},"amount":{"type":"string","pattern":"^[0-9]+(?:\\.[0-9]+)?$"},"currency":{"type":"string","minLength":3,"maxLength":3},"createdAt":{"type":"string","format":"date-time"},"acceptedAt":{"$ref":"#/components/schemas/NullableTimestamp"},"transit":{"type":["object","null"],"additionalProperties":false,"required":["minBusinessDays","maxBusinessDays","estimate"],"properties":{"minBusinessDays":{"type":"integer","minimum":1},"maxBusinessDays":{"type":"integer","minimum":1},"estimate":{"type":"string"}}}},"description":"Merchant sell quote only. Supplier charges, invoices and internal rate-plan data are excluded."},"ShipmentParcelSummary":{"type":"object","additionalProperties":false,"required":["parcelNumber","trackingNumber","trackingUrl","trackingStatus","quote"],"properties":{"parcelNumber":{"type":"string"},"trackingNumber":{"type":"string"},"trackingUrl":{"type":["string","null"],"format":"uri"},"trackingStatus":{"$ref":"#/components/schemas/ShipmentTrackingStatus"},"quote":{"$ref":"#/components/schemas/MerchantSellQuote"}}},"ShipmentSummary":{"type":"object","additionalProperties":false,"required":["shipmentNumber","source","carrier","service","status","sandbox","handedOverAt","deliveredAt","createdAt","updatedAt","parcels"],"properties":{"shipmentNumber":{"type":"string"},"source":{"$ref":"#/components/schemas/PublicShipmentSource"},"carrier":{"$ref":"#/components/schemas/PublicCarrier"},"service":{"$ref":"#/components/schemas/PublicService"},"status":{"$ref":"#/components/schemas/ShipmentStatus"},"sandbox":{"type":"boolean"},"handedOverAt":{"$ref":"#/components/schemas/NullableTimestamp"},"deliveredAt":{"$ref":"#/components/schemas/NullableTimestamp"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"parcels":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentParcelSummary"}}}},"ShipmentSummaryPage":{"type":"object","additionalProperties":false,"required":["shipments","nextCursor"],"properties":{"shipments":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentSummary"}},"nextCursor":{"type":["string","null"]}}},"ShipmentLine":{"type":"object","additionalProperties":false,"required":["quantity","sku","productName","externalLineId"],"properties":{"quantity":{"type":"integer","minimum":1},"sku":{"type":["string","null"]},"productName":{"type":["string","null"]},"externalLineId":{"type":["string","null"]}}},"ShipmentTrackingEvent":{"type":"object","additionalProperties":false,"required":["status","code","description","descriptionZh","location","eventAt"],"properties":{"status":{"$ref":"#/components/schemas/ShipmentTrackingStatus"},"code":{"type":"string"},"description":{"type":"string","description":"Normalized WooliiPorter customer copy in English."},"descriptionZh":{"type":"string","description":"Normalized WooliiPorter customer copy in Chinese."},"location":{"type":["string","null"]},"eventAt":{"type":"string","format":"date-time"}}},"PublicTrackingEvent":{"type":"object","additionalProperties":false,"required":["status","descriptionEn","descriptionZh","location","eventAt"],"properties":{"status":{"$ref":"#/components/schemas/ShipmentTrackingStatus"},"descriptionEn":{"type":"string"},"descriptionZh":{"type":"string"},"location":{"type":["string","null"]},"eventAt":{"type":"string","format":"date-time"}}},"PublicTrackingRecord":{"type":"object","additionalProperties":false,"required":["carrier","trackingNumber","status","updatedAt","events"],"properties":{"carrier":{"type":"string","const":"WooliiPorter"},"trackingNumber":{"type":"string","pattern":"^(?:WP[0-9]{13}|WPTRK-[A-Z0-9]{1,80})$"},"status":{"$ref":"#/components/schemas/ShipmentTrackingStatus"},"updatedAt":{"$ref":"#/components/schemas/NullableTimestamp"},"events":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/PublicTrackingEvent"}}}},"ShipmentParcelDetail":{"type":"object","additionalProperties":false,"required":["parcelNumber","trackingNumber","trackingUrl","trackingStatus","destinationCountryCode","measurement","lines","quote","events"],"properties":{"parcelNumber":{"type":"string"},"trackingNumber":{"type":"string"},"trackingUrl":{"type":["string","null"],"format":"uri"},"trackingStatus":{"$ref":"#/components/schemas/ShipmentTrackingStatus"},"destinationCountryCode":{"type":"string","minLength":2,"maxLength":2},"measurement":{"type":"object","additionalProperties":false,"required":["weightKg","lengthCm","widthCm","heightCm"],"properties":{"weightKg":{"type":"string"},"lengthCm":{"type":"string"},"widthCm":{"type":"string"},"heightCm":{"type":"string"}}},"lines":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentLine"}},"quote":{"$ref":"#/components/schemas/MerchantSellQuote"},"events":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentTrackingEvent"}}}},"ShipmentDetail":{"type":"object","additionalProperties":false,"required":["shipmentNumber","source","carrier","service","status","sandbox","handedOverAt","deliveredAt","createdAt","updatedAt","actionRequired","parcels"],"properties":{"shipmentNumber":{"type":"string"},"source":{"$ref":"#/components/schemas/PublicShipmentSource"},"carrier":{"$ref":"#/components/schemas/PublicCarrier"},"service":{"$ref":"#/components/schemas/PublicService"},"status":{"$ref":"#/components/schemas/ShipmentStatus"},"sandbox":{"type":"boolean"},"handedOverAt":{"$ref":"#/components/schemas/NullableTimestamp"},"deliveredAt":{"$ref":"#/components/schemas/NullableTimestamp"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"actionRequired":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentActionRequired"},"description":"Holds keeping a not-yet-booked shipment in the warehouse; empty otherwise. Added in 2.1.0."},"parcels":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentParcelDetail"}}}},"ShipmentActionRequired":{"type":"object","additionalProperties":false,"required":["code","message","skus"],"description":"Treat unknown codes and reasons as holds WooliiPorter resolves.","properties":{"code":{"type":"string","examples":["cpsc_filing_required"]},"message":{"type":"string"},"skus":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["skuCode","reason","merchantAction","message"],"properties":{"skuCode":{"type":"string"},"reason":{"type":"string","examples":["CERTIFICATE_REFERENCES_MISSING","FILING_PENDING","FILING_REJECTED","SERVICE_UNSUPPORTED"]},"merchantAction":{"type":"boolean","description":"true when the merchant must update data to clear the hold"},"message":{"type":"string"}}}}}},"ShipmentDetailResponse":{"type":"object","additionalProperties":false,"required":["shipment"],"properties":{"shipment":{"$ref":"#/components/schemas/ShipmentDetail"}}},"ShipmentTrackingParcel":{"type":"object","additionalProperties":false,"required":["parcelNumber","trackingNumber","trackingUrl","status","events"],"properties":{"parcelNumber":{"type":"string"},"trackingNumber":{"type":"string"},"trackingUrl":{"type":["string","null"],"format":"uri"},"status":{"$ref":"#/components/schemas/ShipmentTrackingStatus"},"events":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentTrackingEvent"}}}},"ShipmentTrackingResponse":{"type":"object","additionalProperties":false,"required":["shipmentNumber","carrier","service","status","parcels","updatedAt"],"properties":{"shipmentNumber":{"type":"string"},"carrier":{"$ref":"#/components/schemas/PublicCarrier"},"service":{"$ref":"#/components/schemas/PublicService"},"status":{"$ref":"#/components/schemas/ShipmentStatus"},"parcels":{"type":"array","items":{"$ref":"#/components/schemas/ShipmentTrackingParcel"}},"updatedAt":{"type":"string","format":"date-time"}}}}},"x-woolii-contract-version":"2026-10-28.1","x-woolii-public-carrier":"WooliiPorter","x-woolii-internal-fields-never-exposed":["carrierProvider","carrierConnection","carrierRouteDecision","providerOrderId","providerTrackingNo","providerCharge","supplierInvoice","serviceProvider","warehouseProviderRole","quarantineBin","inboundExceptionEvidence","providerPayable","rawCarrierPayload"]}