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

# Create MPP Order

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

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

## How It Works

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

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

## Payment Methods

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

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

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

## 402 Payment Required

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

### Response Headers

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

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


## OpenAPI

````yaml /versions/latest.json POST /agent/orders
openapi: 3.1.0
info:
  title: Zinc
  summary: >-
    Zinc lets you search, buy, and return items from top online retailers with a
    single API.
  description: >-
    Search, buy, and return items from top online retailers with a single API.
    Supports AI agent ordering via MPP (HTTP 402) — no account required.
  version: '2026-04-27'
  x-logo:
    url: https://mintlify.s3.us-west-1.amazonaws.com/zinc/logo/light.png
  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 (e.g. Amazon),
    shipping address, and max_price in cents. The API charges max_price + $1 API
    fee upfront and refunds the difference on completion. Authenticated
    endpoints (orders, products, managed-accounts) require a Bearer token (API
    key prefixed zn_). Docs: https://zinc.com/docs
servers:
  - url: https://api.zinc.com
    description: Production
security:
  - BearerAuth: []
paths:
  /agent/orders:
    post:
      tags:
        - agent
      summary: Create Mpp Order
      description: |-
        Place an order via the Machine Payments Protocol (MPP).

        No Zinc account required. Payment is made upfront via MPP.
        Supports multiple payment methods (e.g. Tempo, Stripe).
        If no valid payment credential is provided, returns HTTP 402
        with payment challenges for all configured methods.
      operationId: create_mpp_order_agent_orders_post
      parameters:
        - name: authorization
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
          headers:
            X-Api-Key:
              description: >-
                API key for the MPP agent to check order status via GET
                /orders/{id}
              schema:
                type: string
            Payment-Receipt:
              description: MPP payment receipt confirming the charge
              schema:
                type: string
        '402':
          description: >-
            Payment required — returns challenge details for each configured
            payment method
          headers:
            WWW-Authenticate:
              description: >-
                One header per supported payment method with challenge
                parameters (per RFC 9110 §11.6.1)
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security: []
components:
  schemas:
    OrderCreate:
      properties:
        products:
          items:
            $ref: '#/components/schemas/OrderProduct'
          type: array
          title: Products
        shipping_address:
          $ref: '#/components/schemas/Address'
        max_price:
          type: integer
          title: Max Price
          description: >-
            Maximum price (in cents) allowed for an order before it is
            finalized.
        idempotency_key:
          anyOf:
            - type: string
              maxLength: 36
            - type: 'null'
          title: Idempotency Key
          description: >-
            Optional idempotency key to prevent duplicate orders. If not
            provided, one will be generated.
        retailer_credentials_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Retailer Credentials Id
          description: >-
            Optional short ID (e.g., 'zn_acct_XXXXXXXX') of specific retailer
            credentials to use for this order. If not provided, credentials will
            be selected automatically.
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: >-
            Optional metadata to attach to the order. Can contain arbitrary
            key-value pairs.
        po_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Po Number
          description: Optional purchase order number for the order.
      type: object
      required:
        - products
        - shipping_address
        - max_price
      title: OrderCreate
      description: Request model for creating a new order.
    OrderResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        status:
          $ref: '#/components/schemas/OrderStatus'
        max_price:
          type: integer
          title: Max Price
        attempts:
          type: integer
          title: Attempts
        items:
          items:
            $ref: '#/components/schemas/OrderItemResponse'
          type: array
          title: Items
        shipping_address:
          additionalProperties: true
          type: object
          title: Shipping Address
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          default: {}
        po_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Po Number
        retailer_credentials_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Retailer Credentials Id
        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: []
        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
    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)
      type: object
      required:
        - url
      title: OrderProduct
      description: |-
        Product item for an order.

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


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

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

        country codes (e.g., "US", "CA", "GB", "DE").
    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
        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.
    TrackingNumberResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        carrier:
          type: string
          title: Carrier
        tracking_number:
          type: string
          title: Tracking Number
        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.
    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
    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.).
    OrderItemStatus:
      type: string
      enum:
        - pending
        - processing
        - ordered
        - shipped
        - delivered
        - cancelled
        - failed
      title: OrderItemStatus
    ReturnRequestStatus:
      type: string
      enum:
        - open
        - approved
        - denied
      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.
  securitySchemes:
    BearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Zinc API key (Bearer zn_...)

````