{ "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": { "302": { "description": "Redirect to the seller consent page", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "parameters": [ { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Partner application client ID." }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Registered redirect URI that receives the authorization response." }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1024 }, "description": "Optional opaque partner-generated value for CSRF binding. Echoed unchanged on the authorization or error redirect when supplied." } ] } }, "/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/TokenResponse" } } } }, "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" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequest" } } } } } }, "/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/RefreshTokenResponse" } } } }, "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" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenRequest" } } } } } }, "/open/v1/auth/revoke": { "post": { "summary": "Revoke a seller authorization", "tags": [ "Auth" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeAuthorizationResponse" } } } }, "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" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeAuthorizationRequest" } } } } } }, "/open/v1/auth/seller-verify": { "post": { "summary": "Verify seller credentials and request an OTP", "tags": [ "Auth" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerVerifyResponse" } } } }, "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" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerVerifyRequest" } } } } } }, "/open/v1/auth/seller-verify-otp": { "post": { "summary": "Verify seller OTP for an authorization session", "tags": [ "Auth" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerVerifyOtpResponse" } } } }, "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" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "sellerAuthSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerVerifyOtpRequest" } } } } } }, "/open/v1/auth/seller-consent": { "post": { "summary": "Create an authorization code after seller consent", "tags": [ "Auth" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerConsentResponse" } } } }, "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" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "sellerAuthSession": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } } } }, "/open/v1/auth/deny": { "post": { "summary": "Validate and return the registered redirect URL after seller denial", "tags": [ "Auth" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DenyAuthorizationResponse" } } } }, "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" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DenyAuthorizationRequest" } } } } } }, "/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/CredentialRotationResponse" } } } }, "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" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ] } }, "/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/LiveCredentialRotationResponse" } } } }, "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" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ] } }, "/open/v1/webhooks": { "get": { "summary": "List webhook subscriptions for the authenticated app", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookListResponse" } } } }, "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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "1-based page number to return." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Maximum number of records to return." } ] }, "post": { "summary": "Create a webhook subscription", "tags": [ "Webhooks" ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "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" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreateRequest" } } } } } }, "/open/v1/webhooks/{id}": { "get": { "summary": "Get a webhook subscription", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The webhook subscription ID." } ] }, "put": { "summary": "Update a webhook subscription", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The webhook subscription ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdateRequest" } } } } }, "delete": { "summary": "Delete a webhook subscription", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeleteResponse" } } } }, "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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The webhook subscription ID." } ] } }, "/open/v1/webhooks/test": { "post": { "summary": "Send a synthetic event to an active webhook subscription", "tags": [ "Webhooks" ], "responses": { "202": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestResponse" } } } }, "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" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestRequest" } } } } } }, "/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/UsageResponse" } } } }, "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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Start of the filter window as an ISO-8601 timestamp." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "End of the filter window as an ISO-8601 timestamp." }, { "name": "endpoint", "in": "query", "schema": { "type": "string" }, "description": "Endpoint path or route pattern to filter usage and access-log rows." }, { "name": "granularity", "in": "query", "schema": { "type": "string", "enum": [ "daily", "hourly" ] }, "description": "Time-series bucket size for usage metrics." } ] } }, "/open/v1/logs": { "get": { "summary": "List the authenticated app's access logs with endpoint, status code, and ISO timestamp-range filters", "tags": [ "Logs" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessLogListResponse" } } } }, "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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "1-based page number to return." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Maximum number of records to return." }, { "name": "endpoint", "in": "query", "schema": { "type": "string" }, "description": "Endpoint path or route pattern to filter usage and access-log rows." }, { "name": "status_code", "in": "query", "schema": { "type": "integer" }, "description": "HTTP status code used to filter access-log rows." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Start of the filter window as an ISO-8601 timestamp." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "End of the filter window as an ISO-8601 timestamp." } ] } }, "/open/v1/authorizations": { "get": { "summary": "List the seller authorizations granted to the calling app (seller_id, scopes, granted_at, expires_at). Defaults to status=active; pass status=all|revoked|expired for the full history. This is the partner-facing source of the seller_id values used by seller-token calls and POST /auth/revoke.", "tags": [ "Authorizations" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationListResponse" } } } }, "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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "1-based page number to return." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Maximum number of records to return." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "revoked", "expired", "all" ], "default": "active" }, "description": "Resource status to include in the list." } ] } }, "/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/SandboxSellerListResponse" } } } }, "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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "1-based page number to return." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Maximum number of records to return." } ] }, "post": { "summary": "Create a test seller in the sandbox", "tags": [ "Sandbox" ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSellerResponse" } } } }, "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" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSellerCreateRequest" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key, generated per request, used to safely retry this call.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/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/SandboxBuyerListResponse" } } } }, "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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "1-based page number to return." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Maximum number of records to return." } ] }, "post": { "summary": "Create a test buyer (with shipping address) in the sandbox", "tags": [ "Sandbox" ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxBuyerResponse" } } } }, "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" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxBuyerCreateRequest" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key, generated per request, used to safely retry this call.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/open/v1/sandbox/orders": { "get": { "summary": "List test orders for the authenticated sandbox app", "tags": [ "Sandbox" ], "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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ] }, "post": { "summary": "Place a buyer-driven test order (state: PENDING)", "tags": [ "Sandbox" ], "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" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxOrderRequest" } } } } } }, "/open/v1/sandbox/orders/{id}": { "get": { "summary": "Get a sandbox test order by ID", "tags": [ "Sandbox" ], "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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The sandbox order ID." } ] } }, "/open/v1/sandbox/orders/{id}/tracking": { "get": { "summary": "Get a sandbox test order's handover/tracking status after a mock booking or shipment.", "tags": [ "Sandbox" ], "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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The sandbox order ID." } ] } }, "/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/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" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The sandbox order ID." } ] } }, "/open/v1/sandbox/orders/{id}/process-mock": { "post": { "summary": "Mock-process a test order — READY_TO_SHIP → PROCESSED, with a sandbox tracking number.", "tags": [ "Sandbox" ], "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" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The sandbox order ID." } ] } }, "/open/v1/sandbox/orders/{id}/ship-mock": { "post": { "summary": "Mock-ship a test order — READY_TO_SHIP → SHIPPED", "tags": [ "Sandbox" ], "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" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The sandbox order ID." } ] } }, "/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/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" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The sandbox order ID." } ] } }, "/open/v1/sandbox/seed": { "post": { "summary": "Re-seed default sandbox fixtures (1 seller, 1 buyer, 7 products). Idempotent — does not delete existing data.", "tags": [ "Sandbox" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSeedResponse" } } } }, "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" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSeedRequest" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key, generated per request, used to safely retry this call.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/open/v1/jobs/{jobId}": { "get": { "summary": "Poll a tenant-scoped asynchronous bulk job. Required operation scope is derived from the persisted operation.", "tags": [ "Jobs" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJobResponse" } } } }, "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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "x-requires-seller-token": true, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The asynchronous bulk job ID returned when the bulk operation was accepted." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "0-based item offset for this asynchronous job result page." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 }, "description": "Maximum number of records to return." } ] } }, "/open/v1/jobs/{jobId}/cancel": { "post": { "summary": "Cancel a pending or processing asynchronous bulk job. Returns 409 CONFLICT when the job is already terminal. Required operation scope is derived from the persisted operation.", "tags": [ "Jobs" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJobResponse" } } } }, "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" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "x-requires-seller-token": true, "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The asynchronous bulk job ID returned when the bulk operation was accepted." } ] } }, "/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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Product listing is available with limited support for deep cursor traversal.", "x-availability": "limited", "x-workaround": "Use returned pages as-is; contact MallPlus before relying on deep cursor traversal for high-volume sync.", "security": [ { "hmacAuth": [], "sellerOAuth": [ "catalog:read" ] } ], "x-scope": "catalog:read", "x-requires-seller-token": true, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "1-based page number to return." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Maximum number of records to return." }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Requested page size. When omitted, the endpoint uses the standard limit value." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search text used to filter products by partner-visible product fields." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "live", "unlisted", "delisted", "proposed", "under_review", "archived", "published", "draft" ] }, "description": "Product status to include in the list. Accepts every status a product can be observed in — settable by the partner: live, unlisted, delisted; read-only, set by the platform: proposed, under_review, archived. Deprecated aliases accepted for compatibility: published (= live), draft (= unlisted)." }, { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Product category ID or category slug used to filter products." }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "created_at_asc", "created_at_desc", "price_asc", "price_desc" ] }, "description": "Product sort order. Supported values sort by creation time or price." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pagination cursor returned by a previous response page." } ] }, "post": { "summary": "Create a new product", "tags": [ "Products" ], "responses": { "201": { "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" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "catalog:write" ] } ], "x-scope": "catalog:write", "x-requires-seller-token": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCreateRequest" } } } } } }, "/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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "catalog:read" ] } ], "x-scope": "catalog:read", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The product ID." } ] }, "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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "catalog:write" ] } ], "x-scope": "catalog:write", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The product ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductUpdateRequest" } } } } }, "delete": { "summary": "Delete a product", "tags": [ "Products" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDeleteResponse" } } } }, "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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "catalog:write" ] } ], "x-scope": "catalog:write", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The product ID." } ] } }, "/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/VariantPriceListResponse" } } } }, "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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Variant price lookup is available with limited seller-ownership confirmation.", "x-availability": "limited", "x-workaround": "Confirm seller ownership in Seller Center before updating prices.", "security": [ { "hmacAuth": [], "sellerOAuth": [ "catalog:read" ] } ], "x-scope": "catalog:read", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The product ID." } ] } }, "/open/v1/categories": { "get": { "summary": "List product categories", "tags": [ "Categories" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryListResponse" } } } }, "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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "x-scope": "catalog:read", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "1-based page number to return." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Maximum number of records to return." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pagination cursor returned by a previous response 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/CategoryAttributeListResponse" } } } }, "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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "x-scope": "catalog:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The product category ID." } ] } }, "/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/AttributeListResponse" } } } }, "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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "x-scope": "catalog:read", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "1-based page number to return." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Maximum number of records to return." } ] } }, "/open/v1/products/bulk": { "post": { "summary": "Bulk create/update products", "tags": [ "Products" ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductBulkCreateResponse" } } } }, "202": { "description": "Asynchronous job accepted", "headers": { "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "integer", "example": 5 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJobAcceptedResponse" } } } }, "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" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is well-formed but cannot be processed in the resource’s current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "catalog:write" ] } ], "x-scope": "catalog:write", "x-requires-seller-token": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductBulkRequest" } } } } } }, "/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/VariantPriceUpdateResponse" } } } }, "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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "catalog:write" ] } ], "x-scope": "catalog:write", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The product ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductPriceUpdateRequest" } } } } } }, "/open/v1/products/{id}/status": { "post": { "summary": "Set a product status (live, unlisted, delisted) — the read-only statuses are rejected with 400", "tags": [ "Products" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductStatusUpdateResponse" } } } }, "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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "catalog:write" ] } ], "x-scope": "catalog:write", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The product ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductStatusUpdateRequest" } } } } } }, "/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/VariantStockUpdateResponse" } } } }, "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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "inventory:write" ] } ], "x-scope": "inventory:write", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The product ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductStockUpdateRequest" } } } } } }, "/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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "inventory:read" ] } ], "x-scope": "inventory:read", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The product ID." } ] } }, "/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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Order listing is available with limited filtering and sorting support.", "x-availability": "limited", "x-workaround": "Use unfiltered order export for now, then filter in your system.", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:read" ] } ], "x-scope": "orders:read", "x-requires-seller-token": true, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "1-based page number to return." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Maximum number of records to return." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "READY_TO_SHIP", "SHIPPED", "DELIVERED", "CANCELLED", "RETURN_REFUND" ] }, "description": "Order status to include in the list." }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Return records created at or after this ISO-8601 timestamp." }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Return records created before this ISO-8601 timestamp." }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "created_at_asc", "created_at_desc" ] }, "description": "Order sort order. Supported values sort by creation time." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pagination cursor returned by a previous response 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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:read" ] } ], "x-scope": "orders:read", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The order ID." } ] } }, "/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/OrderItemListResponse" } } } }, "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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:read" ] } ], "x-scope": "orders:read", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The order ID." } ] } }, "/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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is well-formed but cannot be processed in the resource’s current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:read" ] } ], "x-scope": "orders:read", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The order ID." } ] } }, "/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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is well-formed but cannot be processed in the resource’s current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:read" ] } ], "x-scope": "orders:read", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The order ID." }, { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "description": "Pickup date to validate as an ISO calendar date in YYYY-MM-DD format." } ] } }, "/open/v1/orders/{id}/shipment": { "post": { "summary": "Arrange a shipment for an order. Body type:pickup requires pickupAddressId + pickupDate (YYYY-MM-DD); type:dropoff requires neither. Returns the carrier 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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is well-formed but cannot be processed in the resource’s current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Arrange a carrier pickup or dropoff shipment for an order owned by the authenticated seller. An Idempotency-Key is required.", "x-availability": "limited", "x-workaround": "Arrange shipment in Seller Center for now.", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:write" ] } ], "x-scope": "orders:write", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The order ID." }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key, generated per request, used to safely retry this call.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentArrangementRequest" } } } } } }, "/open/v1/orders/{id}/tracking": { "get": { "summary": "Get the current tracking info for an order's shipment: carrier tracking number, current status, and the latest tracking event (timestamp + location) received from the carrier. 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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is well-formed but cannot be processed in the resource’s current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:read" ] } ], "x-scope": "orders:read", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The order ID." } ] } }, "/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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is well-formed but cannot be processed in the resource’s current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:read" ] } ], "x-scope": "orders:read", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The order ID." }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "pdf_base64", "url", "html" ] }, "description": "Shipping-label format to return." } ] } }, "/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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is well-formed but cannot be processed in the resource’s current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Single-order shipping is available with limited production-readiness confirmation.", "x-availability": "limited", "x-workaround": "Arrange and ship in Seller Center for now.", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:write" ] } ], "x-scope": "orders:write", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The order ID." }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key, generated per request, used to safely retry this call.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderShipRequest" } } } } } }, "/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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is well-formed but cannot be processed in the resource’s current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:write" ] } ], "x-scope": "orders:write", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The order ID." }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key, generated per request, used to safely retry this call.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/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/BulkOrderShipResponse" } } } }, "202": { "description": "Asynchronous job accepted", "headers": { "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "integer", "example": 5 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJobAcceptedResponse" } } } }, "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" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is well-formed but cannot be processed in the resource’s current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Bulk order shipping is available with limited production-readiness confirmation.", "x-availability": "limited", "x-workaround": "Arrange and ship in Seller Center for now; avoid bulk API shipping for production cutover until confirmed.", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:write" ] } ], "x-scope": "orders:write", "x-requires-seller-token": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderBulkShipRequest" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key, generated per request, used to safely retry this call.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/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/BulkOrderCancelResponse" } } } }, "202": { "description": "Asynchronous job accepted", "headers": { "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "integer", "example": 5 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJobAcceptedResponse" } } } }, "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" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is well-formed but cannot be processed in the resource’s current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:write" ] } ], "x-scope": "orders:write", "x-requires-seller-token": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderBulkCancelRequest" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key, generated per request, used to safely retry this call.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/open/v1/inventory": { "get": { "summary": "List inventory items with pagination", "tags": [ "Inventory" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryItemListResponse" } } } }, "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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "inventory:read" ] } ], "x-scope": "inventory:read", "x-requires-seller-token": true, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "1-based page number to return." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Maximum number of records to return." }, { "name": "sku", "in": "query", "schema": { "type": "string" }, "description": "Seller SKU used to filter inventory items." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pagination cursor returned by a previous response 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/InventoryItemResponse" } } } }, "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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Single inventory updates are available with limited exact-stock confirmation.", "x-availability": "limited", "x-workaround": "Update stock in Seller Center for now when exact stock checks are required.", "security": [ { "hmacAuth": [], "sellerOAuth": [ "inventory:write" ] } ], "x-scope": "inventory:write", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The inventory item ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryUpdateRequest" } } } } } }, "/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/InventoryBulkUpdateResponse" } } } }, "202": { "description": "Asynchronous job accepted", "headers": { "Location": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "integer", "example": 5 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJobAcceptedResponse" } } } }, "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" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Bulk inventory updates are available with limited batch confirmation.", "x-availability": "limited", "x-workaround": "Use Seller Center or smaller verified batches for stock updates for now.", "security": [ { "hmacAuth": [], "sellerOAuth": [ "inventory:write" ] } ], "x-scope": "inventory:write", "x-requires-seller-token": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryBulkUpdateRequest" } } } } } }, "/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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Fulfillment listing is available with limited pagination confirmation.", "x-availability": "limited", "x-workaround": "Use Seller Center fulfillment views for reconciliation for now.", "security": [ { "hmacAuth": [], "sellerOAuth": [ "fulfillment:read" ] } ], "x-scope": "fulfillment:read", "x-requires-seller-token": true, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "1-based page number to return." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Maximum number of records to return." }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Fulfillment status to include in the list." }, { "name": "order_id", "in": "query", "schema": { "type": "string" }, "description": "Order ID used to filter related records." }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Return records created before this ISO-8601 timestamp." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pagination cursor returned by a previous response page." } ] }, "post": { "summary": "Create a fulfillment", "tags": [ "Fulfillments" ], "responses": { "201": { "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" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is well-formed but cannot be processed in the resource’s current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Fulfillment creation is available with limited production-readiness confirmation.", "x-availability": "limited", "x-workaround": "Create fulfillments in Seller Center for now.", "security": [ { "hmacAuth": [], "sellerOAuth": [ "fulfillment:write" ] } ], "x-scope": "fulfillment:write", "x-requires-seller-token": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillmentCreateRequest" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key, generated per request, used to safely retry this call.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Fulfillment detail lookup is available with limited production-readiness confirmation.", "x-availability": "limited", "x-workaround": "Check fulfillment details in Seller Center for now.", "security": [ { "hmacAuth": [], "sellerOAuth": [ "fulfillment:read" ] } ], "x-scope": "fulfillment:read", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The fulfillment ID." } ] }, "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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is well-formed but cannot be processed in the resource’s current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Fulfillment updates are available with limited production-readiness confirmation.", "x-availability": "limited", "x-workaround": "Update fulfillments in Seller Center for now.", "security": [ { "hmacAuth": [], "sellerOAuth": [ "fulfillment:write" ] } ], "x-scope": "fulfillment:write", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The fulfillment ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FulfillmentUpdateRequest" } } } } } }, "/open/v1/sellers": { "get": { "summary": "List sellers", "tags": [ "Sellers" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerListResponse" } } } }, "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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "x-scope": "seller:read", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "1-based page number to return." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Maximum number of records to return." } ] } }, "/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/SellerResponse" } } } }, "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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "seller:read" ] } ], "x-scope": "seller:read", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The seller ID." } ] } }, "/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/ShopResponse" } } } }, "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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "seller:read" ] } ], "x-scope": "seller:read", "x-requires-seller-token": true } }, "/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/ShopStatusResponse" } } } }, "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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "seller:read" ] } ], "x-scope": "seller:read", "x-requires-seller-token": true } }, "/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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:read" ] } ], "x-scope": "orders:read", "x-requires-seller-token": true } }, "/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/SellerProfileResponse" } } } }, "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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "seller:read" ] } ], "x-scope": "seller:read", "x-requires-seller-token": true } }, "/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/ReturnCaseListResponse" } } } }, "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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:read" ] } ], "x-scope": "orders:read", "x-requires-seller-token": true, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "1-based page number to return." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Maximum number of records to return." }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "return_refund", "cancellation", "failed_delivery" ] }, "description": "Return case type to include in the list." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "approved", "disputed", "resolved" ] }, "description": "Return case status to include in the list." }, { "name": "order_id", "in": "query", "schema": { "type": "string" }, "description": "Order ID used to filter related records." }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Return records created before this ISO-8601 timestamp." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pagination cursor returned by a previous response page." } ] }, "post": { "summary": "Create a return request (RMA proxy) for one or more line items", "tags": [ "Returns" ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnResponse" } } } }, "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" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is well-formed but cannot be processed in the resource’s current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Return creation is not yet available through the Open API.", "x-availability": "not-yet", "x-workaround": "Create the return in Seller Center for now.", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:write" ] } ], "x-scope": "orders:write", "x-requires-seller-token": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnCreateRequest" } } } } } }, "/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/ReturnResponse" } } } }, "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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:read" ] } ], "x-scope": "orders:read", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The return case ID." } ] } }, "/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/ReturnResponse" } } } }, "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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is well-formed but cannot be processed in the resource’s current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Return approval is available with limited production-readiness confirmation.", "x-availability": "limited", "x-workaround": "Process return approval in Seller Center for now.", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:write" ] } ], "x-scope": "orders:write", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The return case ID." } ] } }, "/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/ReturnResponse" } } } }, "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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is well-formed but cannot be processed in the resource’s current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Return rejection is available with limited reason-handling support.", "x-availability": "limited", "x-workaround": "Process return rejection in Seller Center or partner support workflow for now.", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:write" ] } ], "x-scope": "orders:write", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The return case ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnRejectRequest" } } } } } }, "/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/DisputeReasonListResponse" } } } }, "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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:read" ] } ], "x-scope": "orders:read", "x-requires-seller-token": true } }, "/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/ReturnResponse" } } } }, "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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is well-formed but cannot be processed in the resource’s current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Refund approval is available with limited production-readiness confirmation.", "x-availability": "limited", "x-workaround": "Process refund approval in Seller Center for now.", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:write" ] } ], "x-scope": "orders:write", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The return case ID." }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key, generated per request, used to safely retry this call.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/open/v1/returns/{id}/dispute": { "post": { "summary": "Dispute a return request with a reason code and seller evidence attachments", "tags": [ "Returns" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnResponse" } } } }, "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" } } } }, "404": { "description": "The requested resource does not exist or is not visible to the authenticated seller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The request conflicts with the current resource state or reuses an idempotency key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "The request body exceeds the endpoint payload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The request is well-formed but cannot be processed in the resource’s current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Return dispute filing is available with limited production-readiness confirmation.", "x-availability": "limited", "x-workaround": "File and manage the dispute in Seller Center for now.", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:write" ] } ], "x-scope": "orders:write", "x-requires-seller-token": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The return case ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReturnDisputeRequest" } } } } } }, "/open/v1/shipping/options": { "get": { "summary": "List available shipping options", "tags": [ "Shipping" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingOptionListResponse" } } } }, "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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [] } ], "x-scope": "orders:read", "parameters": [ { "name": "origin_region", "in": "query", "schema": { "type": "string" }, "description": "Origin region using PSGC-aligned Philippine geography." }, { "name": "origin_province", "in": "query", "schema": { "type": "string" }, "description": "Origin province using PSGC-aligned Philippine geography." }, { "name": "origin_city", "in": "query", "schema": { "type": "string" }, "description": "Origin city or municipality using PSGC-aligned Philippine geography." }, { "name": "destination_region", "in": "query", "schema": { "type": "string" }, "description": "Destination region using PSGC-aligned Philippine geography." }, { "name": "destination_province", "in": "query", "schema": { "type": "string" }, "description": "Destination province using PSGC-aligned Philippine geography." }, { "name": "destination_city", "in": "query", "schema": { "type": "string" }, "description": "Destination city or municipality using PSGC-aligned Philippine geography." }, { "name": "actual_weight", "in": "query", "schema": { "type": "number", "minimum": 0, "exclusiveMinimum": true }, "description": "Package actual weight in grams." }, { "name": "length", "in": "query", "schema": { "type": "number", "minimum": 0, "exclusiveMinimum": true }, "description": "Package length in centimetres." }, { "name": "width", "in": "query", "schema": { "type": "number", "minimum": 0, "exclusiveMinimum": true }, "description": "Package width in centimetres." }, { "name": "height", "in": "query", "schema": { "type": "number", "minimum": 0, "exclusiveMinimum": true }, "description": "Package height in centimetres." }, { "name": "insurance_enabled", "in": "query", "schema": { "type": "boolean" }, "description": "Whether to include shipping insurance in the quote." }, { "name": "order_amount", "in": "query", "schema": { "type": "number", "minimum": 0 }, "description": "Order amount used for the quote. Send an integer-valued amount in PHP centavos." } ] } }, "/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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-availability": "available", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:read" ] } ], "x-scope": "orders:read", "x-requires-seller-token": true } }, "/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" } } } }, "429": { "description": "The partner or endpoint rate limit has been exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The upstream commerce service rejected the request or returned an invalid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "A required platform or upstream dependency is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "The upstream commerce service did not respond before the platform timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Payout listing is available with limited multi-page filtering confirmation.", "x-availability": "limited", "x-workaround": "Use Seller Center payout reports for reconciliation for now.", "security": [ { "hmacAuth": [], "sellerOAuth": [ "orders:read" ] } ], "x-scope": "orders:read", "x-requires-seller-token": true, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "1-based page number to return." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 200 }, "description": "Maximum number of records to return." }, { "name": "order_id", "in": "query", "schema": { "type": "string" }, "description": "Order ID used to filter related records." }, { "name": "released_after", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Return payouts released at or after this ISO-8601 timestamp." }, { "name": "released_before", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Return payouts released before this ISO-8601 timestamp." } ] } } }, "x-webhook-event-schemas": { "order.created": "#/components/schemas/WebhookOrderEnvelope", "order.updated": "#/components/schemas/WebhookOrderEnvelope", "order.shipped": "#/components/schemas/WebhookOrderEnvelope", "order.cancelled": "#/components/schemas/WebhookOrderEnvelope", "order.status.updated": "#/components/schemas/WebhookOrderStatusEnvelope", "inventory.updated": "#/components/schemas/WebhookInventoryEnvelope", "product.created": "#/components/schemas/WebhookProductEnvelope", "product.updated": "#/components/schemas/WebhookProductUpdatedEnvelope", "product.stock.updated": "#/components/schemas/WebhookProductStockEnvelope", "product.price.updated": "#/components/schemas/WebhookProductPriceEnvelope", "product.deleted": "#/components/schemas/WebhookProductDeletedEnvelope", "fulfillment.created": "#/components/schemas/WebhookFulfillmentEnvelope", "fulfillment.updated": "#/components/schemas/WebhookFulfillmentEnvelope", "fulfillment.shipped": "#/components/schemas/WebhookFulfillmentEnvelope", "return.created": "#/components/schemas/WebhookReturnEnvelope", "return.approved": "#/components/schemas/WebhookReturnEnvelope", "return.rejected": "#/components/schemas/WebhookReturnEnvelope", "return.disputed": "#/components/schemas/WebhookReturnEnvelope", "return.status.updated": "#/components/schemas/WebhookReturnStatusEnvelope", "authorization.granted": "#/components/schemas/WebhookAuthorizationEnvelope", "authorization.revoked": "#/components/schemas/WebhookAuthorizationEnvelope", "authorization.expiring": "#/components/schemas/WebhookAuthorizationExpiringEnvelope" }, "components": { "securitySchemes": { "hmacAuth": { "type": "apiKey", "in": "header", "name": "X-MallPlus-Signature", "description": "HMAC-SHA256 signature (v3). Base string: \"{timestamp}:{clientId}:{METHOD}:{path}:{queryCanonical}:{sha256(body)}:{nonce}\" where sha256(body) is the lowercase hex SHA-256 digest of the raw request body (digest of the empty string when there is no body), queryCanonical is the sorted percent-encoded query string (empty string when there is none), and nonce is a client-generated 32-64 char lowercase-hex value, unique per request. Also requires X-MallPlus-Partner-Id, X-MallPlus-Timestamp, X-MallPlus-Signature-Version (must be \"3\"), and X-MallPlus-Nonce headers. Standard data routes use the deployment-configured timestamp window (90 seconds by default); OAuth authorize/token/refresh/revoke v3 requests use 120 seconds. On standard data routes, v1 is rejected and v2 (5-field base string, no query/nonce) is dual-accepted only while HMAC_V2_GRACE_UNTIL is set to a future date; after cutover v2 returns 401 HMAC_VERSION_DEPRECATED. OAuth authorize/token/refresh/revoke routes reject an explicit version 2; their temporary legacy mode is selected only by omitting the version header. Routes flagged x-requires-seller-token additionally require X-MallPlus-Access-Token + X-MallPlus-Seller-Id; HMAC-only access returns 401 SELLER_TOKEN_REQUIRED." }, "sellerAuthSession": { "type": "apiKey", "in": "cookie", "name": "mp_seller_auth_session", "description": "Short-lived, HttpOnly authorization-session cookie set during the seller consent flow. Used only by seller-verify-otp and seller-consent; partner API clients do not create this cookie." }, "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 v3 base string is the SAME as public mode — \"{timestamp}:{clientId}:{METHOD}:{path}:{queryCanonical}:{sha256(body)}:{nonce}\"; access_token and seller_id are NOT included in the signature. 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, "description": "Whether the request completed successfully." }, "data": { "type": "object", "description": "Response payload (varies by endpoint)" }, "meta": { "$ref": "#/components/schemas/PaginationMeta", "description": "Response metadata, including pagination when the endpoint returns a list." } }, "required": [ "success" ] }, "AuthorizationListResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the request completed successfully." }, "data": { "type": "array", "items": { "type": "object", "required": [ "seller_id", "scopes", "status", "granted_at", "expires_at" ], "properties": { "seller_id": { "type": "string", "description": "Seller identifier — the value used by seller-token calls and POST /auth/revoke." }, "seller_name": { "type": "string", "nullable": true, "description": "Display name of the seller." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "OAuth scopes requested or granted." }, "status": { "type": "string", "enum": [ "active", "revoked", "expired" ], "description": "Effective grant status. A stored grant past its 365-day expiry is reported as expired even before the lazy storage flip." }, "granted_at": { "type": "string", "format": "date-time", "description": "Granted at as an ISO-8601 timestamp." }, "expires_at": { "type": "string", "format": "date-time", "description": "End of the 365-day authorization window; the seller must re-consent after this. ISO-8601 timestamp." } } }, "description": "Response or event payload for this schema." }, "meta": { "$ref": "#/components/schemas/PaginationMeta", "description": "Response metadata, including pagination when the endpoint returns a list." } } }, "BulkJobAcceptedResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the request completed successfully." }, "data": { "type": "object", "required": [ "job_id", "status", "location" ], "properties": { "job_id": { "type": "string", "description": "Asynchronous bulk job ID." }, "status": { "type": "string", "enum": [ "pending" ], "description": "Current status for this resource or workflow." }, "location": { "type": "string", "description": "Sanitized scan location." } }, "description": "Response or event payload for this schema." } } }, "BulkJobResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the request completed successfully." }, "data": { "type": "object", "required": [ "job_id", "operation", "status", "summary", "items", "pagination" ], "properties": { "job_id": { "type": "string", "description": "Asynchronous bulk job ID." }, "operation": { "type": "string", "enum": [ "product_create", "inventory_update", "order_ship", "order_cancel" ], "description": "Bulk operation type executed by the job." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "partial_success", "failed", "cancelled" ], "description": "Current status for this resource or workflow." }, "summary": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of items in this summary." }, "succeeded": { "type": "integer", "description": "Number of items that completed successfully." }, "failed": { "type": "integer", "description": "Number of items that failed." }, "outcome_unknown": { "type": "integer", "description": "Number of items whose final outcome is not yet known." } }, "description": "Summary details." }, "items": { "type": "array", "items": { "type": "object" }, "description": "Items associated with this request, response, or event." }, "pagination": { "type": "object", "properties": { "offset": { "type": "integer", "description": "0-based item offset for this result page." }, "limit": { "type": "integer", "maximum": 100, "description": "Maximum number of result items returned in this page." } }, "description": "Pagination details." } }, "description": "Response or event payload for this schema." } } }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": false, "description": "Whether the request completed successfully." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code", "enum": [ "ACCOUNT_LOCKED", "APPROVE_FAILED", "APP_LIMIT_REACHED", "APP_NOT_FOUND", "AUTHORIZATION_CODE_EXPIRED", "AUTHORIZATION_REVOKED", "AUTH_CODE_EXPIRED", "AUTH_CODE_USED", "BAD_REQUEST", "CANCELLATION_ALREADY_PROCESSED", "CANCELLATION_DEADLINE_EXCEEDED", "CANCEL_FAILED", "CANNOT_DELETE_ACCOUNT_WITH_APPS", "CONCURRENT_MODIFICATION", "CONFLICT", "CREATE_FAILED", "DISPUTE_FAILED", "DUPLICATE", "EMAIL_ALREADY_EXISTS", "EMAIL_NOT_VERIFIED", "FILE_TOO_LARGE", "FORBIDDEN", "HMAC_VERSION_DEPRECATED", "IDEMPOTENCY_KEY_IN_PROGRESS", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "INTERNAL_ERROR", "INVALID_AUTHORIZATION_CODE", "INVALID_CREDENTIALS", "INVALID_DEVELOPER_TYPE", "INVALID_FILE_CONTENT", "INVALID_FILE_TYPE", "INVALID_JSON", "INVALID_NONCE", "INVALID_PATH", "INVALID_PICKUP_DATE", "INVALID_REFRESH_TOKEN", "INVALID_REQUEST", "INVALID_SIGNATURE", "INVALID_STATE", "INVALID_TRANSITION", "INVALID_VERIFICATION_TOKEN", "MAINTENANCE", "MEMBER_PERMISSION_DENIED", "MISSING_NONCE", "NONCE_REUSED", "NOT_FOUND", "NOT_IMPLEMENTED", "ORDER_NOT_CANCELLABLE", "PAYLOAD_TOO_LARGE", "PICKUP_DATES_UNAVAILABLE", "PRODUCT_HAS_ACTIVE_ORDERS", "PRODUCT_UNDER_REVIEW", "PROFILE_ALREADY_SUBMITTED", "PROFILE_TYPE_MISMATCH", "PROXY_ERROR", "RATE_LIMITED", "REDIRECT_URL_MISMATCH", "REFRESH_TOKEN_EXPIRED", "REFRESH_TOKEN_REUSED", "REJECT_FAILED", "RETURN_ALREADY_PROCESSED", "RETURN_DEADLINE_EXCEEDED", "RE_AUTHORIZATION_REQUIRED", "SANDBOX_LIMIT_REACHED", "SELLER_TOKEN_REQUIRED", "SERVICE_UNAVAILABLE", "SESSION_EXPIRED", "SHIPMENT_ALREADY_ARRANGED", "SHIPMENT_NOT_ARRANGED", "SHIPPING_LABEL_UNAVAILABLE", "SHIP_FAILED", "SIGNATURE_REPLAYED", "SSRF_CHECK_FAILED", "TEST_SHOP_LIMIT_REACHED", "TIMESTAMP_EXPIRED", "TOKEN_REVOKED", "TOO_MANY_REQUESTS", "UNAUTHORIZED", "UPLOAD_ERROR", "UPLOAD_NOT_CONFIGURED", "UPSTREAM_ERROR", "UPSTREAM_TIMEOUT", "VALIDATION_ERROR", "VERIFICATION_LINK_USED", "VERIFICATION_TOKEN_EXPIRED", "WEBHOOK_SUBSCRIPTION_EXISTS" ] }, "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" ], "description": "Structured error payload returned when the request fails." } }, "required": [ "success", "error" ] }, "WebhookEnvelopeBase": { "type": "object", "properties": { "event_type": { "type": "string", "enum": [ "order.created", "order.updated", "order.shipped", "order.cancelled", "order.status.updated", "inventory.updated", "product.created", "product.updated", "product.stock.updated", "product.price.updated", "product.deleted", "fulfillment.created", "fulfillment.updated", "fulfillment.shipped", "return.created", "return.approved", "return.rejected", "return.disputed", "return.status.updated", "authorization.granted", "authorization.revoked", "authorization.expiring" ], "description": "Webhook event type from the published event catalog." }, "event_id": { "type": "string", "format": "uuid", "description": "Unique webhook event ID." }, "resource_type": { "type": "string", "description": "Type of resource represented by this event." }, "resource_id": { "type": "string", "description": "ID of the resource represented by this event." }, "occurred_at": { "type": "string", "format": "date-time", "description": "ISO-8601 UTC event-creation time" } }, "required": [ "event_type", "event_id", "resource_type", "resource_id", "occurred_at" ] }, "WebhookOrderEnvelope": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order", "description": "Response or event payload for this schema." } }, "required": [ "data" ] } ] }, "WebhookOrderStatusEnvelope": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "description": "Order ID associated with this value." }, "new_status": { "type": "string", "description": "Status after the event update." }, "previous_status": { "type": "string", "description": "Status before the event update." } }, "required": [ "order_id", "new_status", "previous_status" ], "description": "Response or event payload for this schema." } }, "required": [ "data" ] } ] }, "WebhookInventoryItem": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Unique identifier for this resource." }, "sku": { "type": "string", "description": "Seller SKU." }, "quantity": { "type": "integer", "description": "Quantity of units." }, "sellerId": { "type": "string", "description": "Seller ID associated with this value." }, "title": { "type": "string", "description": "Partner-visible title." }, "reserved_quantity": { "type": "integer", "description": "Inventory quantity reserved for open orders." }, "incoming_quantity": { "type": "integer", "description": "Inventory quantity expected from inbound stock." }, "variantId": { "type": "string", "description": "Product variant ID associated with this value." }, "created_at": { "type": "string", "format": "date-time", "description": "Created at as an ISO-8601 timestamp." }, "updated_at": { "type": "string", "format": "date-time", "description": "Updated at as an ISO-8601 timestamp." } }, "required": [ "id", "sku", "quantity" ] }, "BulkSummary": { "type": "object", "additionalProperties": false, "properties": { "total": { "type": "integer", "description": "Total number of items in this summary." }, "succeeded": { "type": "integer", "description": "Number of items that completed successfully." }, "failed": { "type": "integer", "description": "Number of items that failed." } }, "required": [ "total", "succeeded", "failed" ] }, "WebhookInventoryData": { "oneOf": [ { "$ref": "#/components/schemas/WebhookInventoryItem" }, { "type": "object", "properties": { "updated": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookInventoryItem" }, "description": "Resources updated by this event." }, "summary": { "$ref": "#/components/schemas/BulkSummary", "description": "Summary details." } }, "required": [ "updated", "summary" ] }, { "type": "object", "properties": { "product_id": { "type": "string", "description": "Product ID associated with this value." }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Items associated with this request, response, or event." } }, "required": [ "product_id", "items" ] } ] }, "WebhookInventoryEnvelope": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookInventoryData", "description": "Response or event payload for this schema." } }, "required": [ "data" ] } ] }, "WebhookProductEnvelope": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product", "description": "Response or event payload for this schema." } }, "required": [ "data" ] } ] }, "WebhookProductUpdatedEnvelope": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/Product" }, { "type": "object", "properties": { "product_id": { "type": "string", "description": "Product ID associated with this value." }, "status": { "type": "string", "description": "Current status for this resource or workflow." } }, "required": [ "product_id", "status" ] } ], "description": "Response or event payload for this schema." } }, "required": [ "data" ] } ] }, "WebhookProductStockEnvelope": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookInventoryData", "description": "Response or event payload for this schema." } }, "required": [ "data" ] } ] }, "WebhookProductPriceEnvelope": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "product_id": { "type": "string", "description": "Product ID associated with this value." }, "updated": { "type": "array", "items": { "type": "object", "properties": { "variant_id": { "type": "string", "description": "Product variant ID associated with this value." }, "new_price": { "type": "integer", "description": "Integer amount in PHP centavos." } }, "required": [ "variant_id", "new_price" ] }, "description": "Resources updated by this event." } }, "required": [ "product_id", "updated" ], "description": "Response or event payload for this schema." } }, "required": [ "data" ] } ] }, "WebhookProductDeletedEnvelope": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "product_id": { "type": "string", "description": "Product ID associated with this value." }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Whether deleted is true." } }, "required": [ "product_id", "deleted" ], "description": "Response or event payload for this schema." } }, "required": [ "data" ] } ] }, "WebhookFulfillmentEnvelope": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Fulfillment", "description": "Response or event payload for this schema." } }, "required": [ "data" ] } ] }, "WebhookReturn": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Unique identifier for this resource." }, "orderId": { "type": "string", "description": "Order ID associated with this value." }, "status": { "type": "string", "description": "Current status for this resource or workflow." }, "reason": { "type": "string", "description": "Reason provided for the request or status." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReturnItemRequest" }, "description": "Items associated with this request, response, or event." }, "refundAmount": { "type": "integer", "description": "Integer amount in PHP centavos." }, "sellerId": { "type": "string", "description": "Seller ID associated with this value." }, "rejection_reason": { "type": "string", "description": "Rejection reason value." }, "dispute_reason_code": { "type": "string", "description": "Dispute reason code value." }, "dispute_note": { "type": "string", "description": "Dispute note value." }, "created_at": { "type": "string", "format": "date-time", "description": "Created at as an ISO-8601 timestamp." }, "updated_at": { "type": "string", "format": "date-time", "description": "Updated at as an ISO-8601 timestamp." } }, "required": [ "id", "orderId", "status", "reason", "items" ] }, "WebhookReturnEnvelope": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookReturn", "description": "Response or event payload for this schema." } }, "required": [ "data" ] } ] }, "WebhookReturnStatusEnvelope": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "return_id": { "type": "string", "description": "Return case ID associated with this value." }, "order_id": { "type": "string", "description": "Order ID associated with this value." }, "new_status": { "type": "string", "description": "Status after the event update." }, "previous_status": { "type": "string", "description": "Status before the event update." } }, "required": [ "return_id", "order_id", "new_status", "previous_status" ], "description": "Response or event payload for this schema." } }, "required": [ "data" ] } ] }, "WebhookAuthorizationEnvelope": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "authorization_id": { "type": "string", "description": "Seller authorization ID associated with this value." }, "seller_id": { "type": "string", "description": "Seller ID associated with this value." }, "app_id": { "type": "string", "description": "App id value." } }, "required": [ "authorization_id" ], "description": "Response or event payload for this schema." } }, "required": [ "data" ] } ] }, "WebhookAuthorizationExpiringEnvelope": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelopeBase" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "authorization_id": { "type": "string", "description": "Seller authorization ID associated with this value." }, "expires_at": { "type": "integer", "description": "Unix epoch seconds" }, "seller_id": { "type": "string", "description": "Seller ID associated with this value." }, "app_id": { "type": "string", "description": "App id value." } }, "required": [ "authorization_id", "expires_at" ], "description": "Response or event payload for this schema." } }, "required": [ "data" ] } ] }, "PaginationMeta": { "type": "object", "properties": { "page": { "type": "integer", "example": 1, "description": "1-based page number represented by this response page." }, "limit": { "type": "integer", "example": 20, "description": "Maximum number of records returned in this response page." }, "total": { "type": "integer", "example": 150, "description": "Total number of records matching the request filters." } } }, "EmptyObject": { "type": "object", "additionalProperties": false }, "TokenRequest": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string", "minLength": 1, "description": "Machine-readable code for this value." }, "client_id": { "type": "string", "minLength": 1, "description": "Partner application client ID." }, "seller_id": { "type": "string", "minLength": 1, "description": "Seller ID associated with this value." } }, "required": [ "code", "client_id", "seller_id" ] }, "RefreshTokenRequest": { "type": "object", "additionalProperties": false, "properties": { "refresh_token": { "type": "string", "minLength": 1, "description": "Refresh token used to obtain a new access token." }, "client_id": { "type": "string", "minLength": 1, "description": "Partner application client ID." }, "seller_id": { "type": "string", "minLength": 1, "description": "Seller ID associated with this value." } }, "required": [ "refresh_token", "client_id", "seller_id" ] }, "RevokeAuthorizationRequest": { "type": "object", "additionalProperties": false, "properties": { "client_id": { "type": "string", "minLength": 1, "description": "Partner application client ID." }, "seller_id": { "type": "string", "minLength": 1, "description": "Seller ID associated with this value." } }, "required": [ "client_id", "seller_id" ] }, "DenyAuthorizationRequest": { "type": "object", "additionalProperties": false, "properties": { "client_id": { "type": "string", "minLength": 1, "description": "Partner application client ID." }, "redirect_uri": { "type": "string", "format": "uri", "description": "Registered redirect URI for the OAuth flow." }, "state": { "type": "string", "maxLength": 1024, "description": "State value." } }, "required": [ "client_id", "redirect_uri" ] }, "SellerVerifyRequest": { "type": "object", "additionalProperties": false, "description": "Provide either email or identifier together with the remaining required fields.", "properties": { "email": { "type": "string", "anyOf": [ { "format": "email" }, { "pattern": "^[A-Za-z0-9_-]{12}$" } ], "description": "Email address." }, "identifier": { "type": "string", "minLength": 1, "description": "Seller login identifier." }, "password": { "type": "string", "minLength": 1, "description": "Seller password used for verification." }, "client_id": { "type": "string", "minLength": 1, "description": "Partner application client ID." }, "redirect_uri": { "type": "string", "format": "uri", "description": "Registered redirect URI for the OAuth flow." }, "state": { "type": "string", "maxLength": 1024, "description": "State value." }, "scopes": { "type": "array", "maxItems": 50, "items": { "type": "string" }, "description": "OAuth scopes requested or granted." } }, "required": [ "password", "client_id", "redirect_uri" ], "anyOf": [ { "required": [ "email" ] }, { "required": [ "identifier" ] } ] }, "SellerVerifyOtpRequest": { "type": "object", "additionalProperties": false, "properties": { "otp": { "type": "string", "pattern": "^\\d{6}$", "description": "Six-digit one-time password." } }, "required": [ "otp" ] }, "SandboxOrderItemRequest": { "type": "object", "additionalProperties": false, "description": "A sandbox order line item to create for simulation.", "properties": { "productId": { "type": "string", "maxLength": 64, "description": "Product ID associated with this value." }, "title": { "type": "string", "maxLength": 200, "description": "Partner-visible title." }, "sku": { "type": "string", "maxLength": 64, "description": "Seller SKU." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Quantity of units." }, "unitPrice": { "type": "integer", "minimum": 0, "maximum": 99999999, "description": "Integer amount in PHP centavos." } }, "required": [ "quantity" ] }, "SandboxOrderRequest": { "type": "object", "additionalProperties": false, "properties": { "sellerId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Seller ID associated with this value." }, "buyerId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Sandbox buyer ID associated with this order." }, "sandboxId": { "type": "string", "maxLength": 64, "description": "Sandbox shop or fixture set ID." }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/SandboxOrderItemRequest" }, "description": "Items associated with this request, response, or event." }, "paymentMethod": { "type": "string", "maxLength": 40, "description": "Payment method used by the sandbox order." }, "shippingOptionId": { "type": "string", "maxLength": 64, "description": "Shipping option ID selected by the sandbox order." }, "shippingOptionName": { "type": "string", "maxLength": 120, "description": "Shipping option name selected by the sandbox order." } }, "required": [ "sellerId", "buyerId", "items" ] }, "SandboxSeedRequest": { "type": "object", "additionalProperties": false, "properties": { "sandboxId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Owned sandbox shop to seed; optional only when the developer has exactly one shop." } } }, "SandboxSellerCreateRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Partner-visible name." }, "email": { "type": "string", "format": "email", "maxLength": 254, "description": "Email address." }, "storeName": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Sandbox seller store name." } }, "required": [ "name", "email", "storeName" ] }, "SandboxBuyerShippingAddressRequest": { "type": "object", "additionalProperties": false, "properties": { "line1": { "type": "string", "minLength": 1, "maxLength": 200, "description": "First line of the street address." }, "line2": { "type": "string", "maxLength": 200, "description": "Second line of the street address, when present." }, "city": { "type": "string", "minLength": 1, "maxLength": 100, "description": "PSGC-aligned Philippine city or municipality." }, "region": { "type": "string", "minLength": 1, "maxLength": 100, "description": "PSGC-aligned Philippine region." }, "postalCode": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Postal code for the address." }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code." } }, "required": [ "line1", "city", "region", "postalCode", "country" ] }, "SandboxBuyerCreateRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Partner-visible name." }, "email": { "type": "string", "format": "email", "maxLength": 254, "description": "Email address." }, "phoneNumber": { "type": "string", "minLength": 1, "maxLength": 40, "description": "Contact phone number." }, "shippingAddress": { "$ref": "#/components/schemas/SandboxBuyerShippingAddressRequest", "description": "Shipping address details." } }, "required": [ "name", "email", "phoneNumber", "shippingAddress" ] }, "WebhookCreateRequest": { "type": "object", "additionalProperties": false, "properties": { "eventType": { "type": "string", "enum": [ "order.created", "order.updated", "order.shipped", "order.cancelled", "order.status.updated", "inventory.updated", "product.created", "product.updated", "product.stock.updated", "product.price.updated", "product.deleted", "fulfillment.created", "fulfillment.updated", "fulfillment.shipped", "return.created", "return.approved", "return.rejected", "return.disputed", "return.status.updated", "authorization.granted", "authorization.revoked", "authorization.expiring" ], "description": "One value from the published webhook event catalog." }, "callbackUrl": { "type": "string", "format": "uri", "pattern": "^https://", "description": "Public HTTPS URL. Private, loopback, link-local, and metadata destinations are rejected." } }, "required": [ "eventType", "callbackUrl" ] }, "WebhookUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "callbackUrl": { "type": "string", "format": "uri", "pattern": "^https://", "description": "Public HTTPS URL. Private, loopback, link-local, and metadata destinations are rejected." }, "isActive": { "type": "boolean", "description": "Whether the webhook subscription is active." } } }, "WebhookTestRequest": { "type": "object", "additionalProperties": false, "properties": { "event": { "type": "string", "enum": [ "order.created", "order.updated", "order.shipped", "order.cancelled", "order.status.updated", "inventory.updated", "product.created", "product.updated", "product.stock.updated", "product.price.updated", "product.deleted", "fulfillment.created", "fulfillment.updated", "fulfillment.shipped", "return.created", "return.approved", "return.rejected", "return.disputed", "return.status.updated", "authorization.granted", "authorization.revoked", "authorization.expiring" ], "description": "One value from the published webhook event catalog." } }, "required": [ "event" ] }, "OrderItemQuantityRequest": { "type": "object", "additionalProperties": false, "description": "A line item and the quantity to act on.", "properties": { "itemId": { "type": "string", "maxLength": 64, "description": "Line item ID." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Quantity of units." } }, "required": [ "itemId", "quantity" ] }, "OrderShipRequest": { "type": "object", "additionalProperties": false, "properties": { "trackingNumber": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Partner-provided tracking number." }, "trackingCompany": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Partner-provided tracking company name." }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/OrderItemQuantityRequest" }, "description": "Items associated with this request, response, or event." } }, "required": [ "trackingNumber", "trackingCompany", "items" ] }, "ProductVariantCreateRequest": { "type": "object", "additionalProperties": false, "description": "A product variant to create with its price, stock, and option values. Supply `options` as the variant axis values (for example `{\"Colour\":\"Red\",\"Size\":\"M\"}`); the option groups they belong to are what the product detail page renders its selectors from, so a variant set with no option values renders as a single un-selectable listing. Physical attributes are required on each variant only when the product sets `use_variant_dimensions: true`.", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Partner-visible title." }, "sku": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Seller SKU." }, "price": { "type": "integer", "minimum": 0, "maximum": 99999999, "description": "Integer amount in PHP centavos." }, "stock": { "type": "integer", "minimum": 0, "maximum": 1000000000, "description": "Stock count for the primary variant." }, "options": { "type": "object", "description": "Variant axis values keyed by option-group name. Required for correct PDP rendering when the product has more than one variant.", "additionalProperties": { "type": "string", "maxLength": 200 } }, "images": { "type": "array", "maxItems": 20, "description": "Variant-specific image URLs. Falls back to the product images when omitted.", "items": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2048 } }, "weight": { "type": "number", "exclusiveMinimum": 0, "description": "Variant weight in GRAMS. Required when the product sets `use_variant_dimensions: true`." }, "length": { "type": "number", "exclusiveMinimum": 0, "description": "Variant length in CENTIMETRES. Required when the product sets `use_variant_dimensions: true`." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Variant width in CENTIMETRES. Required when the product sets `use_variant_dimensions: true`." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Variant height in CENTIMETRES. Required when the product sets `use_variant_dimensions: true`." } }, "required": [ "price", "stock" ] }, "ProductCreateRequest": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "minLength": 8, "maxLength": 100, "description": "Product title, 8-100 characters." }, "description": { "type": "string", "maxLength": 10000, "description": "Human-readable description." }, "category": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Category id. Must be a LEAF category (one with no active children) — a parent category is rejected. The mandatory attributes for the chosen category are discoverable via GET /open/v1/categories/{id}/attributes." }, "images": { "type": "array", "minItems": 1, "maxItems": 20, "description": "Product image URLs. At least one HTTPS URL is required.", "items": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2048 } }, "weight": { "type": "number", "exclusiveMinimum": 0, "description": "Shipping weight in GRAMS. Required unless `use_variant_dimensions` is true." }, "length": { "type": "number", "exclusiveMinimum": 0, "description": "Parcel length in CENTIMETRES. Required unless `use_variant_dimensions` is true." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Parcel width in CENTIMETRES. Required unless `use_variant_dimensions` is true." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Parcel height in CENTIMETRES. Required unless `use_variant_dimensions` is true." }, "use_variant_dimensions": { "type": "boolean", "description": "Ship by variant. When true, weight and dimensions are required on EVERY variant instead of on the product, and the product-level figures are derived from them." }, "attribute_values": { "type": "array", "maxItems": 50, "description": "Category-mapped attribute values. Which attributes are mandatory, and the allowed values for SELECT/MULTIVALUE types, come from the category — fetch them from GET /open/v1/categories/{id}/attributes.", "items": { "type": "object", "additionalProperties": false, "properties": { "attribute_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Attribute id value." }, "value": { "oneOf": [ { "type": "string", "maxLength": 1000 }, { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 500 } } ], "description": "Value details." } }, "required": [ "attribute_id", "value" ] } }, "variants": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/ProductVariantCreateRequest" }, "description": "Product variants." } }, "required": [ "title", "category", "variants", "images" ] }, "ProductUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "minLength": 8, "maxLength": 100, "description": "Partner-visible title." }, "description": { "type": "string", "maxLength": 10000, "description": "Human-readable description." }, "category": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Product category." }, "images": { "type": "array", "maxItems": 20, "items": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2048 }, "description": "Product image URLs." } } }, "ProductBulkItemRequest": { "type": "object", "additionalProperties": false, "description": "Bulk product input. Every item must carry at least one variant with price and stock, matching the single-create contract.", "properties": { "title": { "type": "string", "minLength": 8, "maxLength": 100, "description": "Product title, 8-100 characters." }, "description": { "type": "string", "maxLength": 10000, "description": "Human-readable description." }, "category": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Category id. Must be a LEAF category (one with no active children) — a parent category is rejected. The mandatory attributes for the chosen category are discoverable via GET /open/v1/categories/{id}/attributes." }, "images": { "type": "array", "minItems": 1, "maxItems": 20, "description": "Product image URLs. At least one HTTPS URL is required.", "items": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2048 } }, "weight": { "type": "number", "exclusiveMinimum": 0, "description": "Shipping weight in GRAMS. Required unless `use_variant_dimensions` is true." }, "length": { "type": "number", "exclusiveMinimum": 0, "description": "Parcel length in CENTIMETRES. Required unless `use_variant_dimensions` is true." }, "width": { "type": "number", "exclusiveMinimum": 0, "description": "Parcel width in CENTIMETRES. Required unless `use_variant_dimensions` is true." }, "height": { "type": "number", "exclusiveMinimum": 0, "description": "Parcel height in CENTIMETRES. Required unless `use_variant_dimensions` is true." }, "use_variant_dimensions": { "type": "boolean", "description": "Ship by variant. When true, weight and dimensions are required on EVERY variant instead of on the product, and the product-level figures are derived from them." }, "attribute_values": { "type": "array", "maxItems": 50, "description": "Category-mapped attribute values. Which attributes are mandatory, and the allowed values for SELECT/MULTIVALUE types, come from the category — fetch them from GET /open/v1/categories/{id}/attributes.", "items": { "type": "object", "additionalProperties": false, "properties": { "attribute_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Attribute id value." }, "value": { "oneOf": [ { "type": "string", "maxLength": 1000 }, { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 500 } } ], "description": "Value details." } }, "required": [ "attribute_id", "value" ] } }, "variants": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/ProductVariantCreateRequest" }, "description": "Product variants." } }, "required": [ "title", "category", "variants", "images" ] }, "ProductBulkRequest": { "type": "object", "additionalProperties": false, "properties": { "products": { "type": "array", "minItems": 1, "maxItems": 5000, "items": { "$ref": "#/components/schemas/ProductBulkItemRequest" }, "description": "Products included in the bulk request." } }, "required": [ "products" ] }, "ProductPriceUpdateItemRequest": { "type": "object", "additionalProperties": false, "description": "A variant price update to apply in a bulk price request.", "properties": { "variant_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Product variant ID associated with this value." }, "price": { "type": "integer", "minimum": 1, "maximum": 99999999, "description": "Integer amount in PHP centavos." } }, "required": [ "variant_id", "price" ] }, "ProductPriceUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "updates": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/ProductPriceUpdateItemRequest" }, "description": "Variant updates to apply." } }, "required": [ "updates" ] }, "ProductStatusUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "live", "unlisted", "delisted" ], "description": "The status to apply. Only the settable statuses are accepted here. The read-only statuses (proposed, under_review, archived) are outcomes of other operations and are rejected with 400 VALIDATION_ERROR." } }, "required": [ "status" ] }, "ProductStockUpdateItemRequest": { "type": "object", "additionalProperties": false, "description": "A variant stock update to apply in a bulk stock request.", "properties": { "variant_id": { "type": "string", "minLength": 1, "description": "Product variant ID associated with this value." }, "stock_quantity": { "type": "integer", "minimum": 0, "maximum": 1000000000, "description": "Available stock quantity." } }, "required": [ "variant_id", "stock_quantity" ] }, "ProductStockUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/ProductStockUpdateItemRequest" }, "description": "Items associated with this request, response, or event." } }, "required": [ "items" ] }, "ShipmentArrangementRequest": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "pickup" ], "description": "Discriminator or resource type for this payload." }, "pickupAddressId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Pickup address ID selected for shipment arrangement." }, "pickupDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "maxLength": 10, "description": "Pickup date in YYYY-MM-DD format." } }, "required": [ "type", "pickupAddressId", "pickupDate" ] }, { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "dropoff" ], "description": "Discriminator or resource type for this payload." }, "dropoffBranchId": { "type": "string", "maxLength": 64, "description": "Drop-off branch ID, when a branch is selected." } }, "required": [ "type" ] } ], "discriminator": { "propertyName": "type" } }, "OrderBulkShipItemRequest": { "type": "object", "additionalProperties": false, "description": "An order shipment instruction included in a bulk ship request.", "properties": { "orderId": { "type": "string", "minLength": 1, "description": "Order ID associated with this value." }, "trackingNumber": { "type": "string", "minLength": 1, "description": "Partner-provided tracking number." }, "trackingCompany": { "type": "string", "minLength": 1, "description": "Partner-provided tracking company name." }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/OrderItemQuantityRequest" }, "description": "Items associated with this request, response, or event." }, "expectedStatus": { "type": "string", "enum": [ "PENDING", "PAID", "READY_TO_SHIP", "SHIPPED", "DELIVERED", "CANCELLED" ], "description": "Optional compare-and-swap guard. When supplied, the transition only applies if the order is still in this status. PENDING, PAID, and READY_TO_SHIP are treated as the same pre-shipment state for this guard." } }, "required": [ "orderId", "trackingNumber", "trackingCompany", "items" ] }, "OrderBulkShipRequest": { "type": "object", "additionalProperties": false, "properties": { "orders": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/OrderBulkShipItemRequest" }, "description": "Orders values." } }, "required": [ "orders" ] }, "OrderBulkCancelItemRequest": { "type": "object", "additionalProperties": false, "description": "An order cancellation instruction included in a bulk cancel request.", "properties": { "orderId": { "type": "string", "minLength": 1, "description": "Order ID associated with this value." }, "expectedStatus": { "type": "string", "enum": [ "PENDING", "PAID", "READY_TO_SHIP", "SHIPPED", "DELIVERED", "CANCELLED" ], "description": "Optional compare-and-swap guard. When supplied, the transition only applies if the order is still in this status. PENDING, PAID, and READY_TO_SHIP are treated as the same pre-shipment state for this guard." } }, "required": [ "orderId" ] }, "OrderBulkCancelRequest": { "type": "object", "additionalProperties": false, "properties": { "orders": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/OrderBulkCancelItemRequest" }, "description": "Orders values." } }, "required": [ "orders" ] }, "InventoryUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "quantity": { "type": "integer", "minimum": 0, "maximum": 1000000000, "description": "Quantity of units." }, "expectedQuantity": { "type": "integer", "minimum": 0, "maximum": 1000000000, "description": "Required compare-and-swap guard. The update only applies if current stock matches this value." } }, "required": [ "quantity", "expectedQuantity" ] }, "InventoryBulkUpdateItemRequest": { "type": "object", "additionalProperties": false, "description": "An inventory quantity update included in a bulk inventory request.", "properties": { "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this resource." }, "quantity": { "type": "integer", "minimum": 0, "maximum": 1000000000, "description": "Quantity of units." }, "expectedQuantity": { "type": "integer", "minimum": 0, "maximum": 1000000000, "description": "Required compare-and-swap guard. This item update only applies if current stock matches this value." } }, "required": [ "id", "quantity", "expectedQuantity" ] }, "InventoryBulkUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 5000, "items": { "$ref": "#/components/schemas/InventoryBulkUpdateItemRequest" }, "description": "Items associated with this request, response, or event." } }, "required": [ "items" ] }, "InventoryItem": { "type": "object", "additionalProperties": false, "description": "Seller-owned inventory item returned by Inventory endpoints.", "properties": { "id": { "type": "string", "description": "Inventory item identifier.", "example": "prod_openapi_inventory" }, "sku": { "type": "string", "description": "Seller SKU for the inventory item.", "example": "OPENAPI-INVENTORY-SKU" }, "quantity": { "type": "integer", "description": "Current available inventory quantity.", "example": 8 }, "sellerId": { "type": "string", "description": "Seller identifier that owns the inventory item.", "example": "seller-openapi-response-contract" }, "title": { "type": "string", "description": "Product title associated with the inventory item when available.", "example": "OpenAPI Inventory Product" }, "reserved_quantity": { "type": "integer", "description": "Inventory quantity reserved for open orders.", "example": 1 }, "incoming_quantity": { "type": "integer", "description": "Inventory quantity expected from inbound stock.", "example": 3 }, "variantId": { "type": "string", "description": "Product variant identifier associated with the inventory item when available.", "example": "var_openapi_inventory" }, "created_at": { "type": "string", "format": "date-time", "description": "Inventory item creation timestamp in ISO-8601 format.", "example": "2026-08-25T12:00:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Inventory item update timestamp in ISO-8601 format.", "example": "2026-08-25T12:05:00.000Z" } }, "required": [ "id", "sku", "quantity" ] }, "InventoryItemResponse": { "type": "object", "additionalProperties": false, "description": "Single inventory item response envelope.", "example": { "success": true, "data": { "id": "prod_openapi_inventory", "sku": "OPENAPI-INVENTORY-SKU", "quantity": 12, "sellerId": "seller-openapi-response-contract" } }, "properties": { "success": { "type": "boolean", "description": "Whether the inventory item request succeeded.", "example": true }, "data": { "description": "Updated inventory item data.", "$ref": "#/components/schemas/InventoryItem" } }, "required": [ "success", "data" ] }, "InventoryItemListResponse": { "type": "object", "additionalProperties": false, "description": "Paginated inventory item list response envelope.", "example": { "success": true, "data": [ { "id": "prod_openapi_inventory", "sku": "OPENAPI-INVENTORY-SKU", "quantity": 8, "sellerId": "seller-openapi-response-contract", "created_at": "2026-08-25T12:00:00.000Z" } ], "meta": { "page": 1, "limit": 10, "total": 1 } }, "properties": { "success": { "type": "boolean", "description": "Whether the inventory list request succeeded.", "example": true }, "data": { "type": "array", "description": "Inventory items owned by the authenticated seller.", "items": { "$ref": "#/components/schemas/InventoryItem" } }, "meta": { "description": "Pagination metadata for the inventory list.", "$ref": "#/components/schemas/PaginationMeta" } }, "required": [ "success", "data", "meta" ] }, "InventoryBulkUpdateError": { "type": "object", "additionalProperties": false, "description": "Per-item inventory update failure in a synchronous bulk update response.", "properties": { "id": { "type": "string", "description": "Inventory item identifier from the failed update request.", "example": "prod_openapi_inventory_stale" }, "message": { "type": "string", "description": "Failure reason returned for this inventory item update.", "example": "Inventory quantity changed before update" } }, "required": [ "id", "message" ] }, "InventoryBulkUpdateSummary": { "type": "object", "additionalProperties": false, "description": "Synchronous bulk inventory update result counts.", "properties": { "total": { "type": "integer", "description": "Number of inventory updates submitted in the request.", "example": 2 }, "succeeded": { "type": "integer", "description": "Number of inventory updates that succeeded.", "example": 1 }, "failed": { "type": "integer", "description": "Number of inventory updates that failed.", "example": 1 } }, "required": [ "total", "succeeded", "failed" ] }, "InventoryBulkUpdateData": { "type": "object", "additionalProperties": false, "description": "Synchronous bulk inventory update response data.", "properties": { "updated": { "type": "array", "description": "Inventory items successfully updated by the synchronous bulk request.", "items": { "$ref": "#/components/schemas/InventoryItem" } }, "errors": { "type": "array", "description": "Per-item failures returned by the synchronous bulk request.", "items": { "$ref": "#/components/schemas/InventoryBulkUpdateError" } }, "summary": { "description": "Aggregate result counts for the synchronous bulk request.", "$ref": "#/components/schemas/InventoryBulkUpdateSummary" } }, "required": [ "updated", "errors", "summary" ] }, "InventoryBulkUpdateResponse": { "type": "object", "additionalProperties": false, "description": "Synchronous bulk inventory update response envelope.", "example": { "success": true, "data": { "updated": [ { "id": "prod_openapi_inventory", "sku": "OPENAPI-INVENTORY-SKU", "quantity": 12, "sellerId": "seller-openapi-response-contract" } ], "errors": [ { "id": "prod_openapi_inventory_stale", "message": "Inventory quantity changed before update" } ], "summary": { "total": 2, "succeeded": 1, "failed": 1 } } }, "properties": { "success": { "type": "boolean", "description": "Whether the synchronous bulk inventory request completed.", "example": true }, "data": { "description": "Synchronous bulk inventory update results.", "$ref": "#/components/schemas/InventoryBulkUpdateData" } }, "required": [ "success", "data" ] }, "FulfillmentItemRequest": { "type": "object", "additionalProperties": false, "description": "A fulfillment line item and quantity to fulfill.", "properties": { "itemId": { "type": "string", "maxLength": 64, "description": "Line item ID." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Quantity of units." } }, "required": [ "itemId", "quantity" ] }, "FulfillmentCreateRequest": { "type": "object", "additionalProperties": false, "properties": { "orderId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Order ID associated with this value." }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/FulfillmentItemRequest" }, "description": "Items associated with this request, response, or event." }, "trackingNumber": { "type": "string", "maxLength": 120, "description": "Partner-provided tracking number." }, "trackingCompany": { "type": "string", "maxLength": 80, "description": "Partner-provided tracking company name." } }, "required": [ "orderId", "items" ] }, "FulfillmentUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "pending", "shipped", "delivered", "cancelled" ], "description": "Current status for this resource or workflow." }, "trackingNumber": { "type": "string", "maxLength": 120, "description": "Partner-provided tracking number." }, "trackingCompany": { "type": "string", "maxLength": 80, "description": "Partner-provided tracking company name." }, "expectedStatus": { "type": "string", "enum": [ "pending", "shipped", "delivered", "cancelled" ], "description": "Optional optimistic-locking guard. When supplied, the update is rejected with 409 if the fulfillment status changed before the write was applied." } } }, "ReturnItemRequest": { "type": "object", "additionalProperties": false, "description": "A return line item, quantity, and optional item-level reason.", "properties": { "itemId": { "type": "string", "maxLength": 64, "description": "Line item ID." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Quantity of units." }, "reason": { "type": "string", "maxLength": 500, "description": "Reason provided for the request or status." } }, "required": [ "itemId", "quantity" ] }, "ReturnCreateRequest": { "type": "object", "additionalProperties": false, "properties": { "orderId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Order ID associated with this value." }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/ReturnItemRequest" }, "description": "Items associated with this request, response, or event." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Reason provided for the request or status." } }, "required": [ "orderId", "items", "reason" ] }, "ReturnRejectRequest": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Reason provided for the request or status." } }, "required": [ "reason" ] }, "ReturnDisputeAttachment": { "type": "object", "additionalProperties": false, "description": "Evidence attachment submitted with a return dispute.", "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2048, "description": "Public HTTPS URL for this attachment." }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Partner-visible name." }, "size": { "type": "integer", "minimum": 1, "description": "Attachment size in bytes." }, "mime": { "type": "string", "enum": [ "image/jpeg", "image/png", "video/mp4", "video/quicktime" ], "description": "Attachment MIME type." }, "durationSeconds": { "type": "number", "minimum": 0, "description": "Video duration in seconds." } }, "required": [ "url", "name", "size", "mime" ] }, "ReturnDisputeRequest": { "type": "object", "additionalProperties": false, "properties": { "reasonCode": { "type": "string", "minLength": 1, "maxLength": 100, "enum": [ "did_not_receive_return_parcel", "received_physical_damage", "received_incomplete", "received_wrong_product", "received_used_product", "buyer_claim_incorrect" ], "description": "Machine-readable return dispute reason code." }, "note": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Seller-provided note for the dispute." }, "attachments": { "type": "array", "minItems": 1, "maxItems": 6, "items": { "$ref": "#/components/schemas/ReturnDisputeAttachment" }, "description": "Evidence attachments for the dispute." } }, "required": [ "reasonCode", "note", "attachments" ] }, "ReturnItem": { "type": "object", "additionalProperties": false, "description": "A returned line item projected by the public return DTO.", "properties": { "itemId": { "type": "string", "description": "Line-item identifier from the order being returned.", "example": "100000001" }, "quantity": { "type": "integer", "description": "Number of units for this line item included in the return.", "example": 1 }, "reason": { "type": "string", "description": "Optional item-level return reason supplied for this line item.", "example": "Damaged" } }, "required": [ "itemId", "quantity" ] }, "Return": { "type": "object", "additionalProperties": false, "description": "A return case detail response projected by the Open API return DTO.", "properties": { "id": { "type": "string", "description": "Stable return case identifier.", "example": "ret_openapi_schema_example" }, "orderId": { "type": "string", "description": "Order identifier associated with the return case.", "example": "ORD-SAMPLE-001" }, "status": { "type": "string", "description": "Current return workflow status as returned by the upstream return source.", "example": "requested" }, "reason": { "type": "string", "description": "Return reason recorded on the case.", "example": "Item received damaged - cracked screen" }, "items": { "type": "array", "description": "Line items included in the return.", "items": { "$ref": "#/components/schemas/ReturnItem" } }, "refundAmount": { "type": "integer", "description": "Integer amount in PHP centavos.", "example": 129900 }, "sellerId": { "type": "string", "description": "Seller identifier that owns the return case. Omitted when upstream data does not expose it.", "example": "seller-openapi-response-contract" }, "rejection_reason": { "type": "string", "description": "Reason recorded when the return is rejected. Omitted unless the return has been rejected.", "example": "Item was already used, no longer eligible for return" }, "dispute_reason_code": { "type": "string", "enum": [ "did_not_receive_return_parcel", "received_physical_damage", "received_incomplete", "received_wrong_product", "received_used_product", "buyer_claim_incorrect" ], "description": "Structured dispute reason code. Omitted unless the seller has filed a dispute.", "example": "received_wrong_product" }, "dispute_note": { "type": "string", "description": "Seller dispute note explaining the dispute. Omitted unless the seller has filed a dispute.", "example": "The parcel contained a different item from the approved return." }, "dispute_evidence": { "type": "array", "description": "HTTPS evidence URLs submitted with a dispute. Omitted when no dispute evidence was supplied.", "items": { "type": "string", "description": "HTTPS URL for one dispute evidence attachment.", "example": "https://example.com/evidence/return-photo.jpg" } }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp when the return case was created.", "example": "2026-08-26T10:00:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp when the return case was last updated.", "example": "2026-08-26T10:05:00.000Z" }, "dispute_window_deadline": { "type": "string", "format": "date-time", "description": "ISO-8601 deadline by which the seller may still dispute the return case. Omitted when no dispute window is modelled.", "example": "2026-08-29T10:00:00.000Z" }, "buyer_evidence_urls": { "type": "array", "description": "Buyer-submitted evidence URLs. Omitted when the buyer provided no evidence.", "items": { "type": "string", "description": "URL for one buyer-submitted evidence attachment.", "example": "https://example.com/evidence/buyer-photo.jpg" } }, "response_window_deadline": { "type": "string", "format": "date-time", "description": "ISO-8601 seller response-window deadline. Omitted when the Open API return DTO receives no string deadline from upstream.", "example": "2026-08-27T10:00:00.000Z" } }, "required": [ "id", "orderId", "status", "reason", "items" ] }, "ReturnResponse": { "type": "object", "additionalProperties": false, "description": "Single return response envelope.", "example": { "success": true, "data": { "id": "ret_SqS5eJgMmQ67", "orderId": "ORD-SAMPLE-001", "status": "requested", "reason": "Item received damaged - cracked screen", "items": [ { "itemId": "100000001", "quantity": 1, "reason": "Damaged" } ], "refundAmount": 129900, "sellerId": "seller-openapi-response-contract", "created_at": "2026-08-26T03:21:10.025Z", "updated_at": "2026-08-26T03:21:10.025Z" } }, "properties": { "success": { "type": "boolean", "description": "Whether the return request succeeded.", "example": true }, "data": { "$ref": "#/components/schemas/Return", "description": "Return case detail." } }, "required": [ "success", "data" ] }, "ReturnCase": { "type": "object", "additionalProperties": false, "description": "A return case row in the unified after-sales case list.", "properties": { "case_id": { "type": "string", "description": "Return case identifier used to fetch or act on the case.", "example": "ret_openapi_schema_example" }, "type": { "type": "string", "enum": [ "return_refund", "cancellation", "failed_delivery" ], "description": "Partner-facing case type for the after-sales flow.", "example": "return_refund" }, "order_id": { "type": "string", "description": "Order identifier associated with the case.", "example": "ORD-SAMPLE-001" }, "status": { "type": "string", "enum": [ "pending", "approved", "disputed", "resolved" ], "description": "Partner-facing case status mapped from the upstream return workflow.", "example": "pending" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp when the case was created. Omitted when upstream data does not provide it.", "example": "2026-08-26T10:00:00.000Z" } }, "required": [ "case_id", "type", "order_id", "status" ] }, "ReturnCaseListResponse": { "type": "object", "additionalProperties": false, "description": "Paginated return case list response envelope.", "example": { "success": true, "data": [ { "case_id": "ret_SqS5eJgMmQ67", "type": "return_refund", "order_id": "ORD-SAMPLE-001", "status": "pending", "created_at": "2026-08-26T03:21:10.025Z" } ], "meta": { "page": 1, "limit": 1, "total": 1 } }, "properties": { "success": { "type": "boolean", "description": "Whether the return case list request succeeded.", "example": true }, "data": { "type": "array", "description": "Return cases visible to the authenticated seller token.", "items": { "$ref": "#/components/schemas/ReturnCase" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta", "description": "Response metadata, including pagination when the endpoint returns a list." }, "note": { "type": "string", "description": "Wrapper-level note explaining that cancellation or failed_delivery case lists are empty because those types have no upstream source yet.", "example": "cancellation cases are not yet backed by an upstream source; the list is empty." } }, "required": [ "success", "data", "meta" ] }, "DisputeReasonCode": { "type": "object", "additionalProperties": false, "description": "A structured reason code that can be used when disputing a return.", "properties": { "code_id": { "type": "string", "description": "Stable identifier for this dispute reason code.", "example": "received_wrong_product" }, "code": { "type": "string", "enum": [ "did_not_receive_return_parcel", "received_physical_damage", "received_incomplete", "received_wrong_product", "received_used_product", "buyer_claim_incorrect" ], "description": "Machine-readable dispute reason code accepted by the dispute endpoint.", "example": "received_wrong_product" }, "label": { "type": "string", "description": "Human-readable label for the dispute reason.", "example": "Received wrong product" }, "description": { "type": "string", "description": "Partner-facing explanation of when this dispute reason applies.", "example": "The returned parcel contains the wrong product." } }, "required": [ "code_id", "code", "label", "description" ] }, "DisputeReasonListResponse": { "type": "object", "additionalProperties": false, "description": "Dispute reason reference-data response envelope.", "example": { "success": true, "data": [ { "code_id": "received_wrong_product", "code": "received_wrong_product", "label": "Received wrong product", "description": "The returned parcel contains the wrong product." } ] }, "properties": { "success": { "type": "boolean", "description": "Whether the dispute reason list request succeeded.", "example": true }, "data": { "type": "array", "description": "Dispute reason codes currently accepted by the return dispute endpoint.", "items": { "$ref": "#/components/schemas/DisputeReasonCode" } } }, "required": [ "success", "data" ] }, "TokenData": { "type": "object", "additionalProperties": false, "properties": { "access_token": { "type": "string", "description": "Seller-scoped access token." }, "refresh_token": { "type": "string", "description": "Single-use refresh token. Rotated on every refresh." }, "expires_in": { "type": "integer", "description": "Access-token TTL in seconds.", "example": 14400 }, "expires_at": { "type": "string", "format": "date-time", "description": "Absolute access-token expiry timestamp in ISO-8601 UTC.", "example": "2026-07-16T10:30:00.000Z" }, "seller_id": { "type": "string", "description": "Seller the token acts on." }, "seller_name": { "type": "string", "nullable": true, "description": "Display name of the seller." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "OAuth scopes requested or granted." } }, "required": [ "access_token", "refresh_token", "expires_in", "expires_at", "seller_id", "scopes" ] }, "TokenResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether the request completed successfully." }, "data": { "$ref": "#/components/schemas/TokenData", "description": "Response or event payload for this schema." }, "meta": { "$ref": "#/components/schemas/PaginationMeta", "description": "Response metadata, including pagination when the endpoint returns a list." } }, "required": [ "success", "data" ] }, "RefreshTokenData": { "type": "object", "additionalProperties": false, "properties": { "access_token": { "type": "string", "description": "New seller-scoped access token." }, "refresh_token": { "type": "string", "description": "New single-use refresh token." }, "expires_in": { "type": "integer", "description": "Access-token TTL in seconds.", "example": 14400 }, "expires_at": { "type": "string", "format": "date-time", "description": "Absolute access-token expiry timestamp in ISO-8601 UTC.", "example": "2026-07-16T10:30:00.000Z" } }, "required": [ "access_token", "refresh_token", "expires_in", "expires_at" ] }, "RefreshTokenResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether the request completed successfully." }, "data": { "$ref": "#/components/schemas/RefreshTokenData", "description": "Response or event payload for this schema." }, "meta": { "$ref": "#/components/schemas/PaginationMeta", "description": "Response metadata, including pagination when the endpoint returns a list." } }, "required": [ "success", "data" ] }, "SellerVerifyData": { "type": "object", "additionalProperties": false, "description": "OTP challenge details for a seller authorization session. This does not contain an authorization code or token.", "properties": { "phone_masked": { "type": "string", "description": "Masked phone number where the OTP was sent. Empty for sandbox-shop flows without a phone.", "example": "+63900****000" }, "expires_in_seconds": { "type": "integer", "description": "Seconds until the seller authorization session and OTP challenge expire.", "example": 600 }, "resend_after_seconds": { "type": "integer", "description": "Minimum number of seconds the seller should wait before requesting another OTP.", "example": 60 }, "reference_code": { "type": "string", "description": "Optional OTP provider reference code shown to the seller when one is returned upstream.", "example": "ABC123" } }, "required": [ "phone_masked", "expires_in_seconds", "resend_after_seconds" ], "example": { "phone_masked": "+63900****000", "expires_in_seconds": 600, "resend_after_seconds": 60 } }, "SellerVerifyResponse": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ], "example": true, "description": "Whether the request completed successfully." }, "data": { "$ref": "#/components/schemas/SellerVerifyData", "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ], "example": { "success": true, "data": { "phone_masked": "+63900****000", "expires_in_seconds": 600, "resend_after_seconds": 60 } } }, "SellerVerifyOtpData": { "type": "object", "additionalProperties": false, "description": "Seller identity confirmed for the current authorization session. Consent still must be submitted before an authorization code is minted.", "properties": { "seller_id": { "type": "string", "description": "Seller identifier that will be bound to the authorization after consent.", "example": "seller_nike_ph" }, "seller_name": { "type": "string", "description": "Seller display name confirmed by the authorization session.", "example": "Nike Philippines" } }, "required": [ "seller_id", "seller_name" ], "example": { "seller_id": "seller_nike_ph", "seller_name": "Nike Philippines" } }, "SellerVerifyOtpResponse": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ], "example": true, "description": "Whether the request completed successfully." }, "data": { "$ref": "#/components/schemas/SellerVerifyOtpData", "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ], "example": { "success": true, "data": { "seller_id": "seller_nike_ph", "seller_name": "Nike Philippines" } } }, "SellerConsentData": { "type": "object", "additionalProperties": false, "description": "Authorization result returned after an OTP-verified seller grants consent. Exchange code via POST /auth/token.", "properties": { "code": { "type": "string", "description": "One-time authorization code for POST /auth/token. This is not an access token.", "example": "V1StGXR8_Z5jdHi6B-myT7zM0oLkN2pQ" }, "seller_id": { "type": "string", "description": "Seller identifier authorized for the partner app.", "example": "seller_nike_ph" }, "redirect_uri": { "type": "string", "format": "uri", "description": "Registered redirect URI associated with the consent session.", "example": "https://partner.example.com/callback" }, "state": { "type": "string", "maxLength": 1024, "description": "Opaque state originally supplied by the partner, returned unchanged when present.", "example": "partner-generated-csrf-state" } }, "required": [ "code", "seller_id", "redirect_uri" ], "example": { "code": "V1StGXR8_Z5jdHi6B-myT7zM0oLkN2pQ", "seller_id": "seller_nike_ph", "redirect_uri": "https://partner.example.com/callback", "state": "partner-generated-csrf-state" } }, "SellerConsentResponse": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ], "example": true, "description": "Whether the request completed successfully." }, "data": { "$ref": "#/components/schemas/SellerConsentData", "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ], "example": { "success": true, "data": { "code": "V1StGXR8_Z5jdHi6B-myT7zM0oLkN2pQ", "seller_id": "seller_nike_ph", "redirect_uri": "https://partner.example.com/callback", "state": "partner-generated-csrf-state" } } }, "RevokeAuthorizationData": { "type": "object", "additionalProperties": false, "properties": { "revoked": { "type": "boolean", "description": "True when an active authorization was revoked; false when there was no active grant to revoke. No affected-row count is exposed." } }, "required": [ "revoked" ], "example": { "revoked": true } }, "RevokeAuthorizationResponse": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ], "example": true, "description": "Whether the request completed successfully." }, "data": { "$ref": "#/components/schemas/RevokeAuthorizationData", "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ], "example": { "success": true, "data": { "revoked": true } } }, "DenyAuthorizationData": { "type": "object", "additionalProperties": false, "properties": { "redirect_uri": { "type": "string", "format": "uri", "description": "Registered redirect URI validated for the denied authorization request.", "example": "https://partner.example.com/callback" }, "state": { "type": "string", "maxLength": 1024, "description": "Opaque state supplied by the partner, returned unchanged when present.", "example": "partner-generated-csrf-state" } }, "required": [ "redirect_uri" ], "example": { "redirect_uri": "https://partner.example.com/callback", "state": "partner-generated-csrf-state" } }, "DenyAuthorizationResponse": { "type": "object", "additionalProperties": false, "properties": { "success": { "type": "boolean", "enum": [ true ], "example": true, "description": "Whether the request completed successfully." }, "data": { "$ref": "#/components/schemas/DenyAuthorizationData", "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ], "example": { "success": true, "data": { "redirect_uri": "https://partner.example.com/callback", "state": "partner-generated-csrf-state" } } }, "BulkOperationResult": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether the request completed successfully." }, "data": { "type": "object", "properties": { "shipped": { "type": "array", "items": { "type": "object", "properties": { "orderId": { "type": "string", "description": "Order ID associated with this value." }, "status": { "type": "string", "description": "Current status for this resource or workflow." } } }, "description": "Orders that were shipped successfully." }, "errors": { "type": "array", "items": { "type": "object", "properties": { "orderId": { "type": "string", "description": "Order ID associated with this value." }, "error": { "type": "string", "description": "Structured error payload returned when the request fails." } } }, "description": "Per-item errors returned by the bulk operation." }, "summary": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of items in this summary." }, "succeeded": { "type": "integer", "description": "Number of items that completed successfully." }, "failed": { "type": "integer", "description": "Number of items that failed." } }, "description": "Summary details." } }, "description": "Response or event payload for this schema." } } }, "FulfillmentItem": { "type": "object", "additionalProperties": false, "description": "A line item included in a fulfillment response.", "properties": { "itemId": { "type": "string", "description": "Line item ID." }, "quantity": { "type": "integer", "description": "Quantity of units." } }, "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", "description": "Shipment tracking number." }, "tracking_company": { "type": "string", "description": "Shipment tracking company name." } } }, "Fulfillment": { "type": "object", "additionalProperties": false, "description": "Partner-safe fulfillment view. Carrier-internal fields are stripped at the API boundary.", "properties": { "id": { "type": "string", "description": "Unique identifier for this resource." }, "status": { "type": "string", "enum": [ "pending", "shipped", "delivered", "cancelled" ], "description": "Current status for this resource or workflow." }, "orderId": { "type": "string", "description": "Order ID associated with this value." }, "trackingNumber": { "type": "string", "description": "Partner-provided tracking number." }, "trackingCompany": { "type": "string", "description": "Partner-provided tracking company name." }, "created_at": { "type": "string", "format": "date-time", "description": "Created at as an ISO-8601 timestamp." }, "updated_at": { "type": "string", "format": "date-time", "description": "Updated at as an ISO-8601 timestamp." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/FulfillmentItem" }, "description": "Items associated with this request, response, or event." }, "metadata": { "$ref": "#/components/schemas/FulfillmentMetadata", "description": "Allowlisted partner-visible metadata." } }, "required": [ "id", "status" ] }, "FulfillmentResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether the request completed successfully." }, "data": { "$ref": "#/components/schemas/Fulfillment", "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "FulfillmentListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether the request completed successfully." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Fulfillment" }, "description": "Response or event payload for this schema." }, "meta": { "$ref": "#/components/schemas/PaginationMeta", "description": "Response metadata, including pagination when the endpoint returns a list." } }, "required": [ "success", "data" ] }, "OrderItem": { "type": "object", "additionalProperties": false, "description": "A partner-visible order line item.", "properties": { "id": { "type": "string", "description": "Line-item identifier, unique within the order." }, "orderId": { "type": "string", "description": "Order the line item belongs to." }, "productId": { "type": "string", "description": "Product the line item was created from." }, "variantId": { "type": "string", "description": "Variant of the product that was ordered. Absent when the upstream record carries no variant." }, "title": { "type": "string", "description": "Product title as it appeared on the order." }, "sku": { "type": "string", "description": "Seller SKU of the ordered variant." }, "quantity": { "type": "integer", "description": "Units ordered for this line." }, "unitPrice": { "type": "integer", "description": "Integer amount in PHP centavos." }, "totalPrice": { "type": "integer", "description": "Integer amount in PHP centavos." }, "thumbnail": { "type": "string", "description": "Product thumbnail URL. Present only when the upstream record carries one." } } }, "Address": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Partner-visible name." }, "line1": { "type": "string", "description": "First line of the street address." }, "line2": { "type": "string", "description": "Second line of the street address, when present." }, "city": { "type": "string", "description": "PSGC-aligned Philippine city or municipality." }, "province": { "type": "string", "description": "PSGC-aligned Philippine province." }, "postalCode": { "type": "string", "description": "Postal code for the address." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code." }, "phone": { "type": "string", "description": "Contact phone number." } } }, "Order": { "type": "object", "additionalProperties": false, "description": "Partner-safe order view. Internal status fields and carrier-internal metadata are stripped.", "properties": { "id": { "type": "string", "description": "Unique identifier for this resource." }, "status": { "type": "string", "enum": [ "READY_TO_SHIP", "SHIPPED", "DELIVERED", "CANCELLED", "RETURN_REFUND" ], "description": "Current status for this resource or workflow." }, "sellerId": { "type": "string", "description": "Seller ID associated with this value." }, "customerId": { "type": "string", "description": "Customer ID associated with this order." }, "buyerEmail": { "type": "string", "format": "email", "description": "Buyer email address. Returned by GET /orders and GET /orders/{id} only, and only when the app holds the `customer:email:read` scope. Absent otherwise, and never present on webhook payloads." }, "currency": { "type": "string", "description": "ISO currency code for monetary amounts." }, "subtotal": { "type": "integer", "description": "Integer amount in PHP centavos." }, "total": { "type": "integer", "description": "Integer amount in PHP centavos." }, "tax": { "type": "integer", "description": "Integer amount in PHP centavos." }, "shipping": { "type": "integer", "description": "Integer amount in PHP centavos." }, "discount": { "type": "integer", "description": "Integer amount in PHP centavos." }, "paymentStatus": { "type": "string", "description": "Current payment status for the order." }, "fulfillmentStatus": { "type": "string", "description": "Current fulfillment status for the order." }, "created_at": { "type": "string", "format": "date-time", "description": "Created at as an ISO-8601 timestamp." }, "updated_at": { "type": "string", "format": "date-time", "description": "Updated at as an ISO-8601 timestamp." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" }, "description": "Items associated with this request, response, or event." }, "fulfillments": { "type": "array", "items": { "$ref": "#/components/schemas/Fulfillment" }, "description": "Fulfillments values." }, "shippingAddress": { "$ref": "#/components/schemas/Address", "description": "Shipping address details." }, "billingAddress": { "$ref": "#/components/schemas/Address", "description": "Billing address details." }, "shipByDate": { "type": "string", "format": "date-time", "nullable": true, "description": "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": "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)." }, "shippingChannel": { "type": "string", "description": "The forward logistics channel code the order ships via (e.g. \"STANDARD_COURIER\"), sourced from the order's selected channel. A routing key for WMS integration. Omitted when no channel has been assigned yet." }, "bookingStatus": { "type": "string", "enum": [ "PENDING_ARRANGE", "READY_FOR_HANDOVER" ], "description": "Pre-shipment booking state. PENDING_ARRANGE means paid but unbooked; READY_FOR_HANDOVER means booking arranged and awaiting courier pickup. Omitted after courier handover progresses beyond the pre-shipment booking window." } }, "required": [ "id", "status" ] }, "OrderResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether the request completed successfully." }, "data": { "$ref": "#/components/schemas/Order", "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "OrderListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether the request completed successfully." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" }, "description": "Response or event payload for this schema." }, "meta": { "$ref": "#/components/schemas/PaginationMeta", "description": "Response metadata, including pagination when the endpoint returns a list." } }, "required": [ "success", "data" ] }, "EligiblePickupDatesResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether the request completed successfully." }, "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" ], "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "PickupSlotResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether the request completed successfully." }, "data": { "$ref": "#/components/schemas/PickupSlot", "description": "Response or event payload for this schema." } }, "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", "description": "Start time in HH:mm format." }, "end": { "type": "string", "example": "18:00", "description": "End time in HH:mm format." } }, "required": [ "start", "end" ] } }, "required": [ "date", "available" ] }, "ShipmentArrangementResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether the request completed successfully." }, "data": { "$ref": "#/components/schemas/ShipmentArrangement", "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "ShipmentArrangement": { "type": "object", "additionalProperties": false, "description": "Result of arranging a shipment (pickup or dropoff). Carries the carrier tracking number plus the type-specific booking metadata. Carrier-internal pickup_rules and provider environment trace details 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", "description": "Order ID associated with this value." }, "tracking_number": { "type": "string", "description": "Carrier tracking number.", "example": "TRK1234567890" }, "tracking_url": { "type": "string", "nullable": true, "description": "Carrier tracking URL (null when the upstream provider does not return one)." }, "booking_confirmation": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "confirmed" ], "example": "confirmed", "description": "Current status for this resource or workflow." }, "message": { "type": "string", "example": "Pickup arranged successfully.", "description": "Human-readable message for this value." }, "confirmed_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp the booking was confirmed." } }, "required": [ "status", "message", "confirmed_at" ], "description": "Booking confirmation details returned by the shipment arrangement." }, "pickup_id": { "type": "string", "description": "Pickup-only. Internal pickup stamp (e.g. pickup_)." }, "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 information; null when branch information is not provided by the carrier.", "properties": { "id": { "type": "string", "description": "Unique identifier for this resource." }, "name": { "type": "string", "description": "Partner-visible name." }, "address": { "type": "string", "description": "Address value." }, "operating_hours": { "type": "string", "description": "Operating hours value." } }, "required": [ "id", "name" ] }, "drop_off_deadline": { "type": "string", "nullable": true, "format": "date-time", "description": "Dropoff-only. 3-day drop-off window expiry. ISO-8601 timestamp." } }, "required": [ "shipment_type", "order_id", "tracking_number", "tracking_url", "booking_confirmation" ] }, "OrderTrackingResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether the request completed successfully." }, "data": { "$ref": "#/components/schemas/OrderTracking", "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "OrderTracking": { "type": "object", "additionalProperties": false, "description": "Current tracking snapshot for an order's shipment. Carries the carrier tracking number, the current status, 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", "description": "Order ID associated with this value." }, "tracking_number": { "type": "string", "description": "Carrier tracking number.", "example": "TRK1234567890" }, "current_status": { "type": "string", "nullable": true, "description": "Status of the most recent tracking_update event received from the carrier. null when no scan events have been received yet.", "example": "shipped" }, "handover_status": { "type": "string", "enum": [ "READY_FOR_HANDOVER", "IN_TRANSIT", "SHIPPED", "DELIVERED" ], "description": "Explicit shipment handover/progress state. READY_FOR_HANDOVER means the booking is arranged and the parcel is awaiting courier pickup.", "example": "READY_FOR_HANDOVER" }, "latest_event": { "nullable": true, "description": "The most recent carrier tracking 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 carrier 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, "description": "Whether the request completed successfully." }, "data": { "$ref": "#/components/schemas/ShippingLabel", "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "ShippingLabel": { "type": "object", "additionalProperties": false, "description": "Print-ready AWB / shipping label for an order's shipment. Carries the carrier tracking number 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", "description": "Order ID associated with this value." }, "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": "Carrier tracking number the label was generated for.", "example": "TRK1234567890" }, "provider": { "type": "string", "description": "Logistics provider identifier (e.g. standard_carrier).", "example": "standard_carrier" } }, "required": [ "order_id", "format", "data", "tracking_number", "provider" ] }, "PickupAddressListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether the request completed successfully." }, "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", "description": "Pickup address ID." }, "name": { "type": "string", "description": "Human-readable label (full_name upstream).", "example": "Makati Main Warehouse" }, "phone": { "type": "string", "example": "+63 2 8888 1234", "description": "Contact phone number." }, "region": { "type": "string", "example": "Metro Manila", "description": "PSGC-aligned Philippine region." }, "province": { "type": "string", "example": "Metro Manila", "description": "PSGC-aligned Philippine province." }, "city": { "type": "string", "example": "Makati", "description": "PSGC-aligned Philippine city or municipality." }, "barangay": { "type": "string", "example": "Bel-Air", "description": "PSGC-aligned Philippine barangay." }, "postal_code": { "type": "string", "example": "1209", "description": "Postal code for the address." }, "detailed_address": { "type": "string", "example": "2nd Floor, Bel-Air Tower, 60 Jupiter St", "description": "Detailed street address." }, "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, "description": "Whether the request completed successfully." }, "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. STANDARD).", "example": "STANDARD" }, "name": { "type": "string", "description": "Human-readable channel name.", "example": "Standard Courier" }, "enabled": { "type": "boolean", "description": "Always true on this endpoint — the list is pre-filtered to enabled channels.", "example": true } }, "required": [ "channel_id", "name", "enabled" ] }, "ShippingOptionListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether the request completed successfully." }, "data": { "type": "array", "description": "Active platform logistics options with package-level quote status.", "items": { "$ref": "#/components/schemas/ShippingOption" } } }, "required": [ "success", "data" ] }, "ShippingOption": { "type": "object", "additionalProperties": false, "description": "A shipping option. priceAmount is PHP centavos when quoted and null when unavailable.", "properties": { "id": { "type": "string", "example": "ship_standard", "description": "Unique identifier for this resource." }, "name": { "type": "string", "example": "Standard Delivery", "description": "Partner-visible name." }, "provider": { "type": "string", "example": "Standard Courier", "description": "Logistics provider identifier." }, "priceAmount": { "type": "integer", "nullable": true, "description": "Integer amount in PHP centavos." }, "currency": { "type": "string", "example": "PHP", "description": "ISO currency code for monetary amounts." }, "estimatedDays": { "type": "string", "example": "3-5 business days", "description": "Estimated delivery time range." }, "rateStatus": { "type": "string", "enum": [ "quoted", "unavailable" ], "description": "Quote availability status." }, "rateUnavailableReason": { "type": "string", "description": "Machine-readable reason when rateStatus=unavailable." }, "description": { "type": "string", "description": "Human-readable description." } }, "required": [ "id", "name", "provider", "priceAmount", "currency", "estimatedDays", "rateStatus" ] }, "VariantPrice": { "type": "object", "additionalProperties": false, "description": "Per-variant catalogue pricing for external price mapping.", "properties": { "variant_id": { "type": "string", "description": "Variant identifier the price belongs to." }, "sku": { "type": "string", "description": "Seller SKU of the variant." }, "original_price": { "type": "integer", "description": "Base catalogue price in integer centavos. Always present." }, "sale_price": { "type": "integer", "description": "Promotional override in integer centavos. Present only when a price list exists alongside the base price." } }, "required": [ "variant_id", "sku", "original_price" ] }, "VariantPriceListResponse": { "type": "object", "example": { "success": true, "data": [ { "variant_id": "prod_OP96TBIVxmBI_v1", "sku": "NIKE-AF1-42", "original_price": 549900 } ] }, "description": "Per-variant prices for one product.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the price lookup succeeded." }, "data": { "type": "array", "description": "One entry per variant of the requested product.", "items": { "$ref": "#/components/schemas/VariantPrice" } } }, "required": [ "success", "data" ] }, "VariantPriceUpdate": { "type": "object", "additionalProperties": false, "description": "Confirmation of one applied variant price change.", "properties": { "variant_id": { "type": "string", "description": "Variant whose price was updated." }, "new_price": { "type": "integer", "description": "Integer amount in PHP centavos." } }, "required": [ "variant_id", "new_price" ] }, "VariantPriceUpdateResponse": { "type": "object", "example": { "success": true, "data": [ { "variant_id": "prod_eb-qe4ug93fc_v1", "new_price": 499900 } ] }, "description": "Applied variant price changes, echoed back per variant.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the batch price update succeeded." }, "data": { "type": "array", "description": "One entry per variant the request updated.", "items": { "$ref": "#/components/schemas/VariantPriceUpdate" } } }, "required": [ "success", "data" ] }, "VariantStockUpdate": { "type": "object", "additionalProperties": false, "description": "Confirmation of one applied variant stock change.", "properties": { "variant_id": { "type": "string", "description": "Variant whose stock was set." }, "stock_quantity": { "type": "integer", "description": "Stock level now in effect for the variant." } }, "required": [ "variant_id", "stock_quantity" ] }, "VariantStockUpdateResponse": { "type": "object", "example": { "success": true, "data": { "items": [ { "variant_id": "prod_0Q4bua7uA5PJ_v1", "stock_quantity": 25 } ] } }, "description": "Applied variant stock levels for one product.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the stock update succeeded." }, "data": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "description": "One entry per variant the request updated.", "items": { "$ref": "#/components/schemas/VariantStockUpdate" } } }, "required": [ "items" ], "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "ProductBulkCreateError": { "type": "object", "additionalProperties": false, "description": "One rejected entry from a bulk create, addressed by its position in the request.", "properties": { "index": { "type": "integer", "description": "Zero-based position of the rejected product in the submitted products array." }, "message": { "type": "string", "description": "Why this entry was rejected." } }, "required": [ "index", "message" ] }, "ProductBulkCreateResponse": { "type": "object", "example": { "success": true, "data": { "created": [ { "product_id": "prod_sQHXbsxX8EQ8", "name": "Air Force 1 Mid", "status": "proposed", "sku": "NIKE-AF1-MID-42", "price": 599900, "stock": 10, "category": "Electronics", "created_at": "2026-08-26T04:33:49.300Z", "updated_at": "2026-08-26T04:33:49.300Z" } ], "errors": [], "summary": { "total": 1, "succeeded": 1, "failed": 0 } } }, "description": "Synchronous bulk-create outcome. Partial success is normal: read errors even when some products were created. Batches submitted for asynchronous processing answer 202 with a job handle instead of this body.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the bulk request was processed." }, "data": { "type": "object", "additionalProperties": false, "properties": { "created": { "type": "array", "description": "Products that were created, in submission order.", "items": { "$ref": "#/components/schemas/Product" } }, "errors": { "type": "array", "description": "Entries that were rejected. Empty when every product was created.", "items": { "$ref": "#/components/schemas/ProductBulkCreateError" } }, "summary": { "type": "object", "additionalProperties": false, "description": "Counts for the submitted batch.", "properties": { "total": { "type": "integer", "description": "Total number of items in this summary." }, "succeeded": { "type": "integer", "description": "Number of items that completed successfully." }, "failed": { "type": "integer", "description": "Number of items that failed." } }, "required": [ "total", "succeeded", "failed" ] } }, "required": [ "created", "errors", "summary" ], "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "ProductStatusUpdateResponse": { "type": "object", "example": { "success": true, "data": { "id": "prod_uzikp4otJwDq", "status": "live" } }, "description": "The status now in effect for the product, echoed back verbatim.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the status change was applied." }, "data": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Product whose status changed." }, "status": { "type": "string", "enum": [ "live", "unlisted", "delisted", "proposed", "under_review", "archived" ], "description": "Status now in effect. The platform echoes what was applied, never a substitute." } }, "required": [ "id", "status" ], "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "ProductDeleteResponse": { "type": "object", "example": { "success": true, "data": { "id": "prod_Df3oBRhaGyNP", "deleted": true } }, "description": "Confirmation that the product was deleted.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the delete succeeded." }, "data": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "Product that was deleted." }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Always true on a successful delete." } }, "required": [ "id", "deleted" ], "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "OrderItemListResponse": { "type": "object", "example": { "success": true, "data": [ { "id": "item_CHMTF2ON9QK3VJ_0", "orderId": "CHMTF2ON9QK3VJ", "productId": "prod_048222330", "title": "Bamboo Cutting Board Set", "sku": "HOME-4001", "quantity": 2, "unitPrice": 59900, "totalPrice": 119800 }, { "id": "item_CHMTF2ON9QK3VJ_1", "orderId": "CHMTF2ON9QK3VJ", "productId": "prod_839692237", "title": "Premium Leather Wallet", "sku": "FASH-2001", "quantity": 4, "unitPrice": 89900, "totalPrice": 359600 }, { "id": "item_CHMTF2ON9QK3VJ_2", "orderId": "CHMTF2ON9QK3VJ", "productId": "prod_713430108", "title": "Organic Matcha Powder", "sku": "FOOD-3001", "quantity": 4, "unitPrice": 34900, "totalPrice": 139600 } ] }, "description": "Line items of one order. The list is complete - this endpoint is not paginated.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the line-item read succeeded." }, "data": { "type": "array", "description": "Every line item on the order, in upstream order.", "items": { "$ref": "#/components/schemas/OrderItem" } } }, "required": [ "success", "data" ] }, "BulkOrderOutcome": { "type": "object", "additionalProperties": false, "description": "One order that the bulk request processed successfully.", "properties": { "orderId": { "type": "string", "description": "Order that was processed." }, "status": { "type": "string", "description": "State the order is now in." } }, "required": [ "orderId", "status" ] }, "BulkOrderError": { "type": "object", "additionalProperties": false, "description": "One order the bulk request could not process.", "properties": { "orderId": { "type": "string", "description": "Order that failed." }, "error": { "type": "string", "description": "Why this order could not be processed." }, "code": { "type": "string", "description": "Machine-readable reason, when the failure maps to a catalogued error code." } }, "required": [ "orderId", "error" ] }, "BulkOrderSummary": { "type": "object", "additionalProperties": false, "description": "Counts for the submitted batch.", "properties": { "total": { "type": "integer", "description": "Number of orders submitted." }, "succeeded": { "type": "integer", "description": "Number of orders processed successfully." }, "failed": { "type": "integer", "description": "Number of orders that failed." } }, "required": [ "total", "succeeded", "failed" ] }, "BulkOrderShipResponse": { "type": "object", "example": { "success": true, "data": { "shipped": [ { "orderId": "5RR0SWUDOL4Z65", "status": "shipped" } ], "errors": [], "summary": { "total": 1, "succeeded": 1, "failed": 0 } } }, "description": "Synchronous bulk-ship outcome. Partial success is normal: read errors even when some orders shipped. Asynchronous submissions answer 202 with a job handle instead of this body.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the bulk request was processed." }, "data": { "type": "object", "additionalProperties": false, "properties": { "shipped": { "type": "array", "description": "Orders that were shipped.", "items": { "$ref": "#/components/schemas/BulkOrderOutcome" } }, "errors": { "type": "array", "description": "Orders that could not be shipped. Empty when every order succeeded.", "items": { "$ref": "#/components/schemas/BulkOrderError" } }, "summary": { "$ref": "#/components/schemas/BulkOrderSummary", "description": "Summary details." } }, "required": [ "shipped", "errors", "summary" ], "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "BulkOrderCancelResponse": { "type": "object", "example": { "success": true, "data": { "cancelled": [ { "orderId": "QPS3OJQ6DF2QNL", "status": "cancelled" } ], "errors": [], "summary": { "total": 1, "succeeded": 1, "failed": 0 } } }, "description": "Synchronous bulk-cancel outcome. Partial success is normal: read errors even when some orders were cancelled. Asynchronous submissions answer 202 with a job handle instead of this body.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the bulk request was processed." }, "data": { "type": "object", "additionalProperties": false, "properties": { "cancelled": { "type": "array", "description": "Orders that were cancelled.", "items": { "$ref": "#/components/schemas/BulkOrderOutcome" } }, "errors": { "type": "array", "description": "Orders that could not be cancelled. Empty when every order succeeded.", "items": { "$ref": "#/components/schemas/BulkOrderError" } }, "summary": { "$ref": "#/components/schemas/BulkOrderSummary", "description": "Summary details." } }, "required": [ "cancelled", "errors", "summary" ], "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "Seller": { "type": "object", "additionalProperties": false, "description": "A seller in the marketplace directory.", "properties": { "id": { "type": "string", "description": "Seller identifier used as X-MallPlus-Seller-Id on seller-scoped calls." }, "name": { "type": "string", "description": "Seller name." }, "store_name": { "type": "string", "description": "Storefront name, when it differs from the seller name." }, "email": { "type": "string", "description": "Seller contact email. Present only when the upstream record exposes one." }, "logo": { "type": "string", "description": "Seller logo URL." }, "description": { "type": "string", "description": "Seller description shown on the storefront." }, "created_at": { "type": "string", "format": "date-time", "description": "When the seller was created. ISO-8601 timestamp." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the seller was last updated. ISO-8601 timestamp." } }, "required": [ "id", "name" ] }, "SellerListResponse": { "type": "object", "example": { "success": true, "data": [ { "id": "sel_IYzKSV3YnOou", "name": "Nike PH Official Store" } ], "meta": { "page": 1, "limit": 1, "total": 1 } }, "description": "Seller directory listing. Called with seller headers it returns just that seller; called without them it returns the platform directory page.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the seller list request succeeded." }, "data": { "type": "array", "description": "Sellers on this page.", "items": { "$ref": "#/components/schemas/Seller" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta", "description": "Response metadata, including pagination when the endpoint returns a list." } }, "required": [ "success", "data" ] }, "SellerResponse": { "type": "object", "example": { "success": true, "data": { "id": "sel_Oy4-2R7G9OdY", "name": "Nike PH Official Store" } }, "description": "A single seller.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the seller read succeeded." }, "data": { "$ref": "#/components/schemas/Seller", "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "Shop": { "type": "object", "additionalProperties": false, "description": "Profile of the shop the request is authenticated for.", "properties": { "shop_id": { "type": "string", "description": "Identifier of the authenticated shop." }, "name": { "type": "string", "description": "Shop name." }, "description": { "type": "string", "description": "Shop description shown on the storefront." }, "logo": { "type": "string", "description": "Shop logo URL." }, "category": { "type": "object", "additionalProperties": false, "nullable": true, "description": "Merchandising category of the shop. Null when the shop has none.", "properties": { "id": { "type": "string", "description": "Shop category identifier." }, "name": { "type": "string", "description": "Shop category name." } }, "required": [ "id", "name" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "SUSPENDED", "PENDING" ], "description": "Operating state of the shop: ACTIVE - trading normally; PENDING - approved store whose shop record is still awaiting review; SUSPENDED - trading stopped by the platform; INACTIVE - store closed. Absent when the upstream record does not report a store status." }, "created_at": { "type": "string", "format": "date-time", "description": "When the shop was created. ISO-8601 timestamp." } }, "required": [ "shop_id", "name" ] }, "ShopResponse": { "type": "object", "example": { "success": true, "data": { "shop_id": "sel_E5V1ygvcruzd", "name": "Nike PH Official Store", "description": "Sandbox shop for testing the MallPlus Open API", "logo": "https://sandbox.mallplus.ph/shop-logo.png", "category": { "id": "pcat_sandbox", "name": "General" }, "status": "ACTIVE", "created_at": "2026-01-01T00:00:00.000Z" } }, "description": "Profile of the authenticated shop.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the shop read succeeded." }, "data": { "$ref": "#/components/schemas/Shop", "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "ShopStatus": { "type": "object", "additionalProperties": false, "description": "Live-trading state of the authenticated shop.", "properties": { "shop_id": { "type": "string", "description": "Identifier of the authenticated shop." }, "status": { "type": "string", "enum": [ "ACTIVE", "PENDING", "SUSPENDED", "INACTIVE" ], "description": "Operating state of the shop: ACTIVE - trading normally; PENDING - approved store whose shop record is still awaiting review; SUSPENDED - trading stopped by the platform; INACTIVE - store closed." }, "is_live": { "type": "boolean", "description": "Whether the shop is currently visible and able to trade. True only when the store is ACTIVE and its shop record is past PENDING." }, "last_status_changed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the status last changed. Null when the upstream record has never reported a change. ISO-8601 timestamp." } }, "required": [ "shop_id", "status", "is_live", "last_status_changed_at" ] }, "ShopStatusResponse": { "type": "object", "example": { "success": true, "data": { "shop_id": "sel_mXFhraLPCEbq", "status": "ACTIVE", "is_live": true, "last_status_changed_at": null } }, "description": "Live-trading state of the authenticated shop.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the shop status read succeeded." }, "data": { "$ref": "#/components/schemas/ShopStatus", "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "SellerProfile": { "type": "object", "additionalProperties": false, "description": "Self-profile of the seller the request is authenticated for.", "properties": { "id": { "type": "string", "description": "Identifier of the authenticated seller." }, "name": { "type": "string", "description": "Seller name." }, "store_name": { "type": "string", "description": "Storefront name, when it differs from the seller name." }, "logo": { "type": "string", "description": "Seller logo URL." }, "description": { "type": "string", "description": "Seller description shown on the storefront." }, "created_at": { "type": "string", "format": "date-time", "description": "When the seller was created. ISO-8601 timestamp." }, "updated_at": { "type": "string", "format": "date-time", "description": "When the seller was last updated. ISO-8601 timestamp." } }, "required": [ "id", "name" ] }, "SellerProfileResponse": { "type": "object", "example": { "success": true, "data": { "id": "sel_2ke1Ofpi6f0Z", "name": "Nike PH Official Store" } }, "description": "Self-profile of the authenticated seller.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the seller profile read succeeded." }, "data": { "$ref": "#/components/schemas/SellerProfile", "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "ApiCallEndpointStats": { "type": "object", "additionalProperties": false, "description": "Call counts for one endpoint over the requested window.", "properties": { "endpoint": { "type": "string", "description": "Endpoint path or route pattern the counts belong to." }, "successCalls": { "type": "integer", "description": "Calls that returned a 2xx status." }, "failCalls": { "type": "integer", "description": "Calls that returned a non-2xx status." }, "totalCalls": { "type": "integer", "description": "All calls to this endpoint in the window." }, "successRate": { "type": "number", "description": "Share of calls that succeeded, from 0 to 1." } }, "required": [ "endpoint", "successCalls", "failCalls", "totalCalls", "successRate" ] }, "ApiCallSeriesBucket": { "type": "object", "additionalProperties": false, "description": "One time bucket of the usage series.", "properties": { "ts": { "type": "string", "format": "date-time", "description": "Start of the bucket, in UTC. ISO-8601 timestamp." }, "totalCalls": { "type": "integer", "description": "All calls in this bucket." }, "successCalls": { "type": "integer", "description": "Calls that returned a 2xx status." }, "failCalls": { "type": "integer", "description": "Calls that returned a non-2xx status." } }, "required": [ "ts", "totalCalls", "successCalls", "failCalls" ] }, "QuotaMeter": { "type": "object", "additionalProperties": false, "description": "Live rate-limit meter for the calling app, read at request time.", "properties": { "window": { "type": "string", "enum": [ "per_minute" ], "description": "Window the meter counts over." }, "limit": { "type": "integer", "description": "Requests allowed in the window for this app." }, "used": { "type": "integer", "description": "Requests already charged against the current window." }, "remaining": { "type": "integer", "description": "Requests still available in the current window." }, "resetAt": { "type": "integer", "nullable": true, "description": "Unix seconds at which the current window resets. Null when the app is idle (no open window) or the meter store is unavailable." } }, "required": [ "window", "limit", "used", "remaining", "resetAt" ] }, "UsageResponse": { "type": "object", "example": { "success": true, "data": { "summary": { "successRate": 0.98, "successCalls": 490, "failCalls": 10, "totalCalls": 500 }, "endpoints": [ { "endpoint": "/open/v1/orders", "successCalls": 300, "failCalls": 4, "totalCalls": 304, "successRate": 0.9868 }, { "endpoint": "/open/v1/products", "successCalls": 190, "failCalls": 6, "totalCalls": 196, "successRate": 0.9694 } ], "quota": { "window": "per_minute", "limit": 600, "used": 42, "remaining": 558, "resetAt": 1787649944 }, "series": { "granularity": "daily", "from": "2026-08-19T00:00:00.000Z", "to": "2026-08-26T00:00:00.000Z", "buckets": [ { "ts": "2026-08-25T00:00:00.000Z", "totalCalls": 120, "successCalls": 118, "failCalls": 2 } ] } } }, "description": "The calling app's own API-call statistics. Scoped to the authenticated app - there is no cross-app view. Pass granularity=daily|hourly to include the time series.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the usage read succeeded." }, "data": { "type": "object", "additionalProperties": false, "properties": { "summary": { "type": "object", "additionalProperties": false, "description": "Totals across every endpoint in the window.", "properties": { "successRate": { "type": "number", "description": "Share of calls that succeeded, from 0 to 1." }, "successCalls": { "type": "integer", "description": "Calls that returned a 2xx status." }, "failCalls": { "type": "integer", "description": "Calls that returned a non-2xx status." }, "totalCalls": { "type": "integer", "description": "All calls in the window." } }, "required": [ "successRate", "successCalls", "failCalls", "totalCalls" ] }, "endpoints": { "type": "array", "description": "Per-endpoint breakdown.", "items": { "$ref": "#/components/schemas/ApiCallEndpointStats" } }, "quota": { "$ref": "#/components/schemas/QuotaMeter", "description": "Quota details." }, "series": { "type": "object", "additionalProperties": false, "description": "Time series. Present only when the request passes granularity.", "properties": { "granularity": { "type": "string", "enum": [ "daily", "hourly" ], "description": "Bucket size of the series." }, "from": { "type": "string", "format": "date-time", "description": "Start of the series window, in UTC. ISO-8601 timestamp." }, "to": { "type": "string", "format": "date-time", "description": "End of the series window, in UTC. ISO-8601 timestamp." }, "buckets": { "type": "array", "description": "Buckets in chronological order.", "items": { "$ref": "#/components/schemas/ApiCallSeriesBucket" } } }, "required": [ "granularity", "from", "to", "buckets" ] } }, "required": [ "summary", "endpoints", "quota" ], "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "AccessLog": { "type": "object", "additionalProperties": false, "description": "One recorded API call made with the calling app credentials.", "properties": { "id": { "type": "string", "description": "Access-log entry identifier." }, "partnerAppId": { "type": "string", "description": "App the call was made with." }, "endpoint": { "type": "string", "description": "Path that was called." }, "method": { "type": "string", "description": "HTTP method of the call." }, "statusCode": { "type": "integer", "description": "HTTP status the platform answered with." }, "requestId": { "type": "string", "description": "Request identifier echoed on the response - quote it when contacting support." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the call was received. ISO-8601 timestamp." } }, "required": [ "id", "partnerAppId", "endpoint", "method", "statusCode", "requestId", "createdAt" ] }, "AccessLogListResponse": { "type": "object", "example": { "success": true, "data": [ { "id": "log_01J8XYZ", "partnerAppId": "app-usage-logs-schema", "endpoint": "/open/v1/orders", "method": "GET", "statusCode": 200, "requestId": "01M0VZQDM5VZZ6157NCN8807Q1", "createdAt": "2026-08-26T03:15:00.000Z" } ], "meta": { "page": 1, "limit": 20, "total": 1 } }, "description": "The calling app's own access log. Scoped to the authenticated app.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the access-log read succeeded." }, "data": { "type": "array", "description": "Access-log entries on this page, newest first.", "items": { "$ref": "#/components/schemas/AccessLog" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta", "description": "Response metadata, including pagination when the endpoint returns a list." } }, "required": [ "success", "data" ] }, "Webhook": { "type": "object", "additionalProperties": false, "description": "A webhook subscription owned by the calling app.", "properties": { "id": { "type": "string", "description": "Subscription identifier." }, "partnerAppId": { "type": "string", "description": "App that owns the subscription." }, "eventType": { "type": "string", "enum": [ "order.created", "order.updated", "order.shipped", "order.cancelled", "order.status.updated", "inventory.updated", "product.created", "product.updated", "product.stock.updated", "product.price.updated", "product.deleted", "fulfillment.created", "fulfillment.updated", "fulfillment.shipped", "return.created", "return.approved", "return.rejected", "return.disputed", "return.status.updated", "authorization.granted", "authorization.revoked", "authorization.expiring" ], "description": "Event this subscription delivers." }, "callbackUrl": { "type": "string", "description": "HTTPS endpoint the platform posts deliveries to." }, "isActive": { "type": "boolean", "description": "Whether deliveries are currently sent. An inactive subscription is kept but not delivered to." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the subscription was created. ISO-8601 timestamp." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the subscription was last updated. ISO-8601 timestamp." } }, "required": [ "id", "partnerAppId", "eventType", "callbackUrl", "isActive", "createdAt", "updatedAt" ] }, "WebhookListResponse": { "type": "object", "example": { "success": true, "data": [ { "id": "whs_01J8XYZ", "partnerAppId": "app_01J8ABC", "eventType": "order.created", "callbackUrl": "https://partner.example.com/hooks/mallplus", "isActive": true, "createdAt": "2026-08-26T03:15:00.000Z", "updatedAt": "2026-08-26T03:15:00.000Z" } ], "meta": { "page": 1, "limit": 20, "total": 1 } }, "description": "The calling app's webhook subscriptions. An app only ever sees its own.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the subscription list read succeeded." }, "data": { "type": "array", "description": "Subscriptions on this page.", "items": { "$ref": "#/components/schemas/Webhook" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta", "description": "Response metadata, including pagination when the endpoint returns a list." } }, "required": [ "success", "data" ] }, "WebhookResponse": { "type": "object", "example": { "success": true, "data": { "id": "whs_01J8XYZ", "partnerAppId": "app_01J8ABC", "eventType": "order.created", "callbackUrl": "https://partner.example.com/hooks/mallplus", "isActive": true, "createdAt": "2026-08-26T03:15:00.000Z", "updatedAt": "2026-08-26T03:15:00.000Z" } }, "description": "A single webhook subscription.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the subscription request succeeded." }, "data": { "$ref": "#/components/schemas/Webhook", "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "WebhookDeleteResponse": { "type": "object", "example": { "success": true, "data": { "deleted": true } }, "description": "Confirmation that the subscription was deleted.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the delete succeeded." }, "data": { "type": "object", "additionalProperties": false, "properties": { "deleted": { "type": "boolean", "enum": [ true ], "description": "Always true on a successful delete." } }, "required": [ "deleted" ], "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "WebhookTestResponse": { "type": "object", "example": { "success": true, "data": { "accepted": true, "event": "order.created" } }, "description": "Acknowledgement that a test delivery was accepted. The platform answers 202 and dispatches asynchronously - a 202 means accepted for delivery, not delivered.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the test dispatch was accepted." }, "data": { "type": "object", "additionalProperties": false, "properties": { "accepted": { "type": "boolean", "enum": [ true ], "description": "Always true when the platform queued the test delivery." }, "event": { "type": "string", "enum": [ "order.created", "order.updated", "order.shipped", "order.cancelled", "order.status.updated", "inventory.updated", "product.created", "product.updated", "product.stock.updated", "product.price.updated", "product.deleted", "fulfillment.created", "fulfillment.updated", "fulfillment.shipped", "return.created", "return.approved", "return.rejected", "return.disputed", "return.status.updated", "authorization.granted", "authorization.revoked", "authorization.expiring" ], "description": "Event type the test delivery was queued for." } }, "required": [ "accepted", "event" ], "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "CredentialRotationResponse": { "type": "object", "example": { "success": true, "data": { "clientId": "mp_d6a1c3...", "clientSecret": "", "message": "Sandbox secret rotated. Store this secret - it will not be shown again." } }, "description": "Newly issued sandbox credentials. The secret is returned ONCE and is never retrievable again - store it before discarding the response.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the rotation succeeded." }, "data": { "type": "object", "additionalProperties": false, "properties": { "clientId": { "type": "string", "description": "Sandbox client ID. Unchanged by rotation." }, "clientSecret": { "type": "string", "description": "The new sandbox secret, shown once. The previous secret stops working immediately." }, "message": { "type": "string", "description": "Human-readable reminder that the secret is shown only once." } }, "required": [ "clientId", "clientSecret", "message" ], "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "LiveCredentialRotationResponse": { "type": "object", "example": { "success": true, "data": { "clientIdLive": "mp_live_a1b2c3...", "clientSecretLive": "", "message": "Production secret rotated. Store this secret - it will not be shown again." } }, "description": "Newly issued production credentials. The secret is returned ONCE and is never retrievable again - store it before discarding the response.", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Whether the rotation succeeded." }, "data": { "type": "object", "additionalProperties": false, "properties": { "clientIdLive": { "type": "string", "description": "Production client ID. Unchanged by rotation." }, "clientSecretLive": { "type": "string", "description": "The new production secret, shown once. The previous secret stops working immediately." }, "message": { "type": "string", "description": "Human-readable reminder that the secret is shown only once." } }, "required": [ "clientIdLive", "clientSecretLive", "message" ], "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "CategoryListResponse": { "type": "object", "description": "Product category list response for platform catalog reference data.", "example": { "success": true, "data": [ { "category_id": "pcat_936307F9C749623D4DE7928B", "name": "Speakers", "parent_category_id": "pcat_4684804378598A4C767AAC81" } ], "meta": { "page": 1, "limit": 1, "total": 8 } }, "properties": { "success": { "type": "boolean", "description": "Whether the category list request succeeded.", "example": true }, "data": { "type": "array", "description": "Product categories available for product creation and browsing.", "items": { "$ref": "#/components/schemas/Category" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta", "description": "Response metadata, including pagination when the endpoint returns a list." } }, "required": [ "success", "data" ] }, "Category": { "type": "object", "additionalProperties": false, "description": "A product category in the public catalog tree.", "properties": { "category_id": { "type": "string", "description": "Stable category identifier used by product endpoints.", "example": "pcat_936307F9C749623D4DE7928B" }, "name": { "type": "string", "description": "Human-readable category name.", "example": "Electronics" }, "handle": { "type": "string", "description": "Optional URL-safe category handle when upstream provides one.", "example": "electronics" }, "description": { "type": "string", "description": "Optional category description when upstream provides one.", "example": "Phones, computers, and consumer electronics." }, "parent_category_id": { "type": "string", "nullable": true, "description": "Parent category identifier. Root categories return null.", "example": null } }, "required": [ "category_id", "name", "parent_category_id" ] }, "CategoryAttributeListResponse": { "type": "object", "description": "Attribute definitions that apply to a specific product category.", "example": { "success": true, "data": [ { "attribute_id": "attr_color", "name": "Color", "type": "select", "required": false, "allowed_values": [ "Black", "White", "Silver" ] } ] }, "properties": { "success": { "type": "boolean", "description": "Whether the category attribute request succeeded.", "example": true }, "data": { "type": "array", "description": "Attribute definitions configured for the requested category.", "items": { "$ref": "#/components/schemas/CategoryAttribute" } } }, "required": [ "success", "data" ] }, "CategoryAttribute": { "type": "object", "additionalProperties": false, "description": "An attribute definition configured for a product category.", "properties": { "attribute_id": { "type": "string", "description": "Stable attribute identifier used when supplying category-specific product attributes.", "example": "attr_color" }, "name": { "type": "string", "description": "Human-readable attribute name.", "example": "Color" }, "type": { "type": "string", "description": "UI input hint from the category attribute definition, such as select or input. This is not a closed enum; new values may appear.", "example": "select" }, "required": { "type": "boolean", "description": "Whether products in this category must provide a value for the attribute.", "example": false }, "allowed_values": { "type": "array", "description": "Allowed string values for select-style attributes when the upstream definition provides them.", "items": { "type": "string", "description": "Allowed attribute value.", "example": "Black" }, "example": [ "Black", "White", "Silver" ] } }, "required": [ "attribute_id", "name", "required" ] }, "AttributeListResponse": { "type": "object", "description": "Global product attribute definition list response.", "example": { "success": true, "data": [ { "attribute_id": "attr_color", "name": "Color", "type": "select" } ], "meta": { "page": 1, "limit": 1, "total": 5 } }, "properties": { "success": { "type": "boolean", "description": "Whether the attribute list request succeeded.", "example": true }, "data": { "type": "array", "description": "Global product attribute definitions available on the platform.", "items": { "$ref": "#/components/schemas/Attribute" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta", "description": "Response metadata, including pagination when the endpoint returns a list." } }, "required": [ "success", "data" ] }, "Attribute": { "type": "object", "additionalProperties": false, "description": "A global product attribute definition.", "properties": { "attribute_id": { "type": "string", "description": "Stable attribute identifier.", "example": "attr_color" }, "name": { "type": "string", "description": "Human-readable attribute name.", "example": "Color" }, "type": { "type": "string", "description": "UI input hint from the attribute definition, such as select, multivalue, unit, or text_area. This is not a closed enum; new values may appear.", "example": "select" } }, "required": [ "attribute_id", "name" ] }, "SandboxListMeta": { "type": "object", "additionalProperties": false, "description": "Count metadata returned by sandbox list operations.", "properties": { "totalCount": { "type": "integer", "minimum": 0, "description": "Total number of sandbox records visible to the authenticated sandbox app.", "example": 1 } }, "required": [ "totalCount" ] }, "SandboxSeller": { "type": "object", "additionalProperties": false, "description": "Partner-visible sandbox seller used for OAuth and order simulation.", "example": { "id": "sel_seeded_contract", "name": "Sandbox Seller", "email": "sandbox-seller@example.com", "storeName": "Sandbox Default Store", "status": "active", "sandboxId": "sandbox_response_contract", "oauthIdentifier": "sel_seeded_contract", "createdAt": "2026-08-26T04:00:00.000Z", "updatedAt": "2026-08-26T04:00:00.000Z" }, "properties": { "id": { "type": "string", "description": "Sandbox seller identifier used by sandbox order and seller OAuth flows.", "example": "sel_seeded_contract" }, "name": { "type": "string", "description": "Display name of the test seller.", "example": "Sandbox Seller" }, "email": { "type": "string", "format": "email", "description": "Email address assigned to the test seller.", "example": "sandbox-seller@example.com" }, "storeName": { "type": "string", "description": "Storefront name assigned to the test seller.", "example": "Sandbox Default Store" }, "status": { "type": "string", "enum": [ "active", "suspended" ], "description": "Lifecycle status of the test seller within the sandbox.", "example": "active" }, "sandboxId": { "type": "string", "description": "Sandbox shop identifier linked to a seeded seller when the seller was created from a sandbox shop.", "example": "sandbox_response_contract" }, "oauthIdentifier": { "type": "string", "description": "Identifier partners use for seller OAuth sandbox consent. Present only for sellers linked to a sandbox shop.", "example": "sel_seeded_contract" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 UTC timestamp when the sandbox seller was created.", "example": "2026-08-26T04:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 UTC timestamp when the sandbox seller was last updated.", "example": "2026-08-26T04:00:00.000Z" } }, "required": [ "id", "name", "email", "storeName", "status", "createdAt", "updatedAt" ] }, "SandboxSellerResponse": { "type": "object", "additionalProperties": false, "description": "Single sandbox seller response.", "example": { "success": true, "data": { "id": "sel_test_contract", "name": "Test Seller", "email": "seller@example.com", "storeName": "Test Store", "status": "active", "createdAt": "2026-08-26T04:00:00.000Z", "updatedAt": "2026-08-26T04:00:00.000Z" } }, "properties": { "success": { "type": "boolean", "description": "Whether the sandbox seller request succeeded.", "example": true }, "data": { "$ref": "#/components/schemas/SandboxSeller", "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "SandboxSellerListResponse": { "type": "object", "additionalProperties": false, "description": "Sandbox seller list response for the authenticated sandbox app.", "example": { "success": true, "data": [ { "id": "sel_seeded_contract", "name": "Sandbox Seller", "email": "sandbox-seller@example.com", "storeName": "Sandbox Default Store", "status": "active", "sandboxId": "sandbox_response_contract", "oauthIdentifier": "sel_seeded_contract", "createdAt": "2026-08-26T04:00:00.000Z", "updatedAt": "2026-08-26T04:00:00.000Z" } ], "meta": { "totalCount": 1 } }, "properties": { "success": { "type": "boolean", "description": "Whether the sandbox seller list request succeeded.", "example": true }, "data": { "type": "array", "description": "Sandbox sellers visible to the authenticated sandbox app.", "items": { "$ref": "#/components/schemas/SandboxSeller" } }, "meta": { "$ref": "#/components/schemas/SandboxListMeta", "description": "Response metadata, including pagination when the endpoint returns a list." } }, "required": [ "success", "data", "meta" ] }, "SandboxBuyerShippingAddress": { "type": "object", "additionalProperties": false, "description": "Shipping address assigned to a sandbox buyer.", "properties": { "line1": { "type": "string", "description": "Primary street address line.", "example": "1 Sandbox St" }, "line2": { "type": "string", "description": "Optional secondary street address line such as unit or floor.", "example": "Unit 2" }, "city": { "type": "string", "description": "PSGC-aligned Philippine city or municipality.", "example": "Manila" }, "region": { "type": "string", "description": "PSGC-aligned Philippine region.", "example": "NCR" }, "postalCode": { "type": "string", "description": "Postal code for the sandbox buyer shipping address.", "example": "1000" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code for the shipping address.", "example": "PH" } }, "required": [ "line1", "city", "region", "postalCode", "country" ] }, "SandboxBuyer": { "type": "object", "additionalProperties": false, "description": "Partner-visible sandbox buyer used for buyer-driven order simulation.", "example": { "id": "buy_test_contract", "name": "Sandbox Buyer", "email": "sandbox-buyer@example.com", "phoneNumber": "+639001112233", "shippingAddress": { "line1": "1 Sandbox St", "city": "Manila", "region": "NCR", "postalCode": "1000", "country": "PH" }, "createdAt": "2026-08-26T04:00:00.000Z", "updatedAt": "2026-08-26T04:00:00.000Z" }, "properties": { "id": { "type": "string", "description": "Sandbox buyer identifier used by sandbox order flows.", "example": "buy_test_contract" }, "name": { "type": "string", "description": "Display name of the test buyer.", "example": "Sandbox Buyer" }, "email": { "type": "string", "format": "email", "description": "Email address assigned to the test buyer.", "example": "sandbox-buyer@example.com" }, "phoneNumber": { "type": "string", "description": "Phone number assigned to the test buyer.", "example": "+639001112233" }, "shippingAddress": { "$ref": "#/components/schemas/SandboxBuyerShippingAddress", "description": "Shipping address details." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 UTC timestamp when the sandbox buyer was created.", "example": "2026-08-26T04:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 UTC timestamp when the sandbox buyer was last updated.", "example": "2026-08-26T04:00:00.000Z" } }, "required": [ "id", "name", "email", "phoneNumber", "shippingAddress", "createdAt", "updatedAt" ] }, "SandboxBuyerResponse": { "type": "object", "additionalProperties": false, "description": "Single sandbox buyer response.", "example": { "success": true, "data": { "id": "buy_test_contract", "name": "Test Buyer", "email": "buyer@example.com", "phoneNumber": "+639001234567", "shippingAddress": { "line1": "123 Test St", "city": "Manila", "region": "NCR", "postalCode": "1000", "country": "PH" }, "createdAt": "2026-08-26T04:00:00.000Z", "updatedAt": "2026-08-26T04:00:00.000Z" } }, "properties": { "success": { "type": "boolean", "description": "Whether the sandbox buyer request succeeded.", "example": true }, "data": { "$ref": "#/components/schemas/SandboxBuyer", "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "SandboxBuyerListResponse": { "type": "object", "additionalProperties": false, "description": "Sandbox buyer list response for the authenticated sandbox app.", "example": { "success": true, "data": [ { "id": "buy_test_contract", "name": "Sandbox Buyer", "email": "sandbox-buyer@example.com", "phoneNumber": "+639001112233", "shippingAddress": { "line1": "1 Sandbox St", "city": "Manila", "region": "NCR", "postalCode": "1000", "country": "PH" }, "createdAt": "2026-08-26T04:00:00.000Z", "updatedAt": "2026-08-26T04:00:00.000Z" } ], "meta": { "totalCount": 1 } }, "properties": { "success": { "type": "boolean", "description": "Whether the sandbox buyer list request succeeded.", "example": true }, "data": { "type": "array", "description": "Sandbox buyers visible to the authenticated sandbox app.", "items": { "$ref": "#/components/schemas/SandboxBuyer" } }, "meta": { "$ref": "#/components/schemas/SandboxListMeta", "description": "Response metadata, including pagination when the endpoint returns a list." } }, "required": [ "success", "data", "meta" ] }, "SandboxSeedData": { "type": "object", "additionalProperties": false, "description": "Sandbox fixture set created or refreshed by the seed operation.", "properties": { "seller": { "$ref": "#/components/schemas/SandboxSeller", "description": "Seller details." }, "buyer": { "$ref": "#/components/schemas/SandboxBuyer", "description": "Buyer details." }, "productsCount": { "type": "integer", "minimum": 0, "description": "Number of sandbox products available after the seed operation.", "example": 5 } }, "required": [ "seller", "buyer", "productsCount" ] }, "SandboxSeedResponse": { "type": "object", "additionalProperties": false, "description": "Sandbox fixture seed response.", "example": { "success": true, "data": { "seller": { "id": "sel_seeded_contract", "name": "Sandbox Seller", "email": "sandbox-seller@example.com", "storeName": "Sandbox Default Store", "status": "active", "sandboxId": "sandbox_response_contract", "oauthIdentifier": "sel_seeded_contract", "createdAt": "2026-08-26T04:00:00.000Z", "updatedAt": "2026-08-26T04:00:00.000Z" }, "buyer": { "id": "buy_test_contract", "name": "Sandbox Buyer", "email": "sandbox-buyer@example.com", "phoneNumber": "+639001112233", "shippingAddress": { "line1": "1 Sandbox St", "city": "Manila", "region": "NCR", "postalCode": "1000", "country": "PH" }, "createdAt": "2026-08-26T04:00:00.000Z", "updatedAt": "2026-08-26T04:00:00.000Z" }, "productsCount": 5 } }, "properties": { "success": { "type": "boolean", "description": "Whether the sandbox seed request succeeded.", "example": true }, "data": { "$ref": "#/components/schemas/SandboxSeedData", "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "ProductVariant": { "type": "object", "additionalProperties": false, "description": "A single purchasable variant of a product.", "properties": { "variant_id": { "type": "string", "description": "Product variant ID associated with this value." }, "sku": { "type": "string", "nullable": true, "description": "Seller SKU." }, "price": { "type": "integer", "description": "Integer amount in PHP centavos.", "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, "description": "One option of the variant, as a name/value pair.", "properties": { "name": { "type": "string", "nullable": true, "description": "Option name, for example Size." }, "value": { "type": "string", "nullable": true, "description": "Option value, for example M." } } } }, "dimensions": { "type": "object", "additionalProperties": false, "description": "Package dimensions in centimetres.", "properties": { "length": { "type": "number", "description": "Package length in centimetres." }, "width": { "type": "number", "description": "Package width in centimetres." }, "height": { "type": "number", "description": "Package height in centimetres." } } }, "weight": { "type": "number", "description": "Weight in grams" }, "images": { "type": "array", "description": "Variant image URLs, in display order.", "items": { "type": "string", "description": "Publicly reachable https image URL." } } }, "required": [ "variant_id" ] }, "Product": { "type": "object", "additionalProperties": false, "description": "Partner-safe product view. Supplier-internal fields are stripped at the API boundary.", "properties": { "product_id": { "type": "string", "description": "Product ID associated with this value." }, "short_id": { "type": "string", "description": "Human-friendly alternate product identifier" }, "name": { "type": "string", "description": "Partner-visible name." }, "description": { "type": "string", "description": "Human-readable description." }, "status": { "type": "string", "enum": [ "live", "unlisted", "delisted", "proposed", "under_review", "archived" ], "description": "Current product status. This is the complete set — settable by the partner via POST /open/v1/products/{id}/status: live, unlisted, delisted; read-only, set by the platform: proposed, under_review, archived (proposed after create, under_review while in review, archived after delete). Every value here is also accepted by GET /open/v1/products?status=." }, "sku": { "type": "string", "description": "SKU of the primary variant" }, "price": { "type": "integer", "description": "Integer amount in PHP centavos." }, "stock": { "type": "integer", "description": "Stock of the primary variant" }, "category": { "type": "string", "description": "Product category." }, "thumbnail": { "type": "string", "description": "Product thumbnail image URL." }, "images": { "type": "array", "description": "Product image URLs, in display order.", "items": { "type": "string", "description": "Publicly reachable https image URL." } }, "weight": { "type": "number", "description": "Weight in grams" }, "dimensions": { "type": "object", "additionalProperties": false, "description": "Package dimensions in centimetres.", "properties": { "length": { "type": "number", "description": "Package length in centimetres." }, "width": { "type": "number", "description": "Package width in centimetres." }, "height": { "type": "number", "description": "Package height in centimetres." } } }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/ProductVariant" }, "description": "Product variants." }, "options_order": { "type": "array", "description": "Variant option groups in display order, each with its values in order — the order a storefront renders the variant picker in. Derived at create time from the order the options were submitted in; absent on products with no option groups.", "items": { "type": "object", "additionalProperties": false, "properties": { "title": { "type": "string", "description": "Option group name, e.g. `Colour`." }, "values": { "type": "array", "description": "The group's values, in display order.", "items": { "type": "string" } } }, "required": [ "title", "values" ] } }, "created_at": { "type": "string", "format": "date-time", "description": "Created at as an ISO-8601 timestamp." }, "updated_at": { "type": "string", "format": "date-time", "description": "Updated at as an ISO-8601 timestamp." } }, "required": [ "product_id", "name", "status" ] }, "ProductResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether the request completed successfully." }, "data": { "$ref": "#/components/schemas/Product", "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] }, "ProductListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether the request completed successfully." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" }, "description": "Response or event payload for this schema." }, "meta": { "$ref": "#/components/schemas/PaginationMeta", "description": "Response metadata, including pagination when the endpoint returns a list." } }, "required": [ "success", "data" ] }, "ProductVariantListResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether the request completed successfully." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductVariant" }, "description": "Response or event payload for this schema." } }, "required": [ "success", "data" ] } } } }