Buy a product from a major online retailer and ship it to a US address
curl --request POST \
--url https://api.zinc.com/agent/orders \
--header 'Content-Type: application/json' \
--data '
{
"products": [
{
"url": "https://www.amazon.com/dp/B07JGBW826",
"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": 1,
"idempotency_key": "<string>",
"retailer_credentials_id": "<string>",
"metadata": {},
"po_number": "<string>",
"handling_days_max": 2,
"is_gift": false,
"gift_message": "<string>",
"payment": {
"mode": "wallet",
"payment_method": "<string>",
"customer": "<string>",
"margin": {
"value": 1
}
},
"customer_notifications": {
"email": "jsmith@example.com"
},
"fulfillment": {
"gift": "best_effort",
"items": "best_effort",
"quantity": "best_effort",
"excluded_merchants": [
"<string>"
]
}
}
'import requests
url = "https://api.zinc.com/agent/orders"
payload = {
"products": [
{
"url": "https://www.amazon.com/dp/B07JGBW826",
"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": 1,
"idempotency_key": "<string>",
"retailer_credentials_id": "<string>",
"metadata": {},
"po_number": "<string>",
"handling_days_max": 2,
"is_gift": False,
"gift_message": "<string>",
"payment": {
"mode": "wallet",
"payment_method": "<string>",
"customer": "<string>",
"margin": { "value": 1 }
},
"customer_notifications": { "email": "jsmith@example.com" },
"fulfillment": {
"gift": "best_effort",
"items": "best_effort",
"quantity": "best_effort",
"excluded_merchants": ["<string>"]
}
}
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: 'https://www.amazon.com/dp/B07JGBW826',
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: 1,
idempotency_key: '<string>',
retailer_credentials_id: '<string>',
metadata: {},
po_number: '<string>',
handling_days_max: 2,
is_gift: false,
gift_message: '<string>',
payment: {
mode: 'wallet',
payment_method: '<string>',
customer: '<string>',
margin: {value: 1}
},
customer_notifications: {email: 'jsmith@example.com'},
fulfillment: {
gift: 'best_effort',
items: 'best_effort',
quantity: 'best_effort',
excluded_merchants: ['<string>']
}
})
};
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' => 'https://www.amazon.com/dp/B07JGBW826',
'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' => 1,
'idempotency_key' => '<string>',
'retailer_credentials_id' => '<string>',
'metadata' => [
],
'po_number' => '<string>',
'handling_days_max' => 2,
'is_gift' => false,
'gift_message' => '<string>',
'payment' => [
'mode' => 'wallet',
'payment_method' => '<string>',
'customer' => '<string>',
'margin' => [
'value' => 1
]
],
'customer_notifications' => [
'email' => 'jsmith@example.com'
],
'fulfillment' => [
'gift' => 'best_effort',
'items' => 'best_effort',
'quantity' => 'best_effort',
'excluded_merchants' => [
'<string>'
]
]
]),
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\": \"https://www.amazon.com/dp/B07JGBW826\",\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\": 1,\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 \"gift_message\": \"<string>\",\n \"payment\": {\n \"mode\": \"wallet\",\n \"payment_method\": \"<string>\",\n \"customer\": \"<string>\",\n \"margin\": {\n \"value\": 1\n }\n },\n \"customer_notifications\": {\n \"email\": \"jsmith@example.com\"\n },\n \"fulfillment\": {\n \"gift\": \"best_effort\",\n \"items\": \"best_effort\",\n \"quantity\": \"best_effort\",\n \"excluded_merchants\": [\n \"<string>\"\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\": \"https://www.amazon.com/dp/B07JGBW826\",\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\": 1,\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 \"gift_message\": \"<string>\",\n \"payment\": {\n \"mode\": \"wallet\",\n \"payment_method\": \"<string>\",\n \"customer\": \"<string>\",\n \"margin\": {\n \"value\": 1\n }\n },\n \"customer_notifications\": {\n \"email\": \"jsmith@example.com\"\n },\n \"fulfillment\": {\n \"gift\": \"best_effort\",\n \"items\": \"best_effort\",\n \"quantity\": \"best_effort\",\n \"excluded_merchants\": [\n \"<string>\"\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\": \"https://www.amazon.com/dp/B07JGBW826\",\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\": 1,\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 \"gift_message\": \"<string>\",\n \"payment\": {\n \"mode\": \"wallet\",\n \"payment_method\": \"<string>\",\n \"customer\": \"<string>\",\n \"margin\": {\n \"value\": 1\n }\n },\n \"customer_notifications\": {\n \"email\": \"jsmith@example.com\"\n },\n \"fulfillment\": {\n \"gift\": \"best_effort\",\n \"items\": \"best_effort\",\n \"quantity\": \"best_effort\",\n \"excluded_merchants\": [\n \"<string>\"\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"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>"
}
],
"condition_in": [
"New"
],
"condition_not_in": [
"New"
],
"cancellation_reason": "<string>",
"error_type": "<string>",
"tracking_number_ids": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
]
}
],
"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,
"gift_message": "<string>",
"retailer_credentials_uuid": "<string>",
"job_result": {
"success": true,
"error": "<string>",
"error_type": "<string>",
"error_details": {
"code": "<string>",
"message": "<string>",
"url": "<string>",
"address_validation_reasons": [],
"field_errors": [],
"line_rejections": []
},
"price_components": {
"subtotal": 123,
"tax": 123,
"shipping": 123,
"discount": 123,
"fees": 123,
"total": 123,
"converted_payment_total": 123,
"currency": "<string>",
"payment_currency": "<string>",
"cart_items": [
{
"name": "<string>",
"product_id": "<string>",
"quantity": 123,
"unit_price": 123,
"line_total": 123
}
],
"line_items": [
{}
],
"breakdown_recorded": true
},
"estimated_delivery": "<string>",
"merchant_order_ids": [
{}
]
},
"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
},
"payment": {
"state": "<string>",
"authorized_cents": 123,
"fee_cents": 123,
"mode": "card",
"stripe_fee_cents": 123,
"captured_cents": 123,
"payment_method": "<string>",
"payment_intent_id": "<string>",
"simulated": false
},
"customer_notifications": {
"email": "<string>",
"delivered": true
},
"fulfillment": {
"gift": "best_effort",
"items": "best_effort",
"quantity": "best_effort",
"excluded_merchants": [
"<string>"
],
"concessions": []
}
}Agent
Create MPP Order
Place an order and pay per request via the Machine Payments Protocol (MPP) — no Zinc account required.
POST
/
agent
/
orders
Buy a product from a major online retailer and ship it to a US address
curl --request POST \
--url https://api.zinc.com/agent/orders \
--header 'Content-Type: application/json' \
--data '
{
"products": [
{
"url": "https://www.amazon.com/dp/B07JGBW826",
"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": 1,
"idempotency_key": "<string>",
"retailer_credentials_id": "<string>",
"metadata": {},
"po_number": "<string>",
"handling_days_max": 2,
"is_gift": false,
"gift_message": "<string>",
"payment": {
"mode": "wallet",
"payment_method": "<string>",
"customer": "<string>",
"margin": {
"value": 1
}
},
"customer_notifications": {
"email": "jsmith@example.com"
},
"fulfillment": {
"gift": "best_effort",
"items": "best_effort",
"quantity": "best_effort",
"excluded_merchants": [
"<string>"
]
}
}
'import requests
url = "https://api.zinc.com/agent/orders"
payload = {
"products": [
{
"url": "https://www.amazon.com/dp/B07JGBW826",
"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": 1,
"idempotency_key": "<string>",
"retailer_credentials_id": "<string>",
"metadata": {},
"po_number": "<string>",
"handling_days_max": 2,
"is_gift": False,
"gift_message": "<string>",
"payment": {
"mode": "wallet",
"payment_method": "<string>",
"customer": "<string>",
"margin": { "value": 1 }
},
"customer_notifications": { "email": "jsmith@example.com" },
"fulfillment": {
"gift": "best_effort",
"items": "best_effort",
"quantity": "best_effort",
"excluded_merchants": ["<string>"]
}
}
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: 'https://www.amazon.com/dp/B07JGBW826',
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: 1,
idempotency_key: '<string>',
retailer_credentials_id: '<string>',
metadata: {},
po_number: '<string>',
handling_days_max: 2,
is_gift: false,
gift_message: '<string>',
payment: {
mode: 'wallet',
payment_method: '<string>',
customer: '<string>',
margin: {value: 1}
},
customer_notifications: {email: 'jsmith@example.com'},
fulfillment: {
gift: 'best_effort',
items: 'best_effort',
quantity: 'best_effort',
excluded_merchants: ['<string>']
}
})
};
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' => 'https://www.amazon.com/dp/B07JGBW826',
'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' => 1,
'idempotency_key' => '<string>',
'retailer_credentials_id' => '<string>',
'metadata' => [
],
'po_number' => '<string>',
'handling_days_max' => 2,
'is_gift' => false,
'gift_message' => '<string>',
'payment' => [
'mode' => 'wallet',
'payment_method' => '<string>',
'customer' => '<string>',
'margin' => [
'value' => 1
]
],
'customer_notifications' => [
'email' => 'jsmith@example.com'
],
'fulfillment' => [
'gift' => 'best_effort',
'items' => 'best_effort',
'quantity' => 'best_effort',
'excluded_merchants' => [
'<string>'
]
]
]),
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\": \"https://www.amazon.com/dp/B07JGBW826\",\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\": 1,\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 \"gift_message\": \"<string>\",\n \"payment\": {\n \"mode\": \"wallet\",\n \"payment_method\": \"<string>\",\n \"customer\": \"<string>\",\n \"margin\": {\n \"value\": 1\n }\n },\n \"customer_notifications\": {\n \"email\": \"jsmith@example.com\"\n },\n \"fulfillment\": {\n \"gift\": \"best_effort\",\n \"items\": \"best_effort\",\n \"quantity\": \"best_effort\",\n \"excluded_merchants\": [\n \"<string>\"\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\": \"https://www.amazon.com/dp/B07JGBW826\",\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\": 1,\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 \"gift_message\": \"<string>\",\n \"payment\": {\n \"mode\": \"wallet\",\n \"payment_method\": \"<string>\",\n \"customer\": \"<string>\",\n \"margin\": {\n \"value\": 1\n }\n },\n \"customer_notifications\": {\n \"email\": \"jsmith@example.com\"\n },\n \"fulfillment\": {\n \"gift\": \"best_effort\",\n \"items\": \"best_effort\",\n \"quantity\": \"best_effort\",\n \"excluded_merchants\": [\n \"<string>\"\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\": \"https://www.amazon.com/dp/B07JGBW826\",\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\": 1,\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 \"gift_message\": \"<string>\",\n \"payment\": {\n \"mode\": \"wallet\",\n \"payment_method\": \"<string>\",\n \"customer\": \"<string>\",\n \"margin\": {\n \"value\": 1\n }\n },\n \"customer_notifications\": {\n \"email\": \"jsmith@example.com\"\n },\n \"fulfillment\": {\n \"gift\": \"best_effort\",\n \"items\": \"best_effort\",\n \"quantity\": \"best_effort\",\n \"excluded_merchants\": [\n \"<string>\"\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"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>"
}
],
"condition_in": [
"New"
],
"condition_not_in": [
"New"
],
"cancellation_reason": "<string>",
"error_type": "<string>",
"tracking_number_ids": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
]
}
],
"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,
"gift_message": "<string>",
"retailer_credentials_uuid": "<string>",
"job_result": {
"success": true,
"error": "<string>",
"error_type": "<string>",
"error_details": {
"code": "<string>",
"message": "<string>",
"url": "<string>",
"address_validation_reasons": [],
"field_errors": [],
"line_rejections": []
},
"price_components": {
"subtotal": 123,
"tax": 123,
"shipping": 123,
"discount": 123,
"fees": 123,
"total": 123,
"converted_payment_total": 123,
"currency": "<string>",
"payment_currency": "<string>",
"cart_items": [
{
"name": "<string>",
"product_id": "<string>",
"quantity": 123,
"unit_price": 123,
"line_total": 123
}
],
"line_items": [
{}
],
"breakdown_recorded": true
},
"estimated_delivery": "<string>",
"merchant_order_ids": [
{}
]
},
"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
},
"payment": {
"state": "<string>",
"authorized_cents": 123,
"fee_cents": 123,
"mode": "card",
"stripe_fee_cents": 123,
"captured_cents": 123,
"payment_method": "<string>",
"payment_intent_id": "<string>",
"simulated": false
},
"customer_notifications": {
"email": "<string>",
"delivered": true
},
"fulfillment": {
"gift": "best_effort",
"items": "best_effort",
"quantity": "best_effort",
"excluded_merchants": [
"<string>"
],
"concessions": []
}
}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/orderswith product and shipping details - Payment Challenge - If no valid payment credential is provided, the API returns HTTP
402with payment challenges for all configured methods - Submit Payment - Include a valid MPP payment credential in the
Authorizationheader - 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. The same limits apply — notably at most 10 products per order, checked before the agent is charged.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 the402 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
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 returns402 Payment Required with WWW-Authenticate headers describing the available payment methods.
Response Headers
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
Query Parameters
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.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
Maximum price (in cents) allowed for an order before it is finalized.
Required range:
x >= 0Optional idempotency key to prevent duplicate orders. If not provided, one will be generated.
Maximum string length:
36Optional 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.
Optional metadata to attach to the order. Can contain arbitrary key-value pairs.
Optional purchase order number for the order.
Optional ceiling on a seller's shipping and handling days. Omit or send null for no limit.
Required range:
x >= 1Mark 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.
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.
Maximum string length:
240Optional payment block. Omit for prepaid-wallet billing (default).
Show child attributes
Show child attributes
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).
Show child attributes
Show child attributes
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 tightens instead: merchants this order must not be bought from.
Show child attributes
Show child attributes
Response
Successful Response
Response model for order data.
Available options:
pending, in_progress, order_placed, order_failed, cancelled, cancelled_by_retailer Show child attributes
Show child attributes
Fulfillment result and price breakdown for a completed or failed order; null while processing.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Stripe Connect charge details when this order was paid via Connect; null for prepaid-wallet orders.
Show child attributes
Show child attributes
Card hold details when this order was paid by card outside the wallet and Connect; null for wallet and Connect orders.
Show child attributes
Show child attributes
End-customer email-notification status when the order opted into the notifications add-on; null when it didn't.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes