Create MPP Order - Zinc API Documentation

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>"
        }
      ],
      "condition_in": [],
      "condition_not_in": []
    }
  ],
  "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>",
  "handling_days_max": 2,
  "is_gift": false,
  "payment": {
    "mode": "wallet",
    "payment_method": "<string>",
    "customer": "<string>",
    "margin": {
      "value": 1
    }
  }
}
'

import requests

url = "https://api.zinc.com/agent/orders"

payload = {
    "products": [
        {
            "url": "<string>",
            "quantity": 1,
            "variant": [
                {
                    "label": "<string>",
                    "value": "<string>"
                }
            ],
            "condition_in": [],
            "condition_not_in": []
        }
    ],
    "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>",
    "handling_days_max": 2,
    "is_gift": False,
    "payment": {
        "mode": "wallet",
        "payment_method": "<string>",
        "customer": "<string>",
        "margin": { "value": 1 }
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    products: [
      {
        url: '<string>',
        quantity: 1,
        variant: [{label: '<string>', value: '<string>'}],
        condition_in: [],
        condition_not_in: []
      }
    ],
    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>',
    handling_days_max: 2,
    is_gift: false,
    payment: {
      mode: 'wallet',
      payment_method: '<string>',
      customer: '<string>',
      margin: {value: 1}
    }
  })
};

