Skip to main content
GET
/
orders
List Orders
curl --request GET \
  --url https://api.zinc.com/orders \
  --header 'Authorization: <api-key>'
import requests

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

headers = {"Authorization": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

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 => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>"
],
]);

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

curl_close($curl);

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

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

func main() {

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

req, _ := http.NewRequest("GET", url, nil)

req.Header.Add("Authorization", "<api-key>")

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

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

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.zinc.com/orders")
.header("Authorization", "<api-key>")
.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::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body
{
  "orders": [
    {
      "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
      }
    }
  ],
  "total": 123,
  "limit": 123,
  "offset": 123
}
{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}
Retrieve a list of all orders associated with your account. Orders are returned in reverse chronological order (most recent first).

Response

Returns an array of order objects, each containing:
  • id - Order UUID
  • status - Current order status
  • items - Products in the order
  • shipping_address - Delivery address
  • job_result - Processing results (for completed/failed orders)
  • created_at - Order creation timestamp
  • updated_at - Last update timestamp

Order Statuses

StatusDescription
pendingOrder queued, not yet processing
in_progressOrder is being placed
orderedSuccessfully placed with retailer
shippedOrder shipped (tracking available)
deliveredOrder delivered to address
cancelledOrder was cancelled
failedOrder processing failed

Expanding tracking events

By default, list responses keep tracking payloads small: each tracking number includes its status but not the full carrier checkpoint timeline. Pass include=tracking_events to embed the per-scan checkpoints array on every tracking number.
curl "https://api.zinc.com/orders?include=tracking_events" \
  -H "Authorization: Bearer <your_api_key>"
The single-order read (GET /orders/{order_id}) always includes the full checkpoint timeline — include only affects the list endpoint. See Order Tracking for the checkpoint fields.

Pagination

Currently, all orders are returned in a single response. Pagination will be added in a future update.

Authorizations

Authorization
string
header
required

Zinc API key (Bearer zn_...)

Headers

authorization
string | null

Query Parameters

limit
integer
default:50

Number of orders to return

Required range: 1 <= x <= 500
offset
integer
default:0

Number of orders to skip

Required range: x >= 0
order_id
string | null

Filter by order ID (partial match)

status_filter
string | null

Filter by order status

return_status
string | null

Filter by return-request status. open → orders with at least one open return. closed → orders with at least one approved or denied return. Omit for no filter.

include
string[]

Optional expansions. tracking_events embeds the full carrier checkpoint timeline (and latest status) on each tracking number; omitted by default to keep list payloads small.

Response

Successful Response

List of orders for a particular user_id

orders
OrderResponse · object[]
required
total
integer
required
limit
integer
required
offset
integer
required