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_<waybill>).
        estimated_pickup_time:
          type: string
          nullable: true
          description: Pickup-only. Requested pickup date echoed by the upstream.
        branch:
          type: object
          nullable: true
          description: Dropoff-only. Selected branch 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: <shown once - store it now>
          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: <shown once - store it now>
          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