> ## Documentation Index
> Fetch the complete documentation index at: https://www.zinc.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create MPP Order

> Place an order via the Machine Payments Protocol (MPP)

Place an order using the [Machine Payments Protocol (MPP)](https://mpp.dev) — no Zinc account required. Payment is made upfront via MPP, supporting multiple payment methods including Tempo stablecoins and Stripe.

## How It Works

1. **Send Order Request** - Submit an order to `/agent/orders` with product and shipping details
2. **Payment Challenge** - If no valid payment credential is provided, the API returns HTTP `402` with payment challenges for all configured methods
3. **Submit Payment** - Include a valid MPP payment credential in the `Authorization` header
4. **Order Processing** - Once payment is confirmed, the order is queued for processing

<Info>
  This endpoint uses the same `OrderCreate` request body as the standard [Create Order](/v2/api-reference/orders/create-order) endpoint. The only difference is how authentication and payment are handled.
</Info>

## Payment is the gate

Payment — not request validation — is the gate on this endpoint. The body is parsed leniently so that an unpaid request reaches the `402` payment challenge instead of being rejected first by schema validation. This means an automated MPP discovery probe can send **no body, an empty body, or a partial body** and still receive the `402` challenge describing how to pay.

The body is only validated strictly once a valid payment credential is present. After paying, send a complete, valid `OrderCreate` body — an incomplete one will then be rejected with a `422`.

## Payment Methods

MPP supports multiple payment methods via the HTTP 402 challenge-credential flow:

* **Stripe** - Cards and wallets
* **Tempo** - Stablecoins

When a request is made without a valid credential, the response includes `WWW-Authenticate` headers describing the available payment challenges. Your MPP client uses these to complete payment and resubmit the request.

## 402 Payment Required

If no valid payment credential is provided, the API returns `402 Payment Required` with `WWW-Authenticate` headers describing the available payment methods.

### Response Headers

<ResponseField name="WWW-Authenticate" type="string">
  One header per supported payment method with challenge parameters (per RFC 9110 §11.6.1). Your MPP client uses these to complete payment and resubmit the request.
</ResponseField>

<Tip>
  See the [MPP guide](/v2/mpp) for a full walkthrough of integrating MPP with Zinc.
</Tip>


## OpenAPI

````yaml versions/latest.json POST /agent/orders
openapi: 3.1.0
info:
  title: Zinc
  summary: >-
    Zinc lets you search, buy, and return items from top online retailers with a
    single API.
  description: >-
    Search, buy, and return items from top online retailers with a single API.
    Supports AI agent ordering via MPP (HTTP 402) — no account required.
    Supported retailers include 1-800-Flowers, Ace Hardware, Amazon, Amazon DE,
    Best Buy, Lowe's, Partstown, Pokémon Center, Target, The Home Depot,
    Walmart, Wayfair, and 2 more. Ships to the US and 1 other country (DE).
  version: '2026-07-10'
  x-logo:
    url: https://mintlify.s3.us-west-1.amazonaws.com/zinc/logo/light.png
  contact:
    name: Zinc API Support
    email: support@zinc.com
    url: https://zinc.com/docs
  x-guidance: >-
    Zinc lets AI agents buy products from online retailers via a single API. Use
    POST /agent/orders to place an order — no Zinc account needed, payment is
    handled via MPP (HTTP 402 flow). Provide a product URL from a supported
    retailer, a shipping address, and max_price in cents. The API charges
    max_price + $1 API fee upfront and refunds the difference on completion. To
    find products first, the /agent/* data endpoints (search, products/search,
    products/offers, products/details) are MPP-paid at $0.01 per call;
    /agent/search returns orderable URLs to feed straight into /agent/orders.
    GET /retailers lists supported retailers for free (no payment or account).
    Authenticated equivalents (orders, products, managed-accounts) require a
    Bearer token (API key prefixed zn_). Docs: https://zinc.com/docs Supported
    retailers include 1-800-Flowers, Ace Hardware, Amazon, Amazon DE, Best Buy,
    Lowe's, Partstown, Pokémon Center, Target, The Home Depot, Walmart, Wayfair,
    and 2 more, shipping to the US and 1 other country (DE).
  x-supported-retailers:
    - 1-800-Flowers
    - Ace Hardware
    - Amazon
    - Amazon DE
    - Best Buy
    - Lowe's
    - Partstown
    - Pokémon Center
    - Target
    - The Home Depot
    - Walmart
    - Wayfair
    - Zinc
    - eBay
  x-supported-countries:
    - US
    - DE
servers:
  - url: https://api.zinc.com
    description: Production
security:
  - BearerAuth: []
paths:
  /agent/orders:
    post:
      tags:
        - agent
      summary: Create Mpp Order
      description: >-
        Place an order via the Machine Payments Protocol (MPP).


        No Zinc account required. Payment is made upfront via MPP.

        Supports multiple payment methods (e.g. Tempo, Stripe).

        If no valid payment credential is provided, returns HTTP 402

        with payment challenges for all configured methods.


        Payment is the gate, but only for a genuine discovery probe: a bodyless

        POST (from a registry like mppscan) is parsed leniently and reaches the
        402

        challenge instead of a 422. A *present-but-invalid* body, by contrast —

        including malformed JSON and non-object JSON — is a real order attempt

        and is rejected with a 422 up front, before any payment

        challenge is issued or honored. Otherwise an agent could settle an
        on-chain

        payment against the challenge and then be rejected on the retry, with no
        way

        to refund the settlement (the MPP layer cannot verify or reverse a
        payment

        whose retry body no longer matches the challenge).
      operationId: create_mpp_order_agent_orders_post
      parameters:
        - name: method
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Restrict the 402 to a single payment method (e.g. 'stripe',
              'tempo', or 'x402'). Omit to advertise every configured method.
              Use this when your client can satisfy only one rail — it avoids
              returning multiple WWW-Authenticate challenges, which many HTTP
              clients mishandle.
            title: Method
          description: >-
            Restrict the 402 to a single payment method (e.g. 'stripe', 'tempo',
            or 'x402'). Omit to advertise every configured method. Use this when
            your client can satisfy only one rail — it avoids returning multiple
            WWW-Authenticate challenges, which many HTTP clients mishandle.
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
          headers:
            X-Api-Key:
              description: >-
                API key for the MPP agent to check order status via GET
                /orders/{id}
              schema:
                type: string
            Payment-Receipt:
              description: MPP payment receipt confirming the charge
              schema:
                type: string
        '402':
          description: >-
            Payment required — returns challenge details for each configured
            payment method
          headers:
            WWW-Authenticate:
              description: >-
                One header per supported payment method with challenge
                parameters (per RFC 9110 §11.6.1)
              schema:
                type: string
        '422':
          description: >-
            Invalid order body — rejected before any payment challenge is issued
            or honored, so a payment can never be taken for an order that would
            be rejected. Send a valid OrderCreate body, or no body at all to
            receive a discovery 402.
      security: []
components:
  schemas:
    OrderCreate:
      properties:
        products:
          items:
            $ref: '#/components/schemas/OrderProduct'
          type: array
          title: Products
        shipping_address:
          $ref: '#/components/schemas/Address'
        max_price:
          type: integer
          title: Max Price
          description: >-
            Maximum price (in cents) allowed for an order before it is
            finalized.
        idempotency_key:
          anyOf:
            - type: string
              maxLength: 36
            - type: 'null'
          title: Idempotency Key
          description: >-
            Optional idempotency key to prevent duplicate orders. If not
            provided, one will be generated.
        retailer_credentials_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Retailer Credentials Id
          description: >-
            Optional short ID (e.g., 'zn_acct_XXXXXXXX') of specific retailer
            credentials to use for this order. If not provided, credentials will
            be selected automatically.
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: >-
            Optional metadata to attach to the order. Can contain arbitrary
            key-value pairs.
        po_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Po Number
          description: Optional purchase order number for the order.
        handling_days_max:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Handling Days Max
          description: >-
            Optional ceiling on a seller's shipping and handling days. Omit or
            send null for no limit.
        is_gift:
          type: boolean
          title: Is Gift
          description: >-
            Mark the order as a gift. Prices are suppressed on the packing slip
            where the fulfillment method supports it.
          default: false
        payment:
          anyOf:
            - $ref: '#/components/schemas/OrderPayment'
            - type: 'null'
          description: Optional payment block. Omit for prepaid-wallet billing (default).
      type: object
      required:
        - products
        - shipping_address
        - max_price
      title: OrderCreate
      description: Request model for creating a new order.
    OrderResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        status:
          $ref: '#/components/schemas/OrderStatus'
        max_price:
          type: integer
          title: Max Price
        attempts:
          type: integer
          title: Attempts
        items:
          items:
            $ref: '#/components/schemas/OrderItemResponse'
          type: array
          title: Items
        shipping_address:
          additionalProperties: true
          type: object
          title: Shipping Address
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          default: {}
        po_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Po Number
        handling_days_max:
          anyOf:
            - type: integer
            - type: 'null'
          title: Handling Days Max
        is_gift:
          type: boolean
          title: Is Gift
          default: false
        retailer_credentials_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Retailer Credentials Id
        retailer_credentials_uuid:
          anyOf:
            - type: string
            - type: 'null'
          title: Retailer Credentials Uuid
        job_result:
          anyOf:
            - $ref: '#/components/schemas/OrderJobResult'
            - type: 'null'
          description: >-
            Fulfillment result and price breakdown for a completed or failed
            order; null while processing.
        tracking_numbers:
          items:
            $ref: '#/components/schemas/TrackingNumberResponse'
          type: array
          title: Tracking Numbers
          default: []
        created_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Created By
        user_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: User Id
        returns:
          items:
            $ref: '#/components/schemas/ReturnRequestSummary'
          type: array
          title: Returns
          default: []
        connect:
          anyOf:
            - $ref: '#/components/schemas/OrderConnectInfo'
            - type: 'null'
          description: >-
            Stripe Connect charge details when this order was paid via Connect;
            null for prepaid-wallet orders.
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - status
        - max_price
        - attempts
        - items
        - shipping_address
        - retailer_credentials_id
        - created_at
        - updated_at
      title: OrderResponse
      description: Response model for order data.
    OrderProduct:
      properties:
        url:
          type: string
          title: Url
          examples:
            - https://www.amazon.com/dp/B07JGBW826
        quantity:
          type: integer
          maximum: 100
          minimum: 1
          title: Quantity
          default: 1
        variant:
          anyOf:
            - items:
                $ref: '#/components/schemas/ProductVariant'
              type: array
            - type: 'null'
          title: Variant
          description: Product variants to select (e.g., color, size)
        condition_in:
          anyOf:
            - items:
                $ref: '#/components/schemas/ProductCondition'
              type: array
            - type: 'null'
          title: Condition In
          description: >-
            Condition allowlist. The agent only buys an offer whose condition is
            in this list. Each value must be a canonical condition. Omit or send
            null/[] for no constraint.
        condition_not_in:
          anyOf:
            - items:
                $ref: '#/components/schemas/ProductCondition'
              type: array
            - type: 'null'
          title: Condition Not In
          description: >-
            Condition denylist. The agent will not buy an offer whose condition
            is in this list. Each value must be a canonical condition. Omit or
            send null/[] for no constraint.
      type: object
      required:
        - url
      title: OrderProduct
      description: |-
        Product item for an order.

        For example:
        ````{
            url: "https://www.amazon.com/dp/B07JGBW826",
            quantity: 1
        }```
    Address:
      properties:
        first_name:
          type: string
          title: First Name
        last_name:
          type: string
          title: Last Name
        address_line1:
          type: string
          title: Address Line1
        address_line2:
          anyOf:
            - type: string
            - type: 'null'
          title: Address Line2
        city:
          type: string
          title: City
        state:
          anyOf:
            - type: string
            - type: 'null'
          title: State
        postal_code:
          type: string
          title: Postal Code
        phone_number:
          type: string
          title: Phone Number
        country:
          type: string
          title: Country
          default: US
      type: object
      required:
        - first_name
        - last_name
        - address_line1
        - city
        - postal_code
        - phone_number
      title: Address
      description: >-
        Shipping address model.


        Supports international addresses. The `state` field is optional for
        countries

        that don't use states/provinces. The `country` field uses ISO 3166-1
        alpha-2

        country codes (e.g., "US", "CA", "GB", "DE").
    OrderPayment:
      properties:
        mode:
          type: string
          enum:
            - wallet
            - connect
          title: Mode
          default: wallet
        payment_method:
          anyOf:
            - type: string
            - type: 'null'
          title: Payment Method
          description: >-
            Connect mode: the end-customer's vaulted Stripe payment-method id on
            the customer's connected account.
        customer:
          anyOf:
            - type: string
            - type: 'null'
          title: Customer
          description: >-
            Connect mode: the end-customer's Stripe Customer id (cus_…) on the
            connected account. Required to charge a *reusable* saved card
            off-session; omit only for a one-time, unattached payment method.
        margin:
          anyOf:
            - $ref: '#/components/schemas/MarginSpec'
            - type: 'null'
          description: 'Connect mode: the customer''s margin on the order.'
      type: object
      title: OrderPayment
      description: >-
        Optional payment block. Absent or mode='wallet' ⇒ unchanged
        prepaid-wallet

        behavior. mode='connect' charges the end-customer's vaulted card in real
        time

        via Stripe Connect (see ConnectService).
    OrderStatus:
      type: string
      enum:
        - pending
        - in_progress
        - order_placed
        - order_failed
        - cancelled
        - cancelled_by_retailer
      title: OrderStatus
    OrderItemResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        url:
          type: string
          title: Url
        quantity:
          type: integer
          title: Quantity
        variant:
          anyOf:
            - items:
                $ref: '#/components/schemas/ProductVariant'
              type: array
            - type: 'null'
          title: Variant
        condition_in:
          anyOf:
            - items:
                $ref: '#/components/schemas/ProductCondition'
              type: array
            - type: 'null'
          title: Condition In
        condition_not_in:
          anyOf:
            - items:
                $ref: '#/components/schemas/ProductCondition'
              type: array
            - type: 'null'
          title: Condition Not In
        status:
          $ref: '#/components/schemas/OrderItemStatus'
        cancellation_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Cancellation Reason
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - url
        - quantity
        - status
        - created_at
        - updated_at
      title: OrderItemResponse
      description: >-
        Response model for order item data.


        Field names mirror the OrderItem model, so callers build it with

        ``OrderItemResponse.model_validate(item)`` rather than enumerating
        fields.
    OrderJobResult:
      properties:
        success:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Success
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        error_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Type
        error_details:
          anyOf:
            - $ref: '#/components/schemas/ErrorDetails'
            - type: 'null'
        price_components:
          anyOf:
            - $ref: '#/components/schemas/OrderPriceComponents'
            - type: 'null'
        estimated_delivery:
          anyOf:
            - type: string
            - type: 'null'
          title: Estimated Delivery
        merchant_order_ids:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Merchant Order Ids
      additionalProperties: true
      type: object
      title: OrderJobResult
      description: >-
        Fulfillment result surfaced on a completed or failed order. Null while
        the

        order is still processing.


        Lenient and open (``extra="allow"``) so it documents the common fields —

        success, price breakdown, errors, merchant order ids, delivery estimate
        —

        without constraining the full processing payload, which carries
        additional

        internal detail.
    TrackingNumberResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        carrier:
          type: string
          title: Carrier
        tracking_number:
          type: string
          title: Tracking Number
        zinc_tracking_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Zinc Tracking Number
          description: >-
            Zinc-issued tracking number under pseudo-carrier ZNLOGIC (format
            ZPY…YQ). Carrier-independent alias for this shipment; assigned once
            and never changes, even if the carrier tracking is corrected.
        zinc_tracking_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Zinc Tracking Url
          description: Public tracking URL for the Zinc tracking number (17track.net).
        status:
          anyOf:
            - $ref: '#/components/schemas/TrackingStatus'
            - type: 'null'
          description: Carrier-derived shipment state (pending, in_transit, delivered).
        estimated_delivery_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Estimated Delivery Date
          description: >-
            Carrier-reported delivery estimate for this shipment, as a
            destination-local calendar date. Refreshed on every carrier poll;
            null when the carrier hasn't reported one.
        checkpoints:
          items:
            $ref: '#/components/schemas/TrackingCheckpointResponse'
          type: array
          title: Checkpoints
          description: >-
            Carrier scan events, most recent first. Empty unless the checkpoint
            timeline was requested.
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - id
        - carrier
        - tracking_number
        - created_at
      title: TrackingNumberResponse
      description: >-
        Response model for tracking number data.


        ``status`` is the authoritative carrier-derived shipment state and is
        always

        present. ``checkpoints`` is the per-scan timeline; it's embedded on the

        single-order read (``GET /orders/{id}``) and, on the list endpoint, only

        when ``include=tracking_events`` is requested.
    ReturnRequestSummary:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        status:
          $ref: '#/components/schemas/ReturnRequestStatus'
        reason:
          $ref: '#/components/schemas/ReturnRequestReason'
        notes:
          anyOf:
            - type: string
            - type: 'null'
          title: Notes
        resolution_notes:
          anyOf:
            - type: string
            - type: 'null'
          title: Resolution Notes
        items:
          items:
            $ref: '#/components/schemas/ReturnRequestItem'
          type: array
          title: Items
          default: []
        label_urls:
          items:
            type: string
          type: array
          title: Label Urls
          default: []
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - status
        - reason
        - created_at
        - updated_at
      title: ReturnRequestSummary
    OrderConnectInfo:
      properties:
        state:
          type: string
          title: State
          description: secured | captured | released | refunded | …
        secured_amount:
          anyOf:
            - type: integer
            - type: 'null'
          title: Secured Amount
        order_cost:
          anyOf:
            - type: integer
            - type: 'null'
          title: Order Cost
          description: Actual order cost (goods) captured when the order is placed.
        customer_margin:
          anyOf:
            - type: integer
            - type: 'null'
          title: Customer Margin
        zinc_fee:
          anyOf:
            - type: integer
            - type: 'null'
          title: Zinc Fee
        stripe_fee:
          anyOf:
            - type: integer
            - type: 'null'
          title: Stripe Fee
        final_charge:
          anyOf:
            - type: integer
            - type: 'null'
          title: Final Charge
        transfer_amount:
          anyOf:
            - type: integer
            - type: 'null'
          title: Transfer Amount
        payment_intent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Payment Intent Id
        connected_account_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Connected Account Id
        simulated:
          type: boolean
          title: Simulated
          default: false
      type: object
      required:
        - state
      title: OrderConnectInfo
      description: >-
        Stripe Connect charge + state for an order paid via Connect. Present
        only

        when the order has a Connect profile; ``null`` for prepaid-wallet
        orders. All

        amounts in cents.


        ``state`` moves ``secured`` → ``captured`` (or ``released``/``refunded``
        on a

        terminal outcome). The post-capture fields (``order_cost`` and below)
        are

        populated once Zinc places the order with the retailer and the actual
        total

        is captured.
    ProductVariant:
      properties:
        label:
          type: string
          minLength: 1
          title: Label
          description: Variant label (e.g., 'Color', 'Size')
        value:
          type: string
          minLength: 1
          title: Value
          description: Variant value (e.g., 'Black', 'Large')
      type: object
      required:
        - label
        - value
      title: ProductVariant
      description: >-
        Product variant schema for selecting product options (color, size,
        etc.).
    ProductCondition:
      type: string
      enum:
        - New
        - Refurbished
        - UsedLikeNew
        - UsedVeryGood
        - UsedGood
        - UsedAcceptable
      title: ProductCondition
      description: >-
        Canonical product-condition strings for condition filtering.


        Matching against ``condition_in`` / ``condition_not_in`` is exact and

        case-sensitive against these *values*. The vocabulary matches the Zinc
        v1

        API's ``seller_selection_criteria`` condition strings. The Sonic
        worker's

        CANONICAL_CONDITIONS (``src/agent/schemas.py``) must use the same
        strings,

        since they ride through the job payload unchanged.


        The member *name* is the corresponding Amazon BizAPI offer condition
        code

        (see ``CONDITION_MAP`` in ``bizapi_service``), so the canonical→BizAPI

        mapping is derived from the enum rather than maintained as a separate
        table.
    MarginSpec:
      properties:
        type:
          type: string
          enum:
            - flat
            - percent
          title: Type
        value:
          type: number
          minimum: 0
          title: Value
          description: >-
            Cents when type='flat'; a percentage when type='percent' (e.g. 15 ==
            15%).
      type: object
      required:
        - type
        - value
      title: MarginSpec
      description: Customer's markup on the order cost (computed before fees).
    OrderItemStatus:
      type: string
      enum:
        - pending
        - processing
        - ordered
        - shipped
        - delivered
        - cancelled
        - failed
      title: OrderItemStatus
    ErrorDetails:
      properties:
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
        address_validation_reasons:
          items:
            type: string
          type: array
          title: Address Validation Reasons
          default: []
        field_errors:
          items:
            $ref: '#/components/schemas/FieldError'
          type: array
          title: Field Errors
          default: []
      additionalProperties: true
      type: object
      required:
        - code
        - message
      title: ErrorDetails
      description: |-
        Structured detail for a failed job.

        Additive sibling to the flat `error`/`error_type` keys (kept for
        back-compat). The structured home for enrichment beyond the category +
        message — e.g. why a shipping address was rejected — so we don't keep
        growing loose top-level keys on the job output.
    OrderPriceComponents:
      properties:
        subtotal:
          anyOf:
            - type: integer
            - type: 'null'
          title: Subtotal
        tax:
          anyOf:
            - type: integer
            - type: 'null'
          title: Tax
        shipping:
          anyOf:
            - type: integer
            - type: 'null'
          title: Shipping
        total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total
          description: Order total in `currency` (subtotal + tax + shipping).
        converted_payment_total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Converted Payment Total
          description: '`total` converted to the currency actually charged.'
        currency:
          anyOf:
            - type: string
            - type: 'null'
          title: Currency
        payment_currency:
          anyOf:
            - type: string
            - type: 'null'
          title: Payment Currency
        line_items:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Line Items
          description: Itemized rows, each `{description, amount, category}`.
      additionalProperties: true
      type: object
      title: OrderPriceComponents
      description: >-
        Retailer price breakdown for an order, all amounts in cents.


        Lenient by design — every field is optional and unknown keys are
        preserved

        (``extra="allow"``) — because it mirrors fulfillment output that may be

        partial (e.g. a failed order) or carry extra detail. Documents the
        common

        fields without revalidating the raw payload.
    TrackingStatus:
      type: string
      enum:
        - pending
        - in_transit
        - delivered
      title: TrackingStatus
      description: Carrier-derived shipment state for a TrackingNumber.
    TrackingCheckpointResponse:
      properties:
        checkpoint_time:
          type: string
          format: date-time
          title: Checkpoint Time
          description: When the carrier recorded this scan event.
        status:
          $ref: '#/components/schemas/TrackingStatus'
          description: Carrier-derived shipment state at this checkpoint.
        message:
          type: string
          title: Message
          description: Carrier-provided description of the scan.
        city:
          anyOf:
            - type: string
            - type: 'null'
          title: City
        state:
          anyOf:
            - type: string
            - type: 'null'
          title: State
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
        zip:
          anyOf:
            - type: string
            - type: 'null'
          title: Zip
        location:
          anyOf:
            - type: string
            - type: 'null'
          title: Location
          description: Free-form location string when city/state are absent.
      type: object
      required:
        - checkpoint_time
        - status
        - message
      title: TrackingCheckpointResponse
      description: A single carrier-reported scan event for a tracking number.
    ReturnRequestStatus:
      type: string
      enum:
        - open
        - approved
        - denied
        - credited
      title: ReturnRequestStatus
    ReturnRequestReason:
      type: string
      enum:
        - damaged
        - not_delivered
        - empty_box
        - wrong_item
        - defective
        - not_as_described
        - wrong_size
        - no_longer_needed
        - forced_cancellation
        - other
      title: ReturnRequestReason
      description: Universal return reason codes (Shopify + Amazon prepaid alignment).
    ReturnRequestItem:
      properties:
        order_item_id:
          type: string
          format: uuid
          title: Order Item Id
        quantity:
          type: integer
          maximum: 100
          minimum: 1
          title: Quantity
      type: object
      required:
        - order_item_id
        - quantity
      title: ReturnRequestItem
      description: A single product line on a return — which order item, how many.
    FieldError:
      properties:
        field:
          type: string
          title: Field
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
          default: ''
        received:
          title: Received
        expected:
          anyOf:
            - type: string
            - type: 'null'
          title: Expected
      additionalProperties: true
      type: object
      required:
        - field
        - code
      title: FieldError
      description: >-
        A single field-level validation failure from a worker.


        Mirrors Sonic's `FieldError` (src/agent/types.py): when a job fails
        schema

        validation the worker reports one of these per offending field, so
        consumers

        can show "state should be 'NY', got 'New York'" instead of a bare count.
  securitySchemes:
    BearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Zinc API key (Bearer zn_...)

````