Skip to main content
GET
/
orders
/
{order_id}
Get Order
curl --request GET \
  --url https://api.zinc.com/orders/{order_id} \
  --header 'Authorization: <api-key>'
import requests

url = "https://api.zinc.com/orders/{order_id}"

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/{order_id}', 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/{order_id}",
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/{order_id}"

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/{order_id}")
.header("Authorization", "<api-key>")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.zinc.com/orders/{order_id}")

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
{
  "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>"
}
]
}
Retrieve detailed information about a specific order using its unique identifier.

Path Parameters

  • order_id (required) - The UUID of the order to retrieve

Response

Returns a complete order object with:
  • id - Order UUID
  • status - Current order status
  • items - Array of order items with individual statuses
  • shipping_address - Delivery address
  • job_result - Detailed processing results (when available)
  • created_at - Order creation timestamp
  • updated_at - Last update timestamp

Item-Level Status

Each item in the order has its own status tracking:
{
  "id": "item-uuid",
  "url": "https://www.amazon.com/...",
  "quantity": 2,
  "status": "shipped",
  "created_at": "2025-11-24T10:00:00Z",
  "updated_at": "2025-11-24T12:30:00Z"
}

Job Results

For completed or failed orders, the job_result field contains detailed information about the order processing, including:
  • Success/failure status
  • Retailer confirmation numbers
  • Tracking information
  • Error details (if failed)
Poll this endpoint to track order progress. We recommend checking every 30-60 seconds while the order is processing.

Price Components

Once the retailer total is known, job_result.price_components breaks the charge down. All amounts are in cents.
FieldDescription
subtotalItem subtotal before tax and shipping
taxTax charged by the retailer
shippingShipping charged by the retailer
totalOrder total in the order currency (subtotal + tax + shipping)
converted_payment_totaltotal converted to the currency actually charged
currencyCurrency of total (e.g. USD)
payment_currencyCurrency the order was paid in
line_itemsItemized rows, each { description, amount, category }
{
  "job_result": {
    "success": true,
    "price_components": {
      "subtotal": 4800,
      "tax": 396,
      "shipping": 0,
      "total": 5196,
      "converted_payment_total": 5196,
      "currency": "USD",
      "payment_currency": "USD",
      "line_items": [
        { "description": "Subtotal", "amount": 4800, "category": "subtotal" },
        { "description": "Tax", "amount": 396, "category": "tax" }
      ]
    }
  }
}

Connect Charge

For orders paid via Stripe Connect, the response includes a connect object with the charge breakdown and its current state. It is null for prepaid-wallet orders. All amounts are in cents.
FieldDescription
statesecuredcaptured, or released / refunded on a terminal outcome.
secured_amountAmount held on the end-customer’s card when the order was placed (sized from max_price).
order_costActual order cost (goods), captured once Zinc places the order with the retailer.
customer_marginYour margin, transferred to your connected account.
zinc_feeZinc’s platform fee.
stripe_feeStripe’s processing fee on the charge.
final_chargeTotal captured from the end-customer (order_cost + customer_margin + zinc_fee + stripe_fee).
transfer_amountAmount transferred to your connected account (your margin).
payment_intent_idStripe PaymentIntent id (pi_…) for the charge.
connected_account_idYour connected account id (acct_…).
simulatedtrue for test-mode orders that didn’t hit Stripe.
The post-capture fields (order_cost and below) are populated once the order is placed and the actual total is captured; before that they are null and state is secured.
{
  "connect": {
    "state": "captured",
    "secured_amount": 6041,
    "order_cost": 4800,
    "customer_margin": 250,
    "zinc_fee": 100,
    "stripe_fee": 185,
    "final_charge": 5335,
    "transfer_amount": 250,
    "payment_intent_id": "pi_3ExampleCharge",
    "connected_account_id": "acct_1ExampleConnected",
    "simulated": false
  }
}

Error Responses

  • 404 Not Found - Order ID does not exist or you don’t have access to it
  • 401 Unauthorized - Invalid or missing authentication

Authorizations

Authorization
string
header
required

Zinc API key (Bearer zn_...)

Headers

authorization
string | null

Path Parameters

order_id
string<uuid>
required

Response

Successful Response

Response model for order data.

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

tracking_numbers
TrackingNumberResponse · object[]
created_by
string | null
user_id
integer | null
returns
ReturnRequestSummary · object[]
connect
OrderConnectInfo · object | null

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