Skill: a5huynh/universal-checkout (version 1.0.1)

--- name: zinc-orders description: Place, list, and retrieve orders via the Zinc API (zinc.com). Use when the user wants to buy a product from an online retailer, check order status, list recent orders, or anything involving the Zinc e-commerce ordering API. Requires ZINC_API_KEY environment variable. --- # 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": "5551234567", "country": "US" } }' ``` ## Error Handling See [references/errors.md](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): ```json { "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.

path: references/errors.md
content: # Zinc API Error Reference

## HTTP Status Codes

| Code | Meaning |
|------|---------|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 402 | Payment Required |
| 403 | Forbidden |
| 404 | Not Found |
| 409 | Conflict (duplicate) |
| 422 | Validation error |
| 500 | Internal Server Error |
| 502 | Bad Gateway |

## Error Response Format

```json
{ "code": "error_code", "message": "Human-readable message", "details": { "field": "context" } }
```

## API Error Codes

### General
- `not_found` — Resource not found
- `validation_error` — Bad/missing parameter (check `details`)
- `bad_request` — Malformed request
- `already_exists` — Duplicate (e.g. idempotency key)
- `internal_error` — Server-side issue

### Authentication
- `unauthorized`, `forbidden`, `invalid_token`, `token_expired`

### Wallet & Payment
- `insufficient_funds` — Low wallet balance (details include `required`/`available` in cents)
- `payment_failed`, `payment_method_required`, `invalid_payment_method`

### Order Request
- `invalid_shipping_address` — Address validation failed
- `url_unreachable` — Product URL inaccessible
- `invalid_variant` — Variant not found
- `out_of_stock`, `shipping_unavailable`, `non_us_retailer`, `order_not_cancellable`

### External
- `external_service_error`

## Order Processing Error Types

These appear in `error_type` field on failed orders:

### Product
`product_not_found`, `product_out_of_stock`, `product_unavailable`, `invalid_product_url`, `product_variant_required`, `product_variant_unavailable`, `product_quantity_unavailable`

### Price
`max_price_exceeded`

### Cart & Checkout
`add_to_cart_failed`, `cart_empty`, `checkout_blocked`, `checkout_failed`

### Shipping
`shipping_address_invalid`, `shipping_unavailable`, `shipping_method_unavailable`

### Payment
`payment_declined`, `payment_method_invalid`, `payment_failed`

### Account
`login_failed`, `session_expired`, `account_locked`, `account_verification_required`

### Retailer
`retailer_unavailable`, `retailer_not_supported`, `retailer_rate_limited`

### Quantity
`quantity_limit_exceeded`, `order_limit_exceeded`


path: README.md
content: # 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`.

You can also set the API key through `~/.openclaw/openclaw.json` instead of an environment variable:

```json
{
  "skills": {
    "entries": {
      "zinc-orders": {
        "enabled": true,
        "env": { "ZINC_API_KEY": "your-api-key" }
      }
    }
  }
}
```

OpenClaw hot-reloads skills when `SKILL.md` changes, so no restart is needed after updates.

## Documentation

- [SKILL.md](SKILL.md) — Full endpoint details, field descriptions, examples, and safety guidelines
- [references/errors.md](references/errors.md) — HTTP status codes, API error codes, and order processing error types


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)