Zinc Orders

Place and manage orders on online retailers through the Zinc API (

https://api.zinc.com

).

Prerequisites

• ZINC_API_KEY

  env var must be set. Get one from https://app.zinc.com.

Authentication

All requests use Bearer token auth:

Authorization: Bearer $ZINC_API_KEY

Endpoints

Create Order —

POST /orders

Place a new order. Orders process asynchronously.

Required fields:

• products

  — array of

  { url, quantity?, variant? }

  objects

  • url

    : direct product page URL on a supported retailer

  • quantity

    : integer (default 1)

  • variant

    : array of

    { label, value }

    for size/color/etc.

• shipping_address

  — object with

  first_name

  ,

  last_name

  ,

  address_line1

  ,

  address_line2

  ,

  city

  ,

  state

  (2-letter),

  postal_code

  ,

  phone_number

  ,

  country

  (ISO alpha-2, e.g. "US")

• max_price

  — integer, maximum price in cents

Optional fields:

• idempotency_key

  — string (max 36 chars) to prevent duplicates

• retailer_credentials_id

  — short ID like

  zn_acct_XXXXXXXX

• metadata

  — arbitrary key-value object

• po_number

  — purchase order number string

Response: order object with

id

(UUID),

status

,

items

,

shipping_address

,

created_at

,

tracking_numbers

, etc.

Order statuses:

pending

→

in_progress

→

order_placed

|

order_failed

|

cancelled

List Orders —

GET /orders

Returns

{ orders: [...] }

array of order objects.

Get Order —

GET /orders/{id}

Retrieve a single order by UUID.

Example: Place an Order

curl -X POST https://api.zinc.com/orders \
  -H "Authorization: Bearer $ZINC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [{ "url": "https://example.com/product", "quantity": 1 }],
    "max_price": 5000,
    "shipping_address": {
      "first_name": "Jane",
      "last_name": "Doe",
      "address_line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "phone_number": "5551234567",
      "country": "US"
    }
  }'

Error Handling

See references/errors.md for the full error code reference.

Key points:

• HTTP errors return

  { code, message, details }

• Order processing failures appear in webhook/order response as

  error_type

• Common issues:

  max_price_exceeded

  ,

  product_out_of_stock

  ,

  invalid_shipping_address

Order Status Tracking

Orders process asynchronously and typically take 5–10 minutes. After placing an order:

1. Schedule a cron job to check the order status ~7 minutes after creation.
2. Use

   GET /orders/{id}

   to poll.
3. Report the result back to the user in the same channel.
4. If still pending/in_progress, schedule another check in 5 minutes.

Terminal statuses:

order_placed

,

order_failed

,

cancelled

— stop polling. Non-terminal:

pending

,

in_progress

— schedule another check in 3–5 minutes.

Example cron job (isolated, announce back to the channel):

{
  "name": "zinc-order-check-<short_id>",
  "schedule": { "kind": "at", "at": "<ISO-8601 ~7min from now>" },
  "payload": {
    "kind": "agentTurn",
    "message": "Check Zinc order <order_id> via GET https://api.zinc.com/orders/<order_id>"
  },
  "sessionTarget": "isolated",
  "delivery": {
    "mode": "announce",
    "channel": "<channel>",
    "to": "<channel_id>"
  }
}

Safety

• Always confirm with the user before placing an order (

  POST /orders

  ). This spends real money.
• Reading orders (GET) is always safe.
• Validate that

  max_price

  is reasonable before submitting.