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

# Get Order

> Retrieve a specific order by ID

Retrieve detailed information about a specific order using its unique identifier.

## Path Parameters

* **order\_id** (required) - The UUID of the order to retrieve

## Response

Returns a complete order object with:

* **id** - Order UUID
* **status** - Current order status
* **items** - Array of order items with individual statuses
* **shipping\_address** - Delivery address
* **job\_result** - Detailed processing results (when available)
* **created\_at** - Order creation timestamp
* **updated\_at** - Last update timestamp

## Item-Level Status

Each item in the order has its own status tracking:

```json theme={null}
{
  "id": "item-uuid",
  "url": "https://www.amazon.com/...",
  "quantity": 2,
  "status": "shipped",
  "created_at": "2025-11-24T10:00:00Z",
  "updated_at": "2025-11-24T12:30:00Z"
}
```

## Job Results

For completed or failed orders, the `job_result` field contains detailed information about the order processing, including:

* Success/failure status
* Retailer confirmation numbers
* Tracking information
* Error details (if failed)

<Tip>
  Poll this endpoint to track order progress. We recommend checking every 30-60 seconds while the order is processing.
</Tip>

## Price Components

Once the retailer total is known, `job_result.price_components` breaks the charge down. All amounts are in **cents**.

| Field                     | Description                                                     |
| ------------------------- | --------------------------------------------------------------- |
| `subtotal`                | Item subtotal before tax and shipping                           |
| `tax`                     | Tax charged by the retailer                                     |
| `shipping`                | Shipping charged by the retailer                                |
| `total`                   | Order total in the order currency (`subtotal + tax + shipping`) |
| `converted_payment_total` | `total` converted to the currency actually charged              |
| `currency`                | Currency of `total` (e.g. `USD`)                                |
| `payment_currency`        | Currency the order was paid in                                  |
| `line_items`              | Itemized rows, each `{ description, amount, category }`         |

```json theme={null}
{
  "job_result": {
    "success": true,
    "price_components": {
      "subtotal": 4800,
      "tax": 396,
      "shipping": 0,
      "total": 5196,
      "converted_payment_total": 5196,
      "currency": "USD",
      "payment_currency": "USD",
      "line_items": [
        { "description": "Subtotal", "amount": 4800, "category": "subtotal" },
        { "description": "Tax", "amount": 396, "category": "tax" }
      ]
    }
  }
}
```

## Connect Charge

For orders paid via [Stripe Connect](/v2/connect), the response includes a `connect` object with the charge breakdown and its current state. It is `null` for prepaid-wallet orders. All amounts are in **cents**.

| Field                  | Description                                                                                    |
| ---------------------- | ---------------------------------------------------------------------------------------------- |
| `state`                | `secured` → `captured`, or `released` / `refunded` on a terminal outcome.                      |
| `secured_amount`       | Amount held on the end-customer's card when the order was placed (sized from `max_price`).     |
| `order_cost`           | Actual order cost (goods), captured once Zinc places the order with the retailer.              |
| `customer_margin`      | Your margin, transferred to your connected account.                                            |
| `zinc_fee`             | Zinc's platform fee.                                                                           |
| `stripe_fee`           | Stripe's processing fee on the charge.                                                         |
| `final_charge`         | Total captured from the end-customer (`order_cost + customer_margin + zinc_fee + stripe_fee`). |
| `transfer_amount`      | Amount transferred to your connected account (your margin).                                    |
| `payment_intent_id`    | Stripe PaymentIntent id (`pi_…`) for the charge.                                               |
| `connected_account_id` | Your connected account id (`acct_…`).                                                          |
| `simulated`            | `true` for test-mode orders that didn't hit Stripe.                                            |

The post-capture fields (`order_cost` and below) are populated once the order is placed and the actual total is captured; before that they are `null` and `state` is `secured`.

```json theme={null}
{
  "connect": {
    "state": "captured",
    "secured_amount": 6041,
    "order_cost": 4800,
    "customer_margin": 250,
    "zinc_fee": 100,
    "stripe_fee": 185,
    "final_charge": 5335,
    "transfer_amount": 250,
    "payment_intent_id": "pi_3ExampleCharge",
    "connected_account_id": "acct_1ExampleConnected",
    "simulated": false
  }
}
```

## Error Responses

* **404 Not Found** - Order ID does not exist or you don't have access to it
* **401 Unauthorized** - Invalid or missing authentication


## OpenAPI

````yaml versions/latest.json GET /orders/{order_id}
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:
  /orders/{order_id}:
    get:
      tags:
        - orders
      summary: Get Order
      description: Retrieves an order by its ID
      operationId: get_order_orders__order_id__get
      parameters:
        - name: order_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Order Id
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    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.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    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.
    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_...)

````