Catalog API AI integration
Make your first call in under two minutes, with curl, your AI assistant, or both.
Step 1: Prove your key works (30 seconds)
Drop your sandbox API key in and run this. If you get a JSON list of sockets back, you're wired up. Every other call builds from here.
curl -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \ https://api.catalogapi.com/sandbox/api/v2/sockets
You'll get back a list of catalog sockets your account can use. Grab a
socket_id
from the response. You'll need it for every catalog/cart/order call that follows.
Step 2: Let Claude Code do the rest (2 minutes)
Open your project in Claude Code , paste the prompt below into your first message, and let it scaffold your integration. It'll hit the OpenAPI spec, make real sandbox calls, and generate idiomatic code in whatever language your project is written in.
I'm integrating CatalogAPI v2 against the sandbox. Help me get a working end-to-end integration in whatever language this project is already written in.
Here's what you need to know. Before you do anything else, fetch the OpenAPI spec — it's the source of truth for every endpoint, parameter, and response shape:
https://api.catalogapi.com/api/v2/openapi-clean
AUTH
• API key in the Authorization header, sent as `Authorization: Bearer <key>`. I'll give you a sandbox API key.
• Sandbox calls go to https://api.catalogapi.com/sandbox/api/v2/*
• Production calls (NOT for this task) go to https://api.catalogapi.com/api/v2/*
CORE CONCEPTS
• Socket: a catalog scoped to one currency + region. Every cart is scoped to a socket.
• External User ID: my stable identifier for a user. It's how we key carts.
• Cart Version: an optimistic-locking token the API returns. Echo it back on cart mutations.
• Line Item ID: returned when you add items; use it to update or remove.
• Quantity: there is NO `quantity` field anywhere. Each unit is its own line item. POST /cart/items takes `{"items": [...]}` — to add three of the same catalog_item_id in one call, put three entries with that id in the array. The response has three distinct line_item_ids. To remove one of the three, delete a single line_item_id; the other two stay. A UI that shows "Qty: 3" should group identical catalog_item_ids client-side and map + / − controls to adding-one-entry / removing-one-line-item.
PLAN
1. Call GET /sockets to list what's available. Pick one socket_id to use for the demo.
2. Call GET /sockets/{socket_id}/items?search=... and show me one real product we can use.
3. Scaffold a small module in this project that:
a. Searches for items
b. Adds one to a cart (POST /sockets/{socket_id}/cart/items)
c. Sets a shipping address (PUT /sockets/{socket_id}/cart/address)
d. Validates the cart (POST /sockets/{socket_id}/cart/validate)
e. Places the order (POST /sockets/{socket_id}/cart/order)
4. Write ONE happy-path test against the sandbox that runs all five calls in sequence.
5. Show me how to run the test.
GROUND RULES
• Match this project's existing code style, test framework, and HTTP client. Read a few files first.
• Don't invent endpoints — if something isn't in the OpenAPI spec, ask me.
• Always call /cart/validate before /cart/order. The API will reject orders placed against stale prices.
• Handle 429 (rate limit) and 503 (transient) with exponential backoff. Don't retry other 4xx.
• Never log the API key.
I'll paste the sandbox API key in my next message. Start by reading the OpenAPI spec and this project's structure, then tell me the plan before you write code.
Don't have Claude Code set up? The same prompt works in Claude.ai, Cursor, Copilot Chat, or any assistant that can fetch URLs. They just won't be able to run the curl commands themselves, so you'll paste the output back.
Step 3: Build something real
Once the first call works, the rest of the API follows the same shape. Here's the mental model: four concepts and you've got the whole surface.
Sockets
A socket is a catalog scoped to a specific currency, region, and product set. Every cart and order is attached to one socket.
GET /sockets
lists them.
External User ID
Your own user identifier. We use it as the cart key so the same user keeps the same cart across sessions. Any stable string works.
Cart → Validate → Order
Add items with
POST /sockets/{id}/cart/items
, set an address, call
POST /cart/validate
to lock pricing and shipping, then
POST /cart/order
to submit. Always validate before ordering.
Sandbox vs. production
Sandbox API keys only work against
/sandbox/api/v2/*
. Production API keys only work against
/api/v2/*
. Orders placed in sandbox are never fulfilled, so test freely.