Skip to main content
POST
/
agent
/
orders
Create Mpp Order
curl --request POST \
  --url https://api.zinc.com/agent/orders \
  --header 'Content-Type: application/json' \
  --data '
{
  "products": [
    {
      "url": "<string>",
      "quantity": 1,
      "variant": [
        {
          "label": "<string>",
          "value": "<string>"
        }
      ]
    }
  ],
  "shipping_address": {
    "first_name": "<string>",
    "last_name": "<string>",
    "address_line1": "<string>",
    "city": "<string>",
    "postal_code": "<string>",
    "phone_number": "<string>",
    "address_line2": "<string>",
    "state": "<string>",
    "country": "US"
  },
  "max_price": 123,
  "idempotency_key": "<string>",
  "retailer_credentials_id": "<string>",
  "metadata": {},
  "po_number": "<string>"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "max_price": 123,
  "attempts": 123,
  "items": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "url": "<string>",
      "quantity": 123,
      "status": "pending",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "variant": [
        {
          "label": "<string>",
          "value": "<string>"
        }
      ]
    }
  ],
  "shipping_address": {},
  "retailer_credentials_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "metadata": {},
  "po_number": "<string>",
  "tracking_numbers": []
}
Place an order using the Machine Payments Protocol (MPP) — 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
This endpoint uses the same OrderCreate request body as the standard Create Order endpoint. The only difference is how authentication and payment are handled.

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

WWW-Authenticate
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.
See the MPP guide for a full walkthrough of integrating MPP with Zinc.

Headers

authorization
string | null

Body

application/json

Request model for creating a new order.

products
OrderProduct · object[]
required
shipping_address
Address · object
required

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

max_price
integer
required

Maximum price (in cents) allowed for an order before it is finalized.

idempotency_key
string | null

Optional idempotency key to prevent duplicate orders. If not provided, one will be generated.

Maximum string length: 36
retailer_credentials_id
string | null

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
Metadata · object

Optional metadata to attach to the order. Can contain arbitrary key-value pairs.

po_number
string | null

Optional purchase order number for the order.

Response

Successful Response

Response model for order data.

id
string<uuid>
required
status
enum<string>
required
Available options:
pending,
in_progress,
order_placed,
order_failed,
cancelled
max_price
integer
required
attempts
integer
required
items
OrderItemResponse · object[]
required
shipping_address
Shipping Address · object
required
retailer_credentials_id
string | null
required
created_at
string<date-time>
required
updated_at
string<date-time>
required
metadata
Metadata · object
po_number
string | null
tracking_numbers
TrackingNumberResponse · object[]