Create Order - Zinc API Documentation

Create Order

curl --request POST \
  --url https://api.zinc.com/orders \
  --header 'Authorization: <api-key>' \
  --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/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 = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', '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/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/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 => [
    "Authorization: <api-key>",
    "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/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("Authorization", "<api-key>")
	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/orders")
  .header("Authorization", "<api-key>")
  .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/orders")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
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
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

POST

orders

Create Order

curl --request POST \
  --url https://api.zinc.com/orders \
  --header 'Authorization: <api-key>' \
  --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/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 = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', '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/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/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 => [
    "Authorization: <api-key>",
    "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/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("Authorization", "<api-key>")
	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/orders")
  .header("Authorization", "<api-key>")
  .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/orders")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
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
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Create a new order for processing. Orders are queued and processed asynchronously.

Request Flow

Submit Order - Send order details including products and shipping address
Validation - We validate product URLs and shipping address
Queued - Order is queued for processing
Processing - Our system places the order with the retailer
Completed - You receive confirmation with tracking details

Product URLs

Provide direct product URLs from supported retailers. Each product must include:

url - Direct link to the product page

Make sure product URLs are accessible and lead directly to the product page, not search results or category pages.

Optionally, the product can include:

quantity - Number of items to order (integer, default 1)
variant - A list of label, value pairs indicating a variant of a product. For example, if you’re ordering a shirt. The shirt may come in different colors and different sizes. To indicate a red medium shirt, you would do:
```
[
  {
    "label": "Color",
    "value": "Red"
  },
  {
    "label": "Size",
    "value": "Medium"
  }
]
```
Make sure the strings used for both the label and value match up to what is present on the retailer website. For example, if a medium is indicated by the value M, use M for the value.
condition_in / condition_not_in - Condition allow/deny lists. Limit which offers are eligible by item condition — useful for buying only new items, or for accepting used items down to a floor. See Condition Filtering.

Shipping Address

All orders require a valid shipping address. Addresses are validated using Google’s Address Validation API. Required fields:

first_name and last_name
address_line1 (use address_line2 for apartment/suite, optional)
city
postal_code
phone_number

Optional fields:

state — omit for countries that don’t use states/provinces
country — ISO 3166-1 alpha-2 code (e.g. US, CA, GB, DE); defaults to US

International shipping is supported. Provide the destination country as an ISO 3166-1 alpha-2 code; state is optional where it doesn’t apply.

Payment

By default, orders draw from your prepaid wallet — no payment object needed. To charge your own end-customer’s card instead and keep a margin, include a payment object with mode: "connect". See the Stripe Connect guide for the full flow.

Field	Required	Description
`mode`		`"wallet"` (default) or `"connect"`.
`payment_method`	connect	Your end-customer’s saved Stripe payment-method id (`pm_…`) on your connected account.
`customer`	connect	Your end-customer’s Stripe Customer id (`cus_…`) on your connected account.
`margin`	connect	Your markup: `{ "type": "flat", "value": <cents> }` or `{ "type": "percent", "value": <percent> }`.

In Connect mode the authorization hold is sized from max_price; your end-customer is charged the actual total when Zinc places the order with the retailer.

{
  "payment": {
    "mode": "connect",
    "payment_method": "pm_1ExampleCard",
    "customer": "cus_ExampleEndCustomer",
    "margin": { "type": "flat", "value": 250 }
  }
}

Optional Order Data

You can include additional data with your order for tracking and reference purposes. This data will be used by our system as input to any fields during checkout that match.

po_number - Your internal purchase order number for tracking and reconciliation
is_gift - Mark the order as a gift (boolean, default false). Prices are suppressed on the packing slip where the fulfillment method supports it.
handling_days_max - Optional ceiling on a seller’s handling days (integer, minimum 1). Offers from sellers whose handling time exceeds this are skipped. Omit or send null for no limit.

If you only need data for internal reference, use the metadata field instead.

Response

A successful order creation returns:

id - Unique order identifier (UUID)
status - Current order status (initially “pending”)
items - Array of order items with their details
shipping_address - Confirmed shipping address
created_at - Timestamp of order creation

Use the order id to retrieve order status and updates.

Authorizations

Authorization

string

header

required

Zinc API key (Bearer zn_...)

Headers

authorization

string | null

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

Cross-Retailer Search List Orders

⌘I

​Request Flow

​Product URLs

​Shipping Address

​Payment

​Optional Order Data

​Response

Authorizations

Headers

Body

Response

Request Flow

Product URLs

Shipping Address

Payment

Optional Order Data

Response