zinc-orders

# 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

```bash
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": "55512...

# Universal Checkout Skill

An [Agent Skill](https://agentskills.io) for placing and managing e-commerce orders through the [Zinc API](https://zinc.com). Enables AI agents to buy products from online retailers, check order statuses, and list recent orders on behalf of users.

## Project Structure

```
├── SKILL.md              # Skill definition (endpoints, auth, workflows)
└── references/
    └── errors.md         # Full error code and status reference
```

## Prerequisites

- A Zinc API key. Sign up at [app.zinc.com](https://app.zinc.com).
- `ZINC_API_KEY` environment variable must be set.

## Installation

This is an [Agent Skill](https://agentskills.io) — a folder containing a `SKILL.md` file with metadata and instructions that any compatible agent can discover and use. Agent Skills are supported by Claude Code, Cursor, Gemini CLI, VS Code, GitHub Copilot, and [many other agent products](https://agentskills.io/home).

Clone this repo into your project's `skills/` directory:

```bash
git clone https://github.com/zinc/universal-checkout-skill.git ./skills/universal-checkout-skill
```

Compatible agents automatically discover skills in the workspace `skills/` folder. Skills use progressive disclosure — at startup only the `name` and `description` are loaded, and the full instructions are read into context only when a matching task is detected.

### OpenClaw

[OpenClaw](https://docs.openclaw.ai) loads skills from three locations (highest priority first):

1. **Workspace** — `<workspace>/skills/`
2. **User** — `~/.openclaw/skills/`
3. **Bundled** — shipped with the installation

Install via [ClawHub](https://clawhub.ai/a5huynh/universal-checkout):

```bash
clawhub install a5huynh/universal-checkout
```

Or clone manually into either the workspace or user skill directory:

```bash
git clone https://github.com/zinc/universal-checkout-skill.git ~/.openclaw/skills/universal-checkout-skill
```

Additional skill directories can be configured via `skills.load.extraDirs`.

Y...