fetch('https://api.zinc.com/agent/orders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.zinc.com/agent/orders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'products' => [
        [
                'url' => '<string>',
                'quantity' => 1,
                'variant' => [
                                [
                                                                'label' => '<string>',
                                                                'value' => '<string>'
                                ]
                ],
                'condition_in' => [
                                
                ],
                'condition_not_in' => [
                                
                ]
        ]
    ],
    '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>',
    'handling_days_max' => 2,
    'is_gift' => false,
    'payment' => [
        'mode' => 'wallet',
        'payment_method' => '<string>',
        'customer' => '<string>',
        'margin' => [
                'value' => 1
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.zinc.com/agent/orders"

	payload := strings.NewReader("{\n  \"products\": [\n    {\n      \"url\": \"<string>\",\n      \"quantity\": 1,\n      \"variant\": [\n        {\n          \"label\": \"<string>\",\n          \"value\": \"<string>\"\n        }\n      ],\n      \"condition_in\": [],\n      \"condition_not_in\": []\n    }\n  ],\n  \"shipping_address\": {\n    \"first_name\": \"<string>\",\n    \"last_name\": \"<string>\",\n    \"address_line1\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"phone_number\": \"<string>\",\n    \"address_line2\": \"<string>\",\n    \"state\": \"<string>\",\n    \"country\": \"US\"\n  },\n  \"max_price\": 123,\n  \"idempotency_key\": \"<string>\",\n  \"retailer_credentials_id\": \"<string>\",\n  \"metadata\": {},\n  \"po_number\": \"<string>\",\n  \"handling_days_max\": 2,\n  \"is_gift\": false,\n  \"payment\": {\n    \"mode\": \"wallet\",\n    \"payment_method\": \"<string>\",\n    \"customer\": \"<string>\",\n    \"margin\": {\n      \"value\": 1\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.zinc.com/agent/orders")
  .header("Content-Type", "application/json")
  .body("{\n  \"products\": [\n    {\n      \"url\": \"<string>\",\n      \"quantity\": 1,\n      \"variant\": [\n        {\n          \"label\": \"<string>\",\n          \"value\": \"<string>\"\n        }\n      ],\n      \"condition_in\": [],\n      \"condition_not_in\": []\n    }\n  ],\n  \"shipping_address\": {\n    \"first_name\": \"<string>\",\n    \"last_name\": \"<string>\",\n    \"address_line1\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"phone_number\": \"<string>\",\n    \"address_line2\": \"<string>\",\n    \"state\": \"<string>\",\n    \"country\": \"US\"\n  },\n  \"max_price\": 123,\n  \"idempotency_key\": \"<string>\",\n  \"retailer_credentials_id\": \"<string>\",\n  \"metadata\": {},\n  \"po_number\": \"<string>\",\n  \"handling_days_max\": 2,\n  \"is_gift\": false,\n  \"payment\": {\n    \"mode\": \"wallet\",\n    \"payment_method\": \"<string>\",\n    \"customer\": \"<string>\",\n    \"margin\": {\n      \"value\": 1\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.zinc.com/agent/orders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"products\": [\n    {\n      \"url\": \"<string>\",\n      \"quantity\": 1,\n      \"variant\": [\n        {\n          \"label\": \"<string>\",\n          \"value\": \"<string>\"\n        }\n      ],\n      \"condition_in\": [],\n      \"condition_not_in\": []\n    }\n  ],\n  \"shipping_address\": {\n    \"first_name\": \"<string>\",\n    \"last_name\": \"<string>\",\n    \"address_line1\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"phone_number\": \"<string>\",\n    \"address_line2\": \"<string>\",\n    \"state\": \"<string>\",\n    \"country\": \"US\"\n  },\n  \"max_price\": 123,\n  \"idempotency_key\": \"<string>\",\n  \"retailer_credentials_id\": \"<string>\",\n  \"metadata\": {},\n  \"po_number\": \"<string>\",\n  \"handling_days_max\": 2,\n  \"is_gift\": false,\n  \"payment\": {\n    \"mode\": \"wallet\",\n    \"payment_method\": \"<string>\",\n    \"customer\": \"<string>\",\n    \"margin\": {\n      \"value\": 1\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "max_price": 123,
  "attempts": 123,
  "items": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "url": "<string>",
      "quantity": 123,
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "variant": [
        {
          "label": "<string>",
          "value": "<string>"
        }
      ],
      "condition_in": [],
      "condition_not_in": [],
      "cancellation_reason": "<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>",
  "handling_days_max": 123,
  "is_gift": false,
  "retailer_credentials_uuid": "<string>",
  "job_result": {
    "success": true,
    "error": "<string>",
    "error_type": "<string>",
    "error_details": {
      "code": "<string>",
      "message": "<string>",
      "address_validation_reasons": [],
      "field_errors": []
    },
    "price_components": {
      "subtotal": 123,
      "tax": 123,
      "shipping": 123,
      "total": 123,
      "converted_payment_total": 123,
      "currency": "<string>",
      "payment_currency": "<string>",
      "line_items": [
        {}
      ]
    },
    "estimated_delivery": "<string>",
    "merchant_order_ids": [
      {}
    ]
  },
  "tracking_numbers": [],
  "created_by": "<string>",
  "user_id": 123,
  "returns": [],
  "connect": {
    "state": "<string>",
    "secured_amount": 123,
    "order_cost": 123,
    "customer_margin": 123,
    "zinc_fee": 123,
    "stripe_fee": 123,
    "final_charge": 123,
    "transfer_amount": 123,
    "payment_intent_id": "<string>",
    "connected_account_id": "<string>",
    "simulated": false
  }
}

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>"
        }
      ],
      "condition_in": [],
      "condition_not_in": []
    }
  ],
  "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>",
  "handling_days_max": 2,
  "is_gift": false,
  "payment": {
    "mode": "wallet",
    "payment_method": "<string>",
    "customer": "<string>",
    "margin": {
      "value": 1
    }
  }
}
'

import requests

url = "https://api.zinc.com/agent/orders"

payload = {
    "products": [
        {
            "url": "<string>",
            "quantity": 1,
            "variant": [
                {
                    "label": "<string>",
                    "value": "<string>"
                }
            ],
            "condition_in": [],
            "condition_not_in": []
        }
    ],
    "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>",
    "handling_days_max": 2,
    "is_gift": False,
    "payment": {
        "mode": "wallet",
        "payment_method": "<string>",
        "customer": "<string>",
        "margin": { "value": 1 }
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    products: [
      {
        url: '<string>',
        quantity: 1,
        variant: [{label: '<string>', value: '<string>'}],
        condition_in: [],
        condition_not_in: []
      }
    ],
    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>',
    handling_days_max: 2,
    is_gift: false,
    payment: {
      mode: 'wallet',
      payment_method: '<string>',
      customer: '<string>',
      margin: {value: 1}
    }
  })
};

fetch('https://api.zinc.com/agent/orders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.zinc.com/agent/orders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'products' => [
        [
                'url' => '<string>',
                'quantity' => 1,
                'variant' => [
                                [
                                                                'label' => '<string>',
                                                                'value' => '<string>'
                                ]
                ],
                'condition_in' => [
                                
                ],
                'condition_not_in' => [
                                
                ]
        ]
    ],
    '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>',
    'handling_days_max' => 2,
    'is_gift' => false,
    'payment' => [
        'mode' => 'wallet',
        'payment_method' => '<string>',
        'customer' => '<string>',
        'margin' => [
                'value' => 1
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.zinc.com/agent/orders"

	payload := strings.NewReader("{\n  \"products\": [\n    {\n      \"url\": \"<string>\",\n      \"quantity\": 1,\n      \"variant\": [\n        {\n          \"label\": \"<string>\",\n          \"value\": \"<string>\"\n        }\n      ],\n      \"condition_in\": [],\n      \"condition_not_in\": []\n    }\n  ],\n  \"shipping_address\": {\n    \"first_name\": \"<string>\",\n    \"last_name\": \"<string>\",\n    \"address_line1\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"phone_number\": \"<string>\",\n    \"address_line2\": \"<string>\",\n    \"state\": \"<string>\",\n    \"country\": \"US\"\n  },\n  \"max_price\": 123,\n  \"idempotency_key\": \"<string>\",\n  \"retailer_credentials_id\": \"<string>\",\n  \"metadata\": {},\n  \"po_number\": \"<string>\",\n  \"handling_days_max\": 2,\n  \"is_gift\": false,\n  \"payment\": {\n    \"mode\": \"wallet\",\n    \"payment_method\": \"<string>\",\n    \"customer\": \"<string>\",\n    \"margin\": {\n      \"value\": 1\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.zinc.com/agent/orders")
  .header("Content-Type", "application/json")
  .body("{\n  \"products\": [\n    {\n      \"url\": \"<string>\",\n      \"quantity\": 1,\n      \"variant\": [\n        {\n          \"label\": \"<string>\",\n          \"value\": \"<string>\"\n        }\n      ],\n      \"condition_in\": [],\n      \"condition_not_in\": []\n    }\n  ],\n  \"shipping_address\": {\n    \"first_name\": \"<string>\",\n    \"last_name\": \"<string>\",\n    \"address_line1\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"phone_number\": \"<string>\",\n    \"address_line2\": \"<string>\",\n    \"state\": \"<string>\",\n    \"country\": \"US\"\n  },\n  \"max_price\": 123,\n  \"idempotency_key\": \"<string>\",\n  \"retailer_credentials_id\": \"<string>\",\n  \"metadata\": {},\n  \"po_number\": \"<string>\",\n  \"handling_days_max\": 2,\n  \"is_gift\": false,\n  \"payment\": {\n    \"mode\": \"wallet\",\n    \"payment_method\": \"<string>\",\n    \"customer\": \"<string>\",\n    \"margin\": {\n      \"value\": 1\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.zinc.com/agent/orders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"products\": [\n    {\n      \"url\": \"<string>\",\n      \"quantity\": 1,\n      \"variant\": [\n        {\n          \"label\": \"<string>\",\n          \"value\": \"<string>\"\n        }\n      ],\n      \"condition_in\": [],\n      \"condition_not_in\": []\n    }\n  ],\n  \"shipping_address\": {\n    \"first_name\": \"<string>\",\n    \"last_name\": \"<string>\",\n    \"address_line1\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"phone_number\": \"<string>\",\n    \"address_line2\": \"<string>\",\n    \"state\": \"<string>\",\n    \"country\": \"US\"\n  },\n  \"max_price\": 123,\n  \"idempotency_key\": \"<string>\",\n  \"retailer_credentials_id\": \"<string>\",\n  \"metadata\": {},\n  \"po_number\": \"<string>\",\n  \"handling_days_max\": 2,\n  \"is_gift\": false,\n  \"payment\": {\n    \"mode\": \"wallet\",\n    \"payment_method\": \"<string>\",\n    \"customer\": \"<string>\",\n    \"margin\": {\n      \"value\": 1\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "max_price": 123,
  "attempts": 123,
  "items": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "url": "<string>",
      "quantity": 123,
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "variant": [
        {
          "label": "<string>",
          "value": "<string>"
        }
      ],
      "condition_in": [],
      "condition_not_in": [],
      "cancellation_reason": "<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>",
  "handling_days_max": 123,
  "is_gift": false,
  "retailer_credentials_uuid": "<string>",
  "job_result": {
    "success": true,
    "error": "<string>",
    "error_type": "<string>",
    "error_details": {
      "code": "<string>",
      "message": "<string>",
      "address_validation_reasons": [],
      "field_errors": []
    },
    "price_components": {
      "subtotal": 123,
      "tax": 123,
      "shipping": 123,
      "total": 123,
      "converted_payment_total": 123,
      "currency": "<string>",
      "payment_currency": "<string>",
      "line_items": [
        {}
      ]
    },
    "estimated_delivery": "<string>",
    "merchant_order_ids": [
      {}
    ]
  },
  "tracking_numbers": [],
  "created_by": "<string>",
  "user_id": 123,
  "returns": [],
  "connect": {
    "state": "<string>",
    "secured_amount": 123,
    "order_cost": 123,
    "customer_margin": 123,
    "zinc_fee": 123,
    "stripe_fee": 123,
    "final_charge": 123,
    "transfer_amount": 123,
    "payment_intent_id": "<string>",
    "connected_account_id": "<string>",
    "simulated": false
  }
}

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

Send Order Request - Submit an order to /agent/orders with product and shipping details
Payment Challenge - If no valid payment credential is provided, the API returns HTTP 402 with payment challenges for all configured methods
Submit Payment - Include a valid MPP payment credential in the Authorization header
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 is the gate

Payment — not request validation — is the gate on this endpoint. The body is parsed leniently so that an unpaid request reaches the 402 payment challenge instead of being rejected first by schema validation. This means an automated MPP discovery probe can send no body, an empty body, or a partial body and still receive the 402 challenge describing how to pay. The body is only validated strictly once a valid payment credential is present. After paying, send a complete, valid OrderCreate body — an incomplete one will then be rejected with a 422.

Payment Methods

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

Stripe - Cards and wallets
Tempo - Stablecoins

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

402 Payment Required

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

Response Headers

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

Query Parameters

method

string | null

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.

Body

application/json

Request model for creating a new order.

products

OrderProduct · object[]

required

Show child attributes

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

Show child attributes

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 | null

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

po_number

string | null

Optional purchase order number for the order.

handling_days_max

integer | null

Optional ceiling on a seller's shipping and handling days. Omit or send null for no limit.

Required range: x >= 1

is_gift

boolean

default:false

Mark the order as a gift. Prices are suppressed on the packing slip where the fulfillment method supports it.

payment

OrderPayment · object | null

Optional payment block. Omit for prepaid-wallet billing (default).

Show child attributes

Response

Successful Response

Response model for order data.

string<uuid>

required

status

enum<string>

required

Available options:

pending,

in_progress,

order_placed,

order_failed,

cancelled,

cancelled_by_retailer

max_price

integer

required

attempts

integer

required

items

OrderItemResponse · object[]

required

Show child attributes

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

handling_days_max

integer | null

is_gift

boolean

default:false

retailer_credentials_uuid

string | null

job_result

OrderJobResult · object | null

Fulfillment result and price breakdown for a completed or failed order; null while processing.

Show child attributes

tracking_numbers

TrackingNumberResponse · object[]

Show child attributes

created_by

string | null

user_id

integer | null

returns

ReturnRequestSummary · object[]

Show child attributes

connect

OrderConnectInfo · object | null

Stripe Connect charge details when this order was paid via Connect; null for prepaid-wallet orders.

Show child attributes

List Retailers Agent Search

⌘I

​How It Works

​Payment is the gate

​Payment Methods

​402 Payment Required

​Response Headers

Headers

Query Parameters

Body

Response

How It Works

Payment is the gate

Payment Methods

402 Payment Required

Response Headers