universal-checkout（通用结帐）

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.