{"openapi":"3.0.3","info":{"title":"MallPlus Open Platform API","version":"1.0.0","description":"Open API for Philippine mall brand integrations. Partners integrate with catalog, orders, inventory, and fulfillment APIs via HMAC-SHA256 authentication with optional seller-scoped OAuth2.","contact":{"name":"MallPlus Developer Support","email":"support@mallplus.ph"}},"servers":[{"url":"https://open.mallplus.ph","description":"Production"},{"url":"https://sandbox.open.mallplus.ph","description":"Sandbox"}],"security":[{"hmacAuth":[]}],"tags":[{"name":"Auth","description":"OAuth2 seller authorization flow"},{"name":"Credentials","description":"Partner credential management (secret rotation)"},{"name":"Products","description":"Product catalog management"},{"name":"Categories","description":"Product categories"},{"name":"Attributes","description":"Product attribute definitions"},{"name":"Orders","description":"Order management and fulfillment"},{"name":"Inventory","description":"Inventory level management"},{"name":"Fulfillments","description":"Fulfillment tracking"},{"name":"Sellers","description":"Seller information"},{"name":"Returns","description":"Return request management"},{"name":"Shipping","description":"Shipping options"}],"paths":{"/open/v1/auth/authorize":{"get":{"summary":"Redirect seller to consent page (HMAC-signed URL)","tags":["Auth"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"}]}},"/open/v1/auth/token":{"post":{"summary":"Exchange authorization code for access + refresh tokens","tags":["Auth"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/auth/token/refresh":{"post":{"summary":"Refresh an expired access token","tags":["Auth"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/auth/revoke":{"post":{"summary":"Revoke a seller authorization","tags":["Auth"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/auth/seller-verify":{"post":{"summary":"Verify seller credentials and create authorization code","tags":["Auth"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/credentials/rotate-secret":{"post":{"summary":"Rotate sandbox client secret (old secret invalidated immediately)","tags":["Credentials"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/credentials/rotate-live-secret":{"post":{"summary":"Rotate production client secret (requires app status: live)","tags":["Credentials"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/usage":{"get":{"summary":"Get the authenticated app's API call statistics; pass granularity=daily|hourly for a time-series (daily 90d, hourly 7d, UTC buckets)","tags":["Usage"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"}]}},"/open/v1/sandbox/sellers":{"get":{"summary":"List test sellers for the authenticated sandbox app","tags":["Sandbox"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"}]},"post":{"summary":"Create a test seller in the sandbox","tags":["Sandbox"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/sandbox/buyers":{"get":{"summary":"List test buyers for the authenticated sandbox app","tags":["Sandbox"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"}]},"post":{"summary":"Create a test buyer (with shipping address) in the sandbox","tags":["Sandbox"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/sandbox/orders":{"post":{"summary":"Place a buyer-driven test order (state: PENDING)","tags":["Sandbox"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/sandbox/orders/{id}/pay-mock":{"post":{"summary":"Mock-pay a test order — chained transition PENDING → READY_TO_SHIP","tags":["Sandbox"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/sandbox/orders/{id}/deliver-mock":{"post":{"summary":"Mock-deliver a test order (buyer-side) — SHIPPED → DELIVERED","tags":["Sandbox"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/sandbox/seed":{"post":{"summary":"Re-seed default sandbox fixtures (1 seller, 1 buyer, 5 products). Idempotent — does not delete existing data.","tags":["Sandbox"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/products":{"get":{"summary":"List products with pagination","tags":["Products"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductListResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["catalog:read"]}],"x-scope":"catalog:read","x-requires-seller-token":true,"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"}]},"post":{"summary":"Create a new product","tags":["Products"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["catalog:write"]}],"x-scope":"catalog:write","x-requires-seller-token":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/products/{id}":{"get":{"summary":"Get a single product by ID","tags":["Products"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["catalog:read"]}],"x-scope":"catalog:read","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"put":{"summary":"Update an existing product. When `images` is supplied it replaces the full image set, so send the complete list.","tags":["Products"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["catalog:write"]}],"x-scope":"catalog:write","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}},"delete":{"summary":"Delete a product","tags":["Products"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["catalog:write"]}],"x-scope":"catalog:write","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/open/v1/products/{id}/variant-prices":{"get":{"summary":"List per-variant prices (original + sale) for external price mapping","tags":["Products"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["catalog:read"]}],"x-scope":"catalog:read","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/open/v1/categories":{"get":{"summary":"List product categories","tags":["Categories"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["catalog:read"]}],"x-scope":"catalog:read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"}]}},"/open/v1/categories/{id}/attributes":{"get":{"summary":"List attribute definitions for a product category","tags":["Categories"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["catalog:read"]}],"x-scope":"catalog:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/open/v1/attributes":{"get":{"summary":"List all product attribute definitions (attribute_id, name, type)","tags":["Attributes"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["catalog:read"]}],"x-scope":"catalog:read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"}]}},"/open/v1/products/bulk":{"post":{"summary":"Bulk create/update products","tags":["Products"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["catalog:write"]}],"x-scope":"catalog:write","x-requires-seller-token":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/products/{id}/price":{"put":{"summary":"Atomically update prices for one or more variants of a seller-owned product","tags":["Products"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["catalog:write"]}],"x-scope":"catalog:write","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/products/{id}/status":{"post":{"summary":"Set a product status (live, unlisted, or delisted)","tags":["Products"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["catalog:write"]}],"x-scope":"catalog:write","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/products/{id}/stock":{"put":{"summary":"Set absolute on-hand stock per variant for a product","tags":["Products"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["inventory:write"]}],"x-scope":"inventory:write","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/products/{id}/variants":{"get":{"summary":"Get a product’s variants with on-hand stock per variant","tags":["Products"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductVariantListResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["inventory:read"]}],"x-scope":"inventory:read","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/open/v1/orders":{"get":{"summary":"List orders with pagination","tags":["Orders"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderListResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:read"]}],"x-scope":"orders:read","x-requires-seller-token":true,"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"}]}},"/open/v1/orders/{id}":{"get":{"summary":"Get a single order by ID","tags":["Orders"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:read"]}],"x-scope":"orders:read","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/open/v1/orders/{id}/items":{"get":{"summary":"Get line items for an order","tags":["Orders"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:read"]}],"x-scope":"orders:read","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/open/v1/orders/{id}/shipment/eligible-dates":{"get":{"summary":"Get eligible pickup dates for an order (platform rules: Ship-By-Date cap + holiday calendar). Returns 422 once the order has shipped.","tags":["Orders"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EligiblePickupDatesResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:read"]}],"x-scope":"orders:read","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/open/v1/orders/{id}/shipment/pickup-slots":{"get":{"summary":"Get pickup slot availability for a single date on an order (?date=YYYY-MM-DD). Rule-based (cutoff/holiday/working-days, Asia/Manila); a date with no slot returns available:false, not an error.","tags":["Orders"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PickupSlotResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:read"]}],"x-scope":"orders:read","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/open/v1/orders/{id}/shipment":{"post":{"summary":"Arrange a J&T shipment for an order. Body type:pickup requires pickupAddressId + pickupDate (YYYY-MM-DD); type:dropoff requires neither (J&T PH is branchless). Returns the J&T tracking number. 422 SHIPMENT_ALREADY_ARRANGED if the order already has a booking; 422 INVALID_PICKUP_DATE for a rule-rejected date; 422 PICKUP_DATES_UNAVAILABLE once shipped.","tags":["Orders"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentArrangementResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:write"]}],"x-scope":"orders:write","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/orders/{id}/tracking":{"get":{"summary":"Get the current tracking info for an order's shipment: J&T tracking number, current status, and the latest tracking event (timestamp + location) received from J&T. Returns 422 SHIPMENT_NOT_ARRANGED when the shipment has not yet been arranged.","tags":["Orders"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderTrackingResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:read"]}],"x-scope":"orders:read","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/open/v1/orders/{id}/shipping-label":{"get":{"summary":"Get the print-ready AWB / shipping label for an order's shipment. The label is only available after shipment has been successfully arranged; format is pdf_base64 (default), url, or html. Returns 422 SHIPPING_LABEL_UNAVAILABLE when the shipment has not yet been arranged; 404 when the order is missing or belongs to another shop.","tags":["Orders"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingLabelResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:read"]}],"x-scope":"orders:read","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/open/v1/orders/{id}/ship":{"post":{"summary":"Ship an order with tracking information","tags":["Orders"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:write"]}],"x-scope":"orders:write","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/orders/{id}/cancel":{"post":{"summary":"Cancel an order","tags":["Orders"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:write"]}],"x-scope":"orders:write","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/orders/bulk-ship":{"post":{"summary":"Ship multiple orders in a single request (max 50)","tags":["Orders"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:write"]}],"x-scope":"orders:write","x-requires-seller-token":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/orders/bulk-cancel":{"post":{"summary":"Cancel multiple orders in a single request (max 50)","tags":["Orders"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:write"]}],"x-scope":"orders:write","x-requires-seller-token":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/cancellation-requests/{id}/approve":{"post":{"summary":"Approve a buyer-initiated cancellation request (cancels the order)","tags":["Cancellation-requests"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:write"]}],"x-scope":"orders:write","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/cancellation-requests/{id}/reject":{"post":{"summary":"Reject a buyer-initiated cancellation request (order stays active)","tags":["Cancellation-requests"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:write"]}],"x-scope":"orders:write","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/inventory":{"get":{"summary":"List inventory items with pagination","tags":["Inventory"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["inventory:read"]}],"x-scope":"inventory:read","x-requires-seller-token":true,"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"}]}},"/open/v1/inventory/{id}":{"put":{"summary":"Update inventory for a single item","tags":["Inventory"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["inventory:write"]}],"x-scope":"inventory:write","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/inventory/bulk-update":{"post":{"summary":"Bulk update inventory levels","tags":["Inventory"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["inventory:write"]}],"x-scope":"inventory:write","x-requires-seller-token":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/fulfillments":{"get":{"summary":"List fulfillments","tags":["Fulfillments"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentListResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["fulfillment:read"]}],"x-scope":"fulfillment:read","x-requires-seller-token":true,"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"}]},"post":{"summary":"Create a fulfillment","tags":["Fulfillments"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["fulfillment:write"]}],"x-scope":"fulfillment:write","x-requires-seller-token":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/fulfillments/{id}":{"get":{"summary":"Get a single fulfillment by ID","tags":["Fulfillments"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["fulfillment:read"]}],"x-scope":"fulfillment:read","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]},"put":{"summary":"Update a fulfillment","tags":["Fulfillments"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["fulfillment:write"]}],"x-scope":"fulfillment:write","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/sellers":{"get":{"summary":"List sellers","tags":["Sellers"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["seller:read"]}],"x-scope":"seller:read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"}]}},"/open/v1/sellers/{id}":{"get":{"summary":"Get seller details by ID","tags":["Sellers"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["seller:read"]}],"x-scope":"seller:read","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/open/v1/shop":{"get":{"summary":"Get the authenticated shop's profile (seller bound to the access token)","tags":["Shop"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["seller:read"]}],"x-scope":"seller:read","x-requires-seller-token":true,"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"}]}},"/open/v1/shop/status":{"get":{"summary":"Get the authenticated shop's live status (operability + buyer visibility) and last status-change timestamp","tags":["Shop"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["seller:read"]}],"x-scope":"seller:read","x-requires-seller-token":true,"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"}]}},"/open/v1/shop/shipping-channels":{"get":{"summary":"List shipping channels enabled for the authenticated shop (channel_id, name, enabled). Disabled channels are excluded.","tags":["Shop"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingChannelListResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:read"]}],"x-scope":"orders:read","x-requires-seller-token":true,"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"}]}},"/open/v1/seller/profile":{"get":{"summary":"Get the authenticated seller profile","tags":["Seller"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["seller:read"]}],"x-scope":"seller:read","x-requires-seller-token":true,"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"}]}},"/open/v1/returns":{"get":{"summary":"List return cases (return_refund / cancellation / failed_delivery) with type + status filters","tags":["Returns"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:read"]}],"x-scope":"orders:read","x-requires-seller-token":true,"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"}]},"post":{"summary":"Create a return request (RMA proxy) for one or more line items","tags":["Returns"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:write"]}],"x-scope":"orders:write","x-requires-seller-token":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/returns/{id}":{"get":{"summary":"Get a single return case by ID (full detail incl. dispute window + buyer evidence; 403 for cross-shop)","tags":["Returns"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:read"]}],"x-scope":"orders:read","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/open/v1/returns/{id}/approve":{"post":{"summary":"Approve a pending return request (authorises the refund workflow to the buyer)","tags":["Returns"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:write"]}],"x-scope":"orders:write","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/returns/{id}/reject":{"post":{"summary":"Reject a return request","tags":["Returns"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:write"]}],"x-scope":"orders:write","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/returns/dispute-reasons":{"get":{"summary":"List the valid dispute reason codes","tags":["Returns"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:read"]}],"x-scope":"orders:read","x-requires-seller-token":true,"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"}]}},"/open/v1/returns/{id}/approve-refund":{"post":{"summary":"Approve the refund for a received return","tags":["Returns"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:write"]}],"x-scope":"orders:write","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/returns/{id}/dispute":{"post":{"summary":"Dispute a return request with a reason code and optional supporting evidence (https URLs)","tags":["Returns"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:write"]}],"x-scope":"orders:write","x-requires-seller-token":true,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}}}},"/open/v1/shipping/options":{"get":{"summary":"List available shipping options","tags":["Shipping"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:read"]}],"x-scope":"orders:read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"}]}},"/open/v1/shipment/pickup-addresses":{"get":{"summary":"List pickup addresses registered for the authenticated shop, with per-address capability flags (pickup_eligible, dropoff_eligible).","tags":["Shipment"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PickupAddressListResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:read"]}],"x-scope":"orders:read","x-requires-seller-token":true,"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"}]}},"/open/v1/payouts":{"get":{"summary":"Per-order settlement breakdown for the authenticated seller (settled payouts only). Supports order_id, released_after, released_before, and standard pagination.","tags":["Payouts"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Validation error, or a missing/malformed required signing header (BAD_REQUEST)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid credentials, invalid signature, or expired timestamp (TIMESTAMP_EXPIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden — insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"hmacAuth":[]},{"sellerOAuth":["orders:read"]}],"x-scope":"orders:read","x-requires-seller-token":true,"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"}]}}},"components":{"securitySchemes":{"hmacAuth":{"type":"apiKey","in":"header","name":"X-MallPlus-Signature","description":"HMAC-SHA256 signature (v2). Base string: \"{timestamp}:{clientId}:{method}:{path}:{body}\". Also requires X-MallPlus-Partner-Id and X-MallPlus-Timestamp headers. Timestamp must be within 60 seconds of server time. v1 base string (without method+body) is REJECTED in production with HMAC_VERSION_DEPRECATED. Routes flagged x-requires-seller-token additionally require X-MallPlus-Access-Token + X-MallPlus-Seller-Id; HMAC-only access returns 401 SELLER_TOKEN_REQUIRED."},"sellerOAuth":{"type":"oauth2","description":"Seller-scoped access. After OAuth consent, include access_token and seller_id as X-MallPlus-Access-Token / X-MallPlus-Seller-Id headers (query-param form is deprecated). The HMAC v2 base string is the SAME as public mode — \"{timestamp}:{clientId}:{method}:{path}:{body}\"; access_token and seller_id are NOT included in the signature (MP-7894). Required for any operation flagged x-requires-seller-token (orders, inventory, returns, fulfillments, product writes, sellers/:id).","flows":{"authorizationCode":{"authorizationUrl":"/open/v1/auth/authorize","tokenUrl":"/open/v1/auth/token","refreshUrl":"/open/v1/auth/token/refresh","scopes":{"catalog:read":"Read products and categories","catalog:write":"Create, update, delete products","orders:read":"Read orders, returns, shipping options","orders:write":"Ship, cancel orders; approve/reject returns","inventory:read":"Read inventory levels","inventory:write":"Update inventory levels","fulfillment:read":"Read fulfillments","fulfillment:write":"Create and update fulfillments","seller:read":"Read seller information"}}}}},"schemas":{"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","description":"Response payload (varies by endpoint)"},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["success"]},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code","enum":["BAD_REQUEST","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION_ERROR","RATE_LIMITED","INTERNAL_ERROR","SHIP_FAILED","CANCEL_FAILED","APPROVE_FAILED","REJECT_FAILED","DISPUTE_FAILED","INVALID_TRANSITION","PICKUP_DATES_UNAVAILABLE","SHIPMENT_NOT_ARRANGED","SHIPPING_LABEL_UNAVAILABLE","SHIPMENT_ALREADY_ARRANGED","INVALID_PICKUP_DATE","TIMESTAMP_EXPIRED","SELLER_TOKEN_REQUIRED","HMAC_VERSION_DEPRECATED","INVALID_JSON","PAYLOAD_TOO_LARGE","SSRF_CHECK_FAILED","AUTH_CODE_USED","AUTH_CODE_EXPIRED","REDIRECT_URL_MISMATCH"]},"message":{"type":"string","description":"Human-readable error description"},"details":{"type":"object","additionalProperties":true,"description":"Optional machine-readable context for the error. Shape varies by code — e.g. BAD_REQUEST for missing signing headers carries { missingHeaders: string[] }."}},"required":["code","message"]}},"required":["success","error"]},"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer","example":1},"limit":{"type":"integer","example":20},"total":{"type":"integer","example":150}}},"BulkOperationResult":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"shipped":{"type":"array","items":{"type":"object","properties":{"orderId":{"type":"string"},"status":{"type":"string"}}}},"errors":{"type":"array","items":{"type":"object","properties":{"orderId":{"type":"string"},"error":{"type":"string"}}}},"summary":{"type":"object","properties":{"total":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"}}}}}}},"FulfillmentItem":{"type":"object","additionalProperties":false,"properties":{"itemId":{"type":"string"},"quantity":{"type":"integer"}},"required":["itemId","quantity"]},"FulfillmentMetadata":{"type":"object","additionalProperties":false,"description":"Allowlisted metadata. Carrier-internal fields (mailno, bill_code, sortingcode, etc.) are NOT exposed.","properties":{"tracking_number":{"type":"string"},"tracking_company":{"type":"string"}}},"Fulfillment":{"type":"object","additionalProperties":false,"description":"Partner-safe fulfillment view. Carrier-internal fields are stripped at the API boundary.","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","shipped","delivered","cancelled"]},"orderId":{"type":"string"},"trackingNumber":{"type":"string"},"trackingCompany":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentItem"}},"metadata":{"$ref":"#/components/schemas/FulfillmentMetadata"}},"required":["id","status"]},"FulfillmentResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Fulfillment"}},"required":["success","data"]},"FulfillmentListResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["success","data"]},"OrderItem":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string"},"orderId":{"type":"string"},"productId":{"type":"string"},"variantId":{"type":"string"},"title":{"type":"string"},"sku":{"type":"string"},"quantity":{"type":"integer"},"unitPrice":{"type":"integer","description":"Centavos (PHP)"},"totalPrice":{"type":"integer","description":"Centavos (PHP)"}}},"Address":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"province":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"},"phone":{"type":"string"}}},"Order":{"type":"object","additionalProperties":false,"description":"Partner-safe order view. Internal status fields and carrier-internal metadata are stripped.","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending","paid","shipped","delivered","cancelled","returned"]},"sellerId":{"type":"string"},"customerId":{"type":"string"},"email":{"type":"string"},"currency":{"type":"string"},"subtotal":{"type":"integer","description":"Centavos (PHP)"},"total":{"type":"integer","description":"Centavos (PHP)"},"tax":{"type":"integer","description":"Centavos (PHP)"},"shipping":{"type":"integer","description":"Centavos (PHP)"},"discount":{"type":"integer","description":"Centavos (PHP)"},"paymentStatus":{"type":"string"},"fulfillmentStatus":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItem"}},"fulfillments":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}},"shippingAddress":{"$ref":"#/components/schemas/Address"},"billingAddress":{"$ref":"#/components/schemas/Address"},"shipByDate":{"type":"string","format":"date-time","nullable":true,"description":"MP-10038 — ship-by SLA deadline (ISO 8601), or null when the order has no SBD. Matches the deadline shown in Seller Center."},"slaBreached":{"type":"boolean","description":"MP-10038 — true when the order is unshipped and past its shipByDate. Present only when a deadline exists; false once the order has shipped (SLA no longer applicable)."}},"required":["id","status"]},"OrderResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Order"}},"required":["success","data"]},"OrderListResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["success","data"]},"EligiblePickupDatesResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"dates":{"type":"array","description":"ISO date strings (YYYY-MM-DD) the seller may select for pickup, Asia/Manila.","items":{"type":"string","example":"2026-07-06"}},"cutoffTime":{"type":"string","description":"Same-day cutoff (HH:mm, Asia/Manila) after which pickup moves to the next business day.","example":"17:00"},"shipByDate":{"type":"string","nullable":true,"description":"The order Ship-By-Date ceiling (ISO date). null when the order has no SBD.","example":"2026-07-12"},"allowPickupOnNonWorkingDays":{"type":"boolean","description":"Whether pickups are permitted on non-working days (Sundays/holidays).","example":false},"holidayCalendarStatus":{"type":"string","enum":["ok","unavailable"],"description":"'unavailable' when the holiday calendar couldn't be loaded (dates fall back to weekday-only rules)."}},"required":["dates"]}},"required":["success","data"]},"PickupSlotResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/PickupSlot"}},"required":["success","data"]},"PickupSlot":{"type":"object","additionalProperties":false,"description":"Per-day pickup availability for a single date. Rule-based (cutoff/holiday/working-days, Asia/Manila); does not query the carrier in real time.","properties":{"date":{"type":"string","format":"date","description":"The validated pickup date (YYYY-MM-DD).","example":"2026-07-10"},"available":{"type":"boolean","description":"Whether pickup is available on this date. A false value is NOT an error — partners should select another date.","example":true},"reason":{"type":"string","description":"Present only when available is false — the rule that disqualifies the date.","example":"Pickup is not available on this day"},"cutoffTime":{"type":"string","description":"Same-day cutoff (HH:mm, Asia/Manila) the date was validated against.","example":"17:00"},"timeWindow":{"type":"object","description":"Default pickup window the partner should pre-fill when booking collection (the carrier has no slot lookup; the caller supplies the window).","properties":{"start":{"type":"string","example":"09:00"},"end":{"type":"string","example":"18:00"}},"required":["start","end"]}},"required":["date","available"]},"ShipmentArrangementResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/ShipmentArrangement"}},"required":["success","data"]},"ShipmentArrangement":{"type":"object","additionalProperties":false,"description":"Result of arranging a J&T shipment (pickup or dropoff). Carries the J&T tracking number plus the type-specific booking metadata. The carrier-internal pickup_rules + J&T environment trace are dropped at the DTO boundary.","properties":{"shipment_type":{"type":"string","enum":["pickup","dropoff"],"description":"The arrangement type that was booked.","example":"pickup"},"order_id":{"type":"string","example":"ord_01ABC"},"tracking_number":{"type":"string","description":"J&T waybill / tracking number.","example":"JTNPH1234567890"},"tracking_url":{"type":"string","nullable":true,"description":"J&T tracking URL (null when the upstream provider does not return one)."},"booking_confirmation":{"type":"object","properties":{"status":{"type":"string","enum":["confirmed"],"example":"confirmed"},"message":{"type":"string","example":"Pickup arranged successfully."},"confirmed_at":{"type":"string","format":"date-time","description":"ISO 8601 timestamp the booking was confirmed."}},"required":["status","message","confirmed_at"]},"pickup_id":{"type":"string","description":"Pickup-only. Internal pickup stamp (e.g. pickup_<waybill>)."},"estimated_pickup_time":{"type":"string","nullable":true,"description":"Pickup-only. Requested pickup date echoed by the upstream."},"branch":{"type":"object","nullable":true,"description":"Dropoff-only. Selected branch info; null when the provider is branchless (J&T PH default).","properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"operating_hours":{"type":"string"}},"required":["id","name"]},"drop_off_deadline":{"type":"string","nullable":true,"format":"date-time","description":"Dropoff-only. 3-day drop-off window expiry."}},"required":["shipment_type","order_id","tracking_number","tracking_url","booking_confirmation"]},"OrderTrackingResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/OrderTracking"}},"required":["success","data"]},"OrderTracking":{"type":"object","additionalProperties":false,"description":"Current tracking snapshot for an order's shipment. Carries the J&T waybill, the current status (status of the most recent J&T scan), and the latest tracking event with timestamp + location. Carrier-internal metadata (raw_payload, lvl1_transition, raw_status_code) is dropped at the DTO boundary.","properties":{"order_id":{"type":"string","example":"ord_01ABC"},"tracking_number":{"type":"string","description":"J&T waybill / tracking number.","example":"JTNPH1234567890"},"current_status":{"type":"string","nullable":true,"description":"Status of the most recent tracking_update event received from J&T. null when no scan events have been received yet (shipment arranged but J&T webhook not yet ingested).","example":"shipped"},"latest_event":{"nullable":true,"description":"The most recent J&T scan event (timestamp + location + status + description). null when no tracking events have been received.","allOf":[{"$ref":"#/components/schemas/TrackingEvent"}]}},"required":["order_id","tracking_number","current_status","latest_event"]},"TrackingEvent":{"type":"object","additionalProperties":false,"description":"A single J&T tracking scan. Only partner-facing fields are surfaced; carrier-internal metadata is dropped.","properties":{"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of the scan.","example":"2026-07-10T08:30:00.000Z"},"location":{"type":"string","description":"Sanitized scan location (city/province or hub label). May be empty.","example":"MNL Gateway"},"status":{"type":"string","description":"Resolved tracking status code at the time of the scan.","example":"shipped"},"description":{"type":"string","description":"Human-readable description of the scan event.","example":"Parcel picked up by carrier."}},"required":["timestamp","location","status","description"]},"ShippingLabelResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/ShippingLabel"}},"required":["success","data"]},"ShippingLabel":{"type":"object","additionalProperties":false,"description":"Print-ready AWB / shipping label for an order's shipment. Carries the J&T waybill the label was generated for, the label format (pdf_base64 | url | html), and the format-appropriate payload. Only available after shipment has been successfully arranged (422 SHIPPING_LABEL_UNAVAILABLE otherwise).","properties":{"order_id":{"type":"string","example":"ord_01ABC"},"format":{"type":"string","enum":["pdf_base64","url","html"],"description":"How `data` should be interpreted: pdf_base64 = base64-encoded PDF bytes (decode + pipe to the warehouse printer); url = a pre-signed URL the printer fetches directly; html = inline HTML label."},"data":{"type":"string","description":"Format-appropriate label payload: base64 PDF bytes, a pre-signed URL, or inline HTML. For pdf_base64, decode with a standard base64 decoder before writing to disk / printer."},"tracking_number":{"type":"string","description":"J&T waybill / tracking number the label was generated for.","example":"JTNPH1234567890"},"provider":{"type":"string","description":"Logistics provider identifier (e.g. jt for J&T Express).","example":"jt"}},"required":["order_id","format","data","tracking_number","provider"]},"PickupAddressListResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","description":"Pickup addresses registered for the authenticated shop.","items":{"$ref":"#/components/schemas/PickupAddress"}}},"required":["success","data"]},"PickupAddress":{"type":"object","additionalProperties":false,"description":"A pickup address registered for the shop.","properties":{"address_id":{"type":"string","example":"addr_01"},"name":{"type":"string","description":"Human-readable label (full_name upstream).","example":"Makati Main Warehouse"},"phone":{"type":"string","example":"+63 2 8888 1234"},"region":{"type":"string","example":"Metro Manila"},"province":{"type":"string","example":"Metro Manila"},"city":{"type":"string","example":"Makati"},"barangay":{"type":"string","example":"Bel-Air"},"postal_code":{"type":"string","example":"1209"},"detailed_address":{"type":"string","example":"2nd Floor, Bel-Air Tower, 60 Jupiter St"},"is_default":{"type":"boolean","description":"Whether this is the default pickup address.","example":true},"pickup_eligible":{"type":"boolean","description":"Always true on this endpoint — the list is pre-filtered to pickup addresses.","example":true},"dropoff_eligible":{"type":"boolean","description":"Whether the address also accepts returned goods (is_return_address upstream).","example":true}},"required":["address_id","pickup_eligible","dropoff_eligible"]},"ShippingChannelListResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","description":"Shipping channels enabled for the authenticated shop.","items":{"$ref":"#/components/schemas/ShippingChannel"}}},"required":["success","data"]},"ShippingChannel":{"type":"object","additionalProperties":false,"description":"A shipping channel enabled for the shop.","properties":{"channel_id":{"type":"string","description":"Platform-stable channel code (e.g. JT for J&T Express).","example":"JT"},"name":{"type":"string","description":"Human-readable channel name.","example":"J&T Express"},"enabled":{"type":"boolean","description":"Always true on this endpoint — the list is pre-filtered to enabled channels.","example":true}},"required":["channel_id","name","enabled"]},"ProductVariant":{"type":"object","additionalProperties":false,"description":"A single purchasable variant of a product.","properties":{"variant_id":{"type":"string"},"sku":{"type":"string","nullable":true},"price":{"type":"integer","description":"Centavos (PHP)","nullable":true},"stock_quantity":{"type":"integer","description":"Available stock on hand at the default location","nullable":true},"options":{"type":"array","description":"Variant option values (e.g. Size=M, Color=Black).","items":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","nullable":true},"value":{"type":"string","nullable":true}}}},"dimensions":{"type":"object","additionalProperties":false,"description":"Package dimensions in centimetres.","properties":{"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"}}},"weight":{"type":"number","description":"Weight in grams"}},"required":["variant_id"]},"Product":{"type":"object","additionalProperties":false,"description":"Partner-safe product view. Supplier-internal fields are stripped at the API boundary.","properties":{"id":{"type":"string"},"short_id":{"type":"string","description":"Human-friendly alternate product identifier"},"title":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["draft","published","archived"]},"sku":{"type":"string","description":"SKU of the primary variant"},"price":{"type":"integer","description":"Centavos (PHP) — primary variant price"},"stock":{"type":"integer","description":"Stock of the primary variant"},"category":{"type":"string"},"thumbnail":{"type":"string"},"images":{"type":"array","items":{"type":"string"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariant"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","title","status"]},"ProductResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Product"}},"required":["success","data"]},"ProductListResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["success","data"]},"ProductVariantListResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariant"}}},"required":["success","data"]}}}}