> ## 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 Agent Order

> Place an order and pay for it in the same request with Link, MPP, or x402. No Zinc account required.

Place an order and pay for it per request over HTTP `402 Payment Required`. You don't need a Zinc account or API key. The agent pays `max_price` + the \$1.00 API fee upfront, and anything the order doesn't use is refunded to the original payment.

| Rail | Pays with | Proof header on the retry |
| - | - | - |
| **Link** | A card from the user's Link wallet, as a Shared Payment Token (MPP `method="stripe"`) | `Authorization: Payment <credential>` |
| **Tempo** | USDC on Tempo (MPP `method="tempo"`) | `Authorization: Payment <credential>` |
| **x402** | USDC on Base or Solana | `PAYMENT-SIGNATURE` (v2) or `X-PAYMENT` (v1) |

## How It Works

1. **Send the order** — `POST /agent/orders` with a complete order body and no payment.
2. **Get the challenge** — Zinc checks the body and returns `402` with a challenge for every rail: one `WWW-Authenticate` header per MPP method, plus a `PAYMENT-REQUIRED` header for x402.
3. **Pay and resubmit** — pay on one rail and send the identical request again with the proof header.
4. **Order placed** — Zinc verifies the payment and returns `201` with the order and an `X-Api-Key` header.

> [!NOTE]
>
> This endpoint takes the same `OrderCreate` body as the standard [Create Order](https://www.zinc.com/docs/v2/api-reference/orders/create-order.md) endpoint. Only authentication and payment differ. The same limits apply, including **at most 10 products per order**, and they're checked before the agent is charged.

## Validation before payment

An agent is never charged for an order Zinc would reject:

* **No body, `{}`, or `null`** — treated as a discovery probe (for example from a service registry) and answered with a `402` at a placeholder amount.
* **A malformed or incomplete body** (including invalid JSON) — `422` straight away. No challenge is issued.
* **An order Zinc can't fulfill** (unsupported retailer, unreachable product URL, unsupported shipping country, invalid address) — checked on the paid retry, **before** the proof is charged, and rejected with `400`. The payment is left untouched, so you can fix the order and retry with it.

Send the complete body on the first request. The challenge amount comes from its `max_price`.

## Choosing a rail

By default the `402` lists every rail. Add `?method=stripe`, `?method=tempo`, or `?method=x402` to get only that challenge. This helps clients that can't pick one `WWW-Authenticate` header out of several. An unknown method returns `400` with the available ones in `error.details.available`.

## Test mode

Send `X-Test-Mode: true` to run the same flow without real funds. The `402` offers testnet rails only (Tempo testnet, Base Sepolia, Solana devnet), and the order is created in the [sandbox](https://www.zinc.com/docs/v2/api-reference/introduction/sandbox.md), where it's simulated like any `zn_test_` order and never reaches a retailer. The `X-Api-Key` returned is a `zn_test_` key.

> [!WARNING]
>
> Testnet payments are not refunded, including unused `max_price` budget.

## Responses

### 402 Payment Required

**WWW-Authenticate** `string`

One header per MPP method (`stripe`, `tempo`), per RFC 9110 §11.6.1. Your MPP client or `link-cli` uses it to pay and resubmit.

**PAYMENT-REQUIRED** `string`

Base64 x402 v2 `PaymentRequired` envelope, with one `accepts[]` entry per supported chain.

### 201 Created

**X-Api-Key** `string`

API key for the paying agent. Use it to read the order (`GET /orders/{id}`), cancel it while pending, and register a webhook URL (`PUT /webhooks/endpoint`). Store it. It's the only way to follow the order without paying again.

**Payment-Receipt** `string`

MPP receipt for the charge (Link and Tempo).

**PAYMENT-RESPONSE** `string`

x402 settlement response (x402 only).

### 409 Conflict

Returned when this payer already placed an order with the same `idempotency_key`. The check runs after the payment proof is verified but **before** it's settled, so retrying a request that timed out never charges twice. The existing order's id is in `error.details.order_id`, and the response carries an `X-Api-Key` header to read it.

> [!TIP]
>
> See [Agentic Purchases](https://www.zinc.com/docs/v2/agentic-purchases.md) for a full walkthrough of paying with Link, MPP, or x402, including the one-command `link-cli mpp pay` flow.


## 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, AliExpress, Amazon,
    Amazon AU, Amazon CA, Amazon DE, Amazon ES, Amazon FR, Amazon IT, Amazon MX,
    Amazon UK, and 23 more. Ships to the US and 7 other countries (CA, DE, ES,
    FR, GB, IT, MX). The listed retailers are the ones Zinc verifies with daily
    test orders, not the limit of what Zinc can buy from: checkout is attempted
    at most online stores, including Shopify-hosted ones. To ask about a
    specific store before ordering, call GET /retailers/check?url=... — it
    answers whether Zinc will attempt that URL.
  version: '2026-10-30'
  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_); those orders are paid from a prefunded
    wallet — GET /wallet/me returns the spendable balance and per-order fee, so
    check it before POST /orders to avoid a 402. Orders are strict by default:
    if the gift option can't be applied or any item can't be bought, the whole
    order fails. When the user wants whatever can be shipped, send fulfillment:
    {"gift": "best_effort", "items": "best_effort"} and read
    fulfillment.concessions on the order to see what was relaxed. max_price is
    never relaxed. Docs: https://zinc.com/docs Supported retailers include
    1-800-Flowers, Ace Hardware, AliExpress, Amazon, Amazon AU, Amazon CA,
    Amazon DE, Amazon ES, Amazon FR, Amazon IT, Amazon MX, Amazon UK, and 23
    more, shipping to the US and 7 other countries (CA, DE, ES, FR, GB, IT, MX).
    The listed retailers are the ones Zinc verifies with daily test orders, not
    the limit of what Zinc can buy from: checkout is attempted at most online
    stores, including Shopify-hosted ones. To ask about a specific store before
    ordering, call GET /retailers/check?url=... — it answers whether Zinc will
    attempt that URL.
  x-supported-retailers:
    - 1-800-Flowers
    - Ace Hardware
    - AliExpress
    - Amazon
    - Amazon AU
    - Amazon CA
    - Amazon DE
    - Amazon ES
    - Amazon FR
    - Amazon IT
    - Amazon MX
    - Amazon UK
    - Barnes & Noble
    - Best Buy
    - Chewy
    - Gap
    - Grainger
    - IBS
    - Lowe's
    - Macys
    - McMaster-Carr
    - Partstown
    - Pokémon Center
    - Sephora
    - Shein
    - Temu
    - The Home Depot
    - TikTok
    - Uniqlo
    - Walmart
    - Wayfair
    - Zinc
    - eBay
    - libraccio
    - zazzle
  x-supported-countries:
    - US
    - CA
    - DE
    - ES
    - FR
    - GB
    - IT
    - MX
servers:
  - url: https://api.zinc.com
    description: Production
security:
  - BearerAuth: []
paths:
  /agent/orders:
    post:
      tags:
        - agent
      summary: Buy a product from a major online retailer and ship it to a US address
      description: >-
        Place an order and pay for it in the same request — no Zinc account.


        The agent pays ``max_price`` + the API fee upfront over HTTP 402 on any

        configured rail: Link (a Stripe Shared Payment Token over MPP), MPP
        Tempo,

        or x402 (USDC on Base or Solana). Unused budget is refunded to the
        original

        payment. If no valid payment proof is provided, returns HTTP 402 with a

        challenge for every configured rail (``?method=`` narrows it to one).


        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).


        ``X-Test-Mode: true`` runs the same flow on testnets: every rail is
        swapped

        for a testnet-only twin, and the order is created in the sandbox, where
        it

        is simulated like any ``zn_test_`` order. Testnet payments are not
        refunded.
      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
        - name: x-test-mode
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Set to 'true' for test mode: the 402 offers testnet rails only
              (Tempo testnet, Base Sepolia, Solana devnet), and the order is
              simulated in the sandbox — no real funds, no retailer order. The
              X-Api-Key returned is a zn_test_ key.
            title: X-Test-Mode
          description: >-
            Set to 'true' for test mode: the 402 offers testnet rails only
            (Tempo testnet, Base Sepolia, Solana devnet), and the order is
            simulated in the sandbox — no real funds, no retailer order. The
            X-Api-Key returned is a zn_test_ key.
      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 paying agent. Reads the order via GET
                /orders/{id}, cancels it while pending, and registers a webhook
                URL via PUT /webhooks/endpoint.
              schema:
                type: string
            Payment-Receipt:
              description: MPP payment receipt confirming the charge (Link and Tempo)
              schema:
                type: string
            PAYMENT-RESPONSE:
              description: x402 settlement response (x402 only)
              schema:
                type: string
        '402':
          description: >-
            Payment required — returns challenge details for each configured
            payment method
          headers:
            WWW-Authenticate:
              description: >-
                One header per MPP method (`stripe` for Link SPTs, `tempo`), per
                RFC 9110 §11.6.1
              schema:
                type: string
            PAYMENT-REQUIRED:
              description: >-
                x402 v2 PaymentRequired envelope (base64), one `accepts[]` entry
                per supported chain
              schema:
                type: string
        '409':
          description: >-
            Duplicate `idempotency_key` — this payer already placed an order
            under that key. Checked after the payment proof is verified but
            BEFORE it is settled, so a client that lost the original 201 to a
            timeout can retry with the same key (and a fresh signed payment)
            without being charged twice. The existing order's id is in
            `error.details.order_id`; fetch it with the X-Api-Key header on this
            response via GET /orders/{id}. Same error shape as POST /orders.
          headers:
            X-Api-Key:
              description: API key for the payer's account, to look up the existing order
              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:
      description: Request model for creating a new order.
      properties:
        products:
          items:
            $ref: '#/components/schemas/OrderProduct'
          type: array
          minItems: 1
          title: Products
        shipping_address:
          $ref: '#/components/schemas/Address'
        max_price:
          type: integer
          minimum: 0
          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 one of your own saved
            retailer accounts to place this order on. The item is then paid for
            by the payment method saved on that account, and your wallet is
            charged the API fee only — so the balance needed to place the order
            is the fee, not max_price + fee. Omit it and the order is placed on
            a Zinc account and funded from your wallet; Zinc never substitutes
            one of your saved accounts, so send this field on every order that
            has to run on yours.
        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, suppressing prices on the packing slip. If
            the retailer's checkout offers no free gift option, the order FAILS
            with `gift_option_unavailable` rather than being placed as a normal
            order — a gift that arrives with prices visible to the recipient is
            treated as worse than no order.
          default: false
        gift_message:
          anyOf:
            - type: string
              maxLength: 240
            - type: 'null'
          title: Gift Message
          description: >-
            Optional note for the recipient, entered into the retailer's
            gift-message field at checkout. Requires `is_gift` to be true. Max
            240 characters. Delivered where the retailer's checkout offers a
            gift message; the order is still placed without it where one isn't
            available.
        payment:
          anyOf:
            - $ref: '#/components/schemas/OrderPayment'
            - type: 'null'
          description: Optional payment block. Omit for prepaid-wallet billing (default).
        customer_notifications:
          anyOf:
            - $ref: '#/components/schemas/CustomerNotifications'
            - type: 'null'
          description: >-
            Opt in to emailing the end customer order updates (and unlock the
            public tracking page for this order). Adds a per-order surcharge.
            Omit for no customer notifications (default).
        fulfillment:
          anyOf:
            - $ref: '#/components/schemas/FulfillmentPreferences'
            - type: 'null'
          description: >-
            Loosen the order's strict-by-default rules. Omit for today's
            behaviour: any rule that can't be met fails the order. Set a rule
            (`gift`, `items`, `quantity`) to `best_effort` to have the order
            placed anyway; anything left unset stays strict. Whatever was
            relaxed is reported back in `fulfillment.concessions` on the order.
            `max_price` is never relaxed. `excluded_merchants`,
            `included_merchants` and `first_party_only` tighten instead: which
            merchants this order may be bought from.
      required:
        - products
        - shipping_address
        - max_price
      title: OrderCreate
      type: object
    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
        gift_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Gift Message
        retailer_credentials_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Retailer Credentials Id
        retailer_credentials_uuid:
          anyOf:
            - type: string
            - type: 'null'
          title: Retailer Credentials Uuid
        buying_account:
          anyOf:
            - $ref: '#/components/schemas/OrderBuyingAccount'
            - type: 'null'
        job_result:
          anyOf:
            - $ref: '#/components/schemas/OrderJobResult'
            - type: 'null'
          description: >-
            Fulfillment result and price breakdown for a completed or failed
            order; null while processing.
        merchant_order_ids:
          items:
            type: string
          type: array
          title: Merchant Order Ids
          description: >-
            The retailer's own order number(s) for this order (e.g. an Amazon
            `113-…` ID), as recorded when it was placed. Empty while processing,
            or if the order never reached the retailer.
          default: []
        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: []
        cases:
          items:
            $ref: '#/components/schemas/CaseSummary'
          type: array
          title: Cases
          description: Support cases on this order, newest first. See `/cases`.
          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.
        payment:
          anyOf:
            - $ref: '#/components/schemas/OrderPaymentInfo'
            - type: 'null'
          description: >-
            Card hold details when this order was paid by card outside the
            wallet and Connect; null for wallet and Connect orders.
        customer_notifications:
          anyOf:
            - $ref: '#/components/schemas/CustomerNotificationStatus'
            - type: 'null'
          description: >-
            End-customer email-notification status when the order opted into the
            notifications add-on; null when it didn't.
        fulfillment:
          $ref: '#/components/schemas/OrderFulfillment'
          description: >-
            `gift`/`items`/`quantity`: the mode this order asked for on each
            rule (all null = strict). `concessions`: every rule that actually
            was relaxed, with the worker's code and the item it concerned. Empty
            concessions means the order was fulfilled exactly as requested.
        status_checked_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Status Checked At
          description: >-
            When Zinc last got an answer about this order's status or tracking
            from the retailer or a carrier (UTC). An answer of 'no tracking yet'
            counts; failed attempts do not. Null until the first successful
            check.
        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
          maxLength: 60
          title: Address Line1
          description: >-
            Street address. At most 60 characters — retailers reject a longer
            line outright rather than truncating it.
        address_line2:
          anyOf:
            - type: string
              maxLength: 60
            - type: 'null'
          title: Address Line2
          description: >-
            Apartment, suite, unit, etc. At most 60 characters — retailers
            reject a longer line outright rather than truncating it.
        city:
          type: string
          title: City
        state:
          anyOf:
            - type: string
            - type: 'null'
          title: State
        postal_code:
          type: string
          title: Postal Code
          description: >-
            Postal code. For a US address this must be a ZIP: 5 digits,
            optionally +4 (e.g. '98632' or '27517-8761').
        phone_number:
          type: string
          title: Phone Number
        country:
          type: string
          title: Country
          description: >-
            Country as an ISO 3166-1 alpha-2 code (e.g. 'US', 'CA', 'GB', 'DE').
            Case-insensitive. Longer spellings such as 'USA' or 'United States'
            are rejected — the error names the code to use.
          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"), which are required rather
        than

        inferred — a longer spelling like "USA" is rejected with the code to
        use, so

        everything downstream can rely on seeing alpha-2.
    OrderPayment:
      properties:
        mode:
          type: string
          enum:
            - wallet
            - card
            - connect
          title: Mode
          default: wallet
        payment_method:
          anyOf:
            - type: string
            - type: 'null'
          title: Payment Method
          description: >-
            Connect mode: the end-customer's vaulted payment-method id on the
            connected account. Required for connect mode.
        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' draws the order from the

        prepaid wallet. mode='connect' charges the end-customer's saved card
        through

        Stripe Connect and keeps your margin (see ConnectService).
    CustomerNotifications:
      properties:
        email:
          type: string
          format: email
          title: Email
          description: End-customer email address to send order updates to.
      type: object
      required:
        - email
      title: CustomerNotifications
      description: |-
        Opt-in to email the END customer as this order progresses.

        Providing this block opts the order into the notifications add-on: a
        per-order surcharge is applied and the public tracking page becomes
        reachable for the order. The feature is gated server-side by
        ``customer_emails_enabled``; while that's off the block has no effect.
    FulfillmentPreferences:
      properties:
        gift:
          anyOf:
            - $ref: '#/components/schemas/FulfillmentMode'
            - type: 'null'
          description: >-
            `best_effort`: if the retailer offers no free gift option, place a
            normal order instead of failing with `gift_option_unavailable`.
            Requires `is_gift: true`. Omit to keep the gift requirement strict.
        items:
          anyOf:
            - $ref: '#/components/schemas/FulfillmentMode'
            - type: 'null'
          description: >-
            `best_effort`: if an item can't be bought (not found, out of stock,
            variant or condition unavailable, add-to-cart failed), skip it and
            ship the rest — its status becomes `skipped`. An empty cart still
            fails. Omit for all-or-nothing.
        quantity:
          anyOf:
            - $ref: '#/components/schemas/FulfillmentMode'
            - type: 'null'
          description: >-
            `best_effort`: if the retailer caps an item below the requested
            quantity, buy the cap instead of failing with
            `quantity_limit_exceeded`. Omit to require the full quantity.
        excluded_merchants:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 20
            - type: 'null'
          title: Excluded Merchants
          description: >-
            Merchants this order must never be bought from: a display name as
            shown on the retailer's storefront (matched ignoring case and
            spacing) or an Amazon Business `amzn1.` merchant id (Amazon Business
            orders only; refused on other orders). At most 20 entries. Added to
            any blocklist already on your account; it can only bar more
            merchants, never allow a barred one. Applied to Amazon Business
            orders, Amazon orders placed with `retailer_credentials_id`, and
            Walmart orders; ignored elsewhere. When no allowed offer is left the
            item fails as `product_unavailable`; on orders placed with a
            retailer account or on Walmart, `error_details` names the barred
            sellers (`barred_sellers`) and why (`merchant_rule`).
        included_merchants:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 20
            - type: 'null'
          title: Included Merchants
          description: >-
            Only buy this order from these merchants: same entry format as
            `excluded_merchants`, at most 20 entries. Offers from any other
            merchant are skipped; if none of the listed merchants has a
            qualifying offer the item fails as unavailable. Exclusions still
            win: a merchant on both lists, or on your account's blocklist, is
            never used. Other offer rules (condition, delivery time, the price
            cap; on Amazon Business also Prime unless it's the Buy Box) still
            apply. Ignored when `first_party_only` is set. Applied to Amazon
            Business orders, Amazon orders placed with
            `retailer_credentials_id`, and Walmart orders; ignored elsewhere.
        first_party_only:
          anyOf:
            - type: boolean
            - type: 'null'
          title: First Party Only
          description: >-
            `true`: only buy offers sold by the retailer itself (Amazon on
            Amazon, Walmart.com on Walmart), skipping every third-party seller
            (including ones fulfilled by the retailer) and Amazon's
            cross-border, used/returns, pharmacy and gift-card stores. If the
            retailer doesn't sell the item the item fails as unavailable. Takes
            the place of every merchant list: `included_merchants`,
            `excluded_merchants` and any blocklist on your account are not
            applied to this order. Applied to Amazon Business orders, Amazon
            orders placed with `retailer_credentials_id`, and Walmart orders;
            ignored elsewhere.
      additionalProperties: false
      type: object
      title: FulfillmentPreferences
      description: >-
        Which strict order rules may be relaxed. The order contract is strict by

        default; this object only ever loosens it.


        One key per concern — ``gift``, ``items``, ``quantity`` — whose value is
        the

        mode to hold that rule at. Absent (or null) is today's behaviour, so an

        omitted block and ``{}`` mean the same strict order. There is
        deliberately

        no ``"strict"`` mode to write — the existing fields already mean that

        (``is_gift: true`` is a required gift; a products list is
        all-or-nothing),

        and a second spelling of the same intent is a second thing to get wrong.

        Unknown keys and unknown modes are rejected rather than ignored, so a
        typo

        can never silently mean "strict".


        Extension point: a softer mode for a concern is a new
        ``FulfillmentMode``

        member (``prefer``, ``nearest``); a per-concern knob is that concern's
        value

        widening from a bare mode into an object (``items: {mode: "best_effort",

        min_items: 2}``) — never a new top-level order field.


        The exceptions to "only loosens" are the merchant rules

        (``excluded_merchants``, ``included_merchants``, ``first_party_only``):
        a

        per-order seller blocklist, allowlist and "sold by the retailer itself"

        flag, here rather than top-level because they are rare and only some

        placement paths can honour them (BizAPI, and Sonic on Amazon and
        Walmart;

        ignored elsewhere). None is

        a ``FulfillmentConcern`` and none produces a concession.
    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
        error_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Type
        tracking_number_ids:
          anyOf:
            - items:
                type: string
                format: uuid
              type: array
            - type: 'null'
          title: Tracking Number Ids
          description: >-
            Ids of the `tracking_numbers[]` known to carry this item, best
            effort. Null when unknown (never an empty list). The reverse of
            `tracking_numbers[].order_item_ids`.
        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.
    OrderBuyingAccount:
      properties:
        short_id:
          type: string
          title: Short Id
        email:
          type: string
          title: Email
        is_global:
          type: boolean
          title: Is Global
        has_password:
          type: boolean
          title: Has Password
        has_totp:
          type: boolean
          title: Has Totp
      type: object
      required:
        - short_id
        - email
        - is_global
        - has_password
        - has_totp
      title: OrderBuyingAccount
      description: >-
        The retailer login an order was placed from. Admin-only.


        Covers global (Zinc-owned) credentials too, which the customer-facing

        ``retailer_credentials_id`` deliberately hides. The password and TOTP
        never

        ride on this payload: the dashboard fetches them on demand through the

        audit-logged ``POST /admin/accounts/{short_id}/reveal-credential``.
    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.
        delivery_proof_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Delivery Proof Url
          description: >-
            URL of the proof-of-delivery photo, when the retailer provided one.
            Only available on orders placed with a managed account; delivery
            photos can't be pulled from carriers (USPS, UPS, etc.) for privacy
            reasons, so the retailer must supply it. Typically appears once the
            shipment is delivered; null when none is available.
        checkpoints:
          items:
            $ref: '#/components/schemas/TrackingCheckpointResponse'
          type: array
          title: Checkpoints
          description: >-
            Carrier scan events, most recent first. Empty unless the checkpoint
            timeline was requested.
        order_item_ids:
          anyOf:
            - items:
                type: string
                format: uuid
              type: array
            - type: 'null'
          title: Order Item Ids
          description: >-
            Ids of the `items[]` this package carries, best effort. Null when
            unknown (never an empty list). Populated when the order has one
            item, or once a single-package order is delivered; see
            `item_mapping` for how much to trust it.
        item_mapping:
          anyOf:
            - type: string
              enum:
                - exact
                - inferred
            - type: 'null'
          title: Item Mapping
          description: >-
            Confidence of `order_item_ids`: `exact` means the package cannot
            carry anything else; `inferred` means at least one entry is a
            best-effort guess. Null when `order_item_ids` is null.
        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: []
        credited_amount:
          type: integer
          title: Credited Amount
          description: >-
            Total wallet credit issued for this return, in cents. 0 until a
            credit is issued (and on returns resolved without one). Credits are
            append-only, so this is the running total across every credit and
            reversal on the return, not the last one.
          default: 0
        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
    CaseSummary:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        order_id:
          type: string
          format: uuid
          title: Order Id
        return_request_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Return Request Id
        reason:
          $ref: '#/components/schemas/CaseReason'
        status:
          $ref: '#/components/schemas/CaseStatus'
          description: >-
            `open` — waiting on Zinc. `waiting_on_customer` — Zinc replied and
            is waiting on you. `on_hold` — waiting on the retailer or carrier.
            `closed` — resolved; replying reopens it within the case window.
        credited_amount:
          type: integer
          title: Credited Amount
          description: >-
            Total wallet credit issued from this case, in cents (net of
            reversals).
          default: 0
        opened_by_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Opened By Name
          description: >-
            Who opened the case: a teammate's name, or `Zinc support` when Zinc
            reached out. (The `case.created` webhook's `opened_by` is the side
            instead: `customer` or `zinc`.)
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        closed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Closed At
      type: object
      required:
        - id
        - order_id
        - reason
        - status
        - created_at
        - updated_at
      title: CaseSummary
    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.
    OrderPaymentInfo:
      properties:
        mode:
          type: string
          const: card
          title: Mode
          default: card
        state:
          type: string
          title: State
          description: authorized | captured | released | refunded | …
        authorized_cents:
          type: integer
          title: Authorized Cents
        fee_cents:
          type: integer
          title: Fee Cents
        stripe_fee_cents:
          anyOf:
            - type: integer
            - type: 'null'
          title: Stripe Fee Cents
          description: >-
            Card-processing fee grossed into the amount above, the same way a
            wallet top-up and a Connect charge gross it in.
        captured_cents:
          anyOf:
            - type: integer
            - type: 'null'
          title: Captured Cents
        payment_method:
          anyOf:
            - type: string
            - type: 'null'
          title: Payment Method
        payment_intent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Payment Intent Id
        simulated:
          type: boolean
          title: Simulated
          default: false
      type: object
      required:
        - state
        - authorized_cents
        - fee_cents
      title: OrderPaymentInfo
      description: >-
        Card hold details for an order paid by card outside the wallet and

        Connect, and where that hold stands. ``null`` for wallet and Connect
        orders

        (Connect has its own ``connect`` block). All amounts in cents.


        ``state`` moves ``authorized`` → ``captured`` when the retailer order is

        placed (``captured_cents`` = actual total + fee), or → ``released`` when
        the

        order fails or is cancelled first. The card is only ever charged

        ``captured_cents``; the difference to ``authorized_cents`` is released.
    CustomerNotificationStatus:
      properties:
        email:
          type: string
          title: Email
        delivered:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Delivered
      type: object
      required:
        - email
      title: CustomerNotificationStatus
      description: >-
        End-customer email-notification status for an order.


        Present only when the order opted into the notifications add-on.
        ``delivered``

        is the deliverability signal: True once a notification reached the
        shopper

        (an unsubscribe click also counts — it proves receipt), False if one was

        attempted but bounced/failed/suppressed, and null while nothing has been

        sent yet (e.g. not shipped) or a send is still in flight.
    OrderFulfillment:
      properties:
        gift:
          anyOf:
            - $ref: '#/components/schemas/FulfillmentMode'
            - type: 'null'
          description: >-
            `best_effort`: if the retailer offers no free gift option, place a
            normal order instead of failing with `gift_option_unavailable`.
            Requires `is_gift: true`. Omit to keep the gift requirement strict.
        items:
          anyOf:
            - $ref: '#/components/schemas/FulfillmentMode'
            - type: 'null'
          description: >-
            `best_effort`: if an item can't be bought (not found, out of stock,
            variant or condition unavailable, add-to-cart failed), skip it and
            ship the rest — its status becomes `skipped`. An empty cart still
            fails. Omit for all-or-nothing.
        quantity:
          anyOf:
            - $ref: '#/components/schemas/FulfillmentMode'
            - type: 'null'
          description: >-
            `best_effort`: if the retailer caps an item below the requested
            quantity, buy the cap instead of failing with
            `quantity_limit_exceeded`. Omit to require the full quantity.
        excluded_merchants:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 20
            - type: 'null'
          title: Excluded Merchants
          description: >-
            Merchants this order must never be bought from: a display name as
            shown on the retailer's storefront (matched ignoring case and
            spacing) or an Amazon Business `amzn1.` merchant id (Amazon Business
            orders only; refused on other orders). At most 20 entries. Added to
            any blocklist already on your account; it can only bar more
            merchants, never allow a barred one. Applied to Amazon Business
            orders, Amazon orders placed with `retailer_credentials_id`, and
            Walmart orders; ignored elsewhere. When no allowed offer is left the
            item fails as `product_unavailable`; on orders placed with a
            retailer account or on Walmart, `error_details` names the barred
            sellers (`barred_sellers`) and why (`merchant_rule`).
        included_merchants:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 20
            - type: 'null'
          title: Included Merchants
          description: >-
            Only buy this order from these merchants: same entry format as
            `excluded_merchants`, at most 20 entries. Offers from any other
            merchant are skipped; if none of the listed merchants has a
            qualifying offer the item fails as unavailable. Exclusions still
            win: a merchant on both lists, or on your account's blocklist, is
            never used. Other offer rules (condition, delivery time, the price
            cap; on Amazon Business also Prime unless it's the Buy Box) still
            apply. Ignored when `first_party_only` is set. Applied to Amazon
            Business orders, Amazon orders placed with
            `retailer_credentials_id`, and Walmart orders; ignored elsewhere.
        first_party_only:
          anyOf:
            - type: boolean
            - type: 'null'
          title: First Party Only
          description: >-
            `true`: only buy offers sold by the retailer itself (Amazon on
            Amazon, Walmart.com on Walmart), skipping every third-party seller
            (including ones fulfilled by the retailer) and Amazon's
            cross-border, used/returns, pharmacy and gift-card stores. If the
            retailer doesn't sell the item the item fails as unavailable. Takes
            the place of every merchant list: `included_merchants`,
            `excluded_merchants` and any blocklist on your account are not
            applied to this order. Applied to Amazon Business orders, Amazon
            orders placed with `retailer_credentials_id`, and Walmart orders;
            ignored elsewhere.
        concessions:
          items:
            $ref: '#/components/schemas/FulfillmentConcession'
          type: array
          title: Concessions
          default: []
      type: object
      title: OrderFulfillment
      description: |-
        What was asked (the per-concern modes, all null on a strict order) plus
        what was actually relaxed (``concessions``, empty when the order was
        fulfilled exactly as requested — which is every strict order).
    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.
    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).
    FulfillmentMode:
      type: string
      enum:
        - best_effort
      title: FulfillmentMode
      description: >-
        How hard to hold one order rule — the value of a ``fulfillment`` key

        (``fulfillment.items: "best_effort"``).


        Every mode loosens; strict is the *absence* of a mode, never a spelling
        of

        one. A future softer mode for a concern (``prefer``, ``nearest``) is a
        new

        member here; a future per-concern knob is that concern's value growing
        from

        a bare mode into an object — neither is a new top-level order field.
    OrderItemStatus:
      type: string
      enum:
        - pending
        - processing
        - ordered
        - shipped
        - available_for_pickup
        - delivered
        - cancelled
        - failed
        - skipped
      title: OrderItemStatus
    ErrorDetails:
      properties:
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
        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: []
        line_rejections:
          items:
            $ref: '#/components/schemas/LineRejection'
          type: array
          title: Line Rejections
          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
        discount:
          anyOf:
            - type: integer
            - type: 'null'
          title: Discount
          description: >-
            Promotion/free-shipping discount applied by the retailer, as a
            positive magnitude subtracted from the total. A nonzero `shipping`
            paired with an equal `discount` means shipping was itemized but
            waived — the total correctly excludes it.
        fees:
          anyOf:
            - type: integer
            - type: 'null'
          title: Fees
          description: >-
            Retailer fees not folded into subtotal/shipping/tax (gift wrap,
            import/regulatory charges), as a positive magnitude added to the
            total. Surfaced so a total exceeding the shown parts reads as an
            itemized fee rather than an unexplained charge.
        total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total
          description: >-
            Order total in `currency` (subtotal + tax + shipping + fees −
            discount).
        converted_payment_total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Converted Payment Total
          description: >-
            `total` converted to `payment_currency`, the currency actually
            charged. On an order billed in USD from a non-USD `currency`, this
            is the USD amount charged, including the FX markup; `total` stays in
            the retailer's currency. Equal to `total` when no conversion was
            charged.
        currency:
          anyOf:
            - type: string
            - type: 'null'
          title: Currency
        payment_currency:
          anyOf:
            - type: string
            - type: 'null'
          title: Payment Currency
        cart_items:
          anyOf:
            - items:
                $ref: '#/components/schemas/OrderCartItem'
              type: array
            - type: 'null'
          title: Cart Items
          description: >-
            Per-product rows making up `subtotal`. Distinct from `line_items`,
            which carries order-level adjustments (discounts, fees) and shares
            no fields with these — a discount is never a cart row. Null when the
            retailer's checkout page did not expose readable line items, so
            handle both `null` and `[]`. Individual fields may also be null on a
            row we could only partly read. Best-effort: `sum(line_total)`
            normally equals `subtotal`, but that is not guaranteed and must not
            be used as a billing input — the charge is always driven by `total`.
        line_items:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Line Items
          description: >-
            Order-level adjustments, each `{description, amount, category}`.
            Null — not `[]` — when the producer didn't supply them, which is
            every BizAPI-placed order today, so null-check before iterating.
        breakdown_recorded:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Breakdown Recorded
          description: >-
            False when `subtotal`/`tax`/`shipping` are placeholders rather than
            observed figures — an order an operator recorded by hand without
            itemizing the whole of what they paid. Those fields read `0` in that
            case, which must NOT be shown as '$0.00 tax': nothing was recorded.
            `total` is authoritative either way. Null on results written before
            this flag existed; treat null as true.
      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
        - available_for_pickup
        - delivered
        - undeliverable
      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.
    CaseReason:
      type: string
      enum:
        - not_received
        - missing_item
        - late
        - damaged_or_wrong_item
        - cancellation
        - address_change
        - return
        - billing
        - other
      title: CaseReason
      description: |-
        What a support case is about. Routing and reporting only — no reason
        triggers automation.
    CaseStatus:
      type: string
      enum:
        - open
        - waiting_on_customer
        - on_hold
        - closed
      title: CaseStatus
      description: >-
        Whose move it is on a support case.


        Only ``closed`` is terminal, and not even that for long: a customer
        reply

        inside the open window reopens a closed case rather than starting a new
        one.
    FulfillmentConcession:
      properties:
        concern:
          type: string
          enum:
            - gift
            - items
            - quantity
          title: Concern
        code:
          type: string
          title: Code
          description: Worker error code that would have failed a strict order.
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
        item_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Item Id
          description: Order item this concession is about, if any.
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
        requested_quantity:
          anyOf:
            - type: integer
            - type: 'null'
          title: Requested Quantity
        fulfilled_quantity:
          anyOf:
            - type: integer
            - type: 'null'
          title: Fulfilled Quantity
      additionalProperties: true
      type: object
      required:
        - concern
        - code
      title: FulfillmentConcession
      description: One rule that was actually relaxed while placing the order.
    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.


        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.
    LineRejection:
      properties:
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
        product_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Product Id
        requested_quantity:
          anyOf:
            - type: integer
            - type: 'null'
          title: Requested Quantity
        available_quantity:
          anyOf:
            - type: integer
            - type: 'null'
          title: Available Quantity
        codes:
          items:
            type: string
          type: array
          title: Codes
          default: []
        messages:
          items:
            type: string
          type: array
          title: Messages
          default: []
      type: object
      title: LineRejection
      description: One order line the retailer rejected, as it reported it (BizAPI).
    OrderCartItem:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        product_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Product Id
          description: >-
            Retailer product identifier (Amazon ASIN, Walmart item number, SKU)
            when one is visible on the page. Often absent — do not rely on it to
            join rows back to the requested products.
        quantity:
          anyOf:
            - type: integer
            - type: 'null'
          title: Quantity
        unit_price:
          anyOf:
            - type: integer
            - type: 'null'
          title: Unit Price
          description: Price per unit.
        line_total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Line Total
          description: >-
            Total for this row, normally `quantity * unit_price`. May differ
            when the retailer applies a per-line promotion.
      additionalProperties: true
      type: object
      title: OrderCartItem
      description: |-
        A single product row from the retailer's cart or order summary.

        Lenient and open (``extra="allow"``) like its siblings — it mirrors
        fulfillment output that may be partial. All amounts are in cents.
  securitySchemes:
    BearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Zinc API key (Bearer zn_...)

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.