Create Agent Order

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": [],
  "cases": [],
  "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": []
  }
}

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": [],
  "cases": [],
  "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 and pay for it per request over HTTP 402 Payment Required. You don’t need a Zinc account or API key. The agent pays max_price + the $1.00 API fee upfront, and anything the order doesn’t use is refunded to the original payment.

Rail	Pays with	Proof header on the retry
Link	A card from the user’s Link wallet, as a Shared Payment Token (MPP `method="stripe"`)	`Authorization: Payment <credential>`
Tempo	USDC on Tempo (MPP `method="tempo"`)	`Authorization: Payment <credential>`
x402	USDC on Base or Solana	`PAYMENT-SIGNATURE` (v2) or `X-PAYMENT` (v1)

How It Works

Send the order — POST /agent/orders with a complete order body and no payment.
Get the challenge — Zinc checks the body and returns 402 with a challenge for every rail: one WWW-Authenticate header per MPP method, plus a PAYMENT-REQUIRED header for x402.
Pay and resubmit — pay on one rail and send the identical request again with the proof header.
Order placed — Zinc verifies the payment and returns 201 with the order and an X-Api-Key header.

This endpoint takes the same OrderCreate body as the standard Create Order endpoint. Only authentication and payment differ. The same limits apply, including at most 10 products per order, and they’re checked before the agent is charged.

Validation before payment

An agent is never charged for an order Zinc would reject:

No body, {}, or null — treated as a discovery probe (for example from a service registry) and answered with a 402 at a placeholder amount.
A malformed or incomplete body (including invalid JSON) — 422 straight away. No challenge is issued.
An order Zinc can’t fulfill (unsupported retailer, unreachable product URL, unsupported shipping country, invalid address) — checked on the paid retry, before the proof is charged, and rejected with 400. The payment is left untouched, so you can fix the order and retry with it.

Send the complete body on the first request. The challenge amount comes from its max_price.

Choosing a rail

By default the 402 lists every rail. Add ?method=stripe, ?method=tempo, or ?method=x402 to get only that challenge. This helps clients that can’t pick one WWW-Authenticate header out of several. An unknown method returns 400 with the available ones in error.details.available.

Responses

402 Payment Required

string

One header per MPP method (stripe, tempo), per RFC 9110 §11.6.1. Your MPP client or link-cli uses it to pay and resubmit.

string

Base64 x402 v2 PaymentRequired envelope, with one accepts[] entry per supported chain.

201 Created

string

API key for the paying agent. Use it to read the order (GET /orders/{id}), cancel it while pending, and register a webhook URL (PUT /webhooks/endpoint). Store it. It’s the only way to follow the order without paying again.

string

MPP receipt for the charge (Link and Tempo).

string

x402 settlement response (x402 only).

409 Conflict

Returned when this payer already placed an order with the same idempotency_key. The check runs after the payment proof is verified but before it’s settled, so retrying a request that timed out never charges twice. The existing order’s id is in error.details.order_id, and the response carries an X-Api-Key header to read it.

See Agentic Purchases for a full walkthrough of paying with Link, MPP, or x402, including the one-command link-cli mpp pay flow.

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

Minimum array length: 1

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

max_price

integer

required

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

Required range: x >= 0

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

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

gift_message

string | null

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: 240

payment

OrderPayment · object | null

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

Show child attributes

customer_notifications

CustomerNotifications · object | null

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

fulfillment

FulfillmentPreferences · object | null

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

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

gift_message

string | null

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

merchant_order_ids

string[]

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.

tracking_numbers

TrackingNumberResponse · object[]

Show child attributes

created_by

string | null

user_id

integer | null

returns

ReturnRequestSummary · object[]

Show child attributes

cases

CaseSummary · object[]

Support cases on this order, newest first. See /cases.

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

payment

OrderPaymentInfo · object | null

Card hold details when this order was paid by card outside the wallet and Connect; null for wallet and Connect orders.

Show child attributes

customer_notifications

CustomerNotificationStatus · object | null

End-customer email-notification status when the order opted into the notifications add-on; null when it didn't.

Show child attributes

fulfillment

OrderFulfillment · object

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

Getting Started

Agent Sandbox

Device Approval

Search (Beta)

Orders

Bulk Orders

Managed Accounts

Returns

Cases

Product Data

Retailers

Agent

Wallet

Webhooks

Usage

Create Agent Order

How It Works

Validation before payment

Choosing a rail

Responses

402 Payment Required

201 Created

409 Conflict

Headers

Query Parameters

Body

Response

​How It Works

​Validation before payment

​Choosing a rail

​Responses

​402 Payment Required

​201 Created

​409 Conflict

Headers

Query Parameters

Body

Response

How It Works

Validation before payment

Choosing a rail

Responses

402 Payment Required

201 Created

409 Conflict