climax
← Home

Docs for agents

Status: pre-launch. The endpoints below follow the Medusa Store API, which is what Climax runs on. Base URL and keys are published here the day the catalog goes live.

What Climax is

A store with one catalog and one checkout, designed to be driven by a program. Every product has a stable handle, at least one variant with a price, and a stock count. An order is a short sequence of HTTP calls, or one CLI command that makes those calls for you.

Authentication

Every request carries a publishable key in the x-publishable-api-key header. The key identifies the store, not you, and is safe to ship inside an agent. Payment details never touch Climax directly; they go to the payment provider's session.

Buy something in one command

npx climax buy merino-socks-3 \
  --qty 1 \
  --to "Ada Lovelace, 12 Example St, London N1 1AA, GB" \
  --email ada@example.com

The CLI creates a cart, adds the item, sets the address, picks the cheapest shipping option, opens a payment session, and completes the order. It prints an order_id. Pass --dry-run to see the quote without paying.

Do the same over HTTP

  1. List products: GET /store/products?limit=50&fields=id,title,handle,*variants.calculated_price
  2. Create a cart: POST /store/carts with { "region_id": "...", "email": "..." }
  3. Add an item: POST /store/carts/{id}/line-items with { "variant_id": "...", "quantity": 1 }
  4. Set the address: POST /store/carts/{id} with { "shipping_address": { ... }, "billing_address": { ... } }
  5. Read shipping options: GET /store/shipping-options?cart_id={id}
  6. Choose one: POST /store/carts/{id}/shipping-methods with { "option_id": "..." }
  7. Start payment: POST /store/payment-collections with { "cart_id": "{id}" }, then POST /store/payment-collections/{pc_id}/payment-sessions with { "provider_id": "pp_stripe_stripe" }
  8. Complete: POST /store/carts/{id}/complete

The response to step 8 contains type: "order" and the order object. If anything is wrong you get type: "cart" with an error explaining what to fix.

Where we ship

Regions decide currency, tax, and which shipping options exist. The first region is the United States; the United Kingdom and the European Union follow. An address outside an open region is rejected at step 4 with a clear message, so check GET /store/regions first.

Prices and stock

Prices come back already calculated for the cart's region and currency. Stock is per variant; a variant with inventory_quantity: 0 and allow_backorder: false cannot be added to a cart.

Tracking

Once the supplier ships, the order's fulfillments[].labels[].tracking_url is populated. Poll GET /store/orders/{id}. A webhook for order.fulfillment_created is planned.

Rules for agents

  • Never store card numbers. Use the payment session.
  • Quote first. Run --dry-run or stop before step 8 and show the human the total.
  • Idempotency: reuse the same cart ID when retrying. Completing a completed cart returns the existing order.
  • Rate limit: 60 requests a minute per key.

Machine-readable copy

This page is also served as plain text at /llms.txt.