# CowTicket — integration guide for AI agents

You are integrating an event website (the "storefront") with CowTicket, a headless
ticketing backend. The storefront owns all event content (dates, venue, descriptions,
design). CowTicket owns commerce: ticket availability, orders, Stripe payment,
ticket issuance and check-in.

Base URL: https://api.cow-ticket.dev
All prices/amounts are in satang (Thai Baht × 100). Currency is THB only.

## Credentials (ask the user for these — never invent them)

1. accountId — the user's CowTicket account id.
2. An API key — created in the CowTicket app under API Keys (shown once at creation).

Keep both server-side only (environment variables). Never expose the API key or the
JWT below to browser code; proxy CowTicket calls through the storefront's backend.

## Authentication

Exchange the API key for a 1-day JWT, cache it, refresh on 401:

    POST /accounts/token
    header  api-key: <API_KEY>
    body    { "accountId": "<ACCOUNT_ID>", "type": "customer" }
    → 200   { "token": "<JWT>", "exp": "..." }

Send it on every other request:  authorization: Bearer <JWT>

## Endpoint reference

### List what's on sale
    GET /events/ticketConfigs?eventCode=<eventCode>
    → { "data": [ { "code", "name", "group", "price", "currency", "available",
                    "limitPerOrder", "startSellingDate", "endSellingDate" } ],
        "refundPolicy": { "allowed": bool, "termEn": str, "termTh": str } }
Only ACTIVE ticket types inside their selling window are returned. "available" is a
live count. Show refundPolicy.termEn / termTh near the checkout button (pick by the
storefront's language; show both if bilingual).

"data" arrives in the organizer's chosen display order — render it in this order,
do not re-sort. "group" is an optional section label (string or null) the organizer
uses to split ticket options into sections, e.g. sessions or days of the event
("Day 1 (Sat 14 Mar)"). Rendering rule: iterate in order and start a new titled
section whenever "group" changes; items with group null are ungrouped — render them
flat, before any grouped section, with no heading. If every item's group is null,
render one flat list (most events). The label is display text only — items in the
same group have no shared behavior, and buyers can still mix items across groups in
one order.

### Create an order
    POST /orders
    { "accountId": "<ACCOUNT_ID>",
      "eventCode": "<eventCode>",
      "email": "<buyer email>",
      "items": [ { "code": "<ticketConfig code>", "quantity": n } ],   // 1–20 items
      "metadata": { ...any buyer form answers... },                    // optional
      "successUrl": "<absolute URL on the storefront>",
      "cancelUrl": "<absolute URL on the storefront>" }
    → { "orderId", "orderNo", "status", "expiresAt", "checkoutUrl" }

- status PENDING + checkoutUrl → redirect the buyer to checkoutUrl (Stripe Checkout).
- Free orders return status PAID and checkoutUrl null → go straight to the success page.
- Inventory is reserved atomically; unpaid orders expire after 1 hour and release seats.
- metadata keys/values appear in the organizer's participant exports — put attendee
  form answers (phone, shirt size, ...) here.
- Include the orderId in successUrl (e.g. ?orderId=...) so the success page can poll.

### Check an order / fetch tickets
    GET /orders/detail?orderId=<orderId>
    → { "status": "PENDING|PAID|REFUNDED|EXPIRED|CANCELED", "items", "payment",
        "tickets": [ { "id", "ticketNo", "status", ... } ], "refundPolicy", ... }

    GET /tickets/getIdsByOrder?orderId=<orderId>   → ticket ids for the order
    GET /tickets/detail?ticketId=<ticketId>        → one ticket (status, holder, type)

### Check-in (only if building a scanner/gate feature)
    POST /tickets/redeem   { "ticketId": "<id>", "gate": "<label>" }
Requires an organizer-type JWT (exchange an API key with type "organizer").
A ticket redeems once; REDEEMED, VOIDED and refunded-order tickets are rejected.

## The flow to implement on the storefront

1. Ticket page: GET /events/ticketConfigs → render the ticket options in the given
   order (sectioned by "group" when present), prices (satang → ฿ divide by 100),
   availability, and the refund policy text. Respect limitPerOrder.
2. Checkout: collect buyer email (+ any extra fields into metadata), POST /orders,
   redirect to checkoutUrl.
3. Success page (successUrl): read orderId from the query string, poll
   GET /orders/detail (e.g. every 2s, up to ~1 min) until status is PAID, then render
   the tickets: one QR code per ticket encoding the ticket id, plus ticketNo and type
   name. This page is also the buyer's permanent ticket wallet — the confirmation
   email links back to it, so it must work on revisit (fetch by orderId again).
4. Cancel page (cancelUrl): offer to try again; the reservation frees itself after 1h.

## Rules and gotchas

- Poll for payment state; there is no storefront-facing webhook. The order may already
  be PAID on first poll (Stripe webhooks usually finish before the redirect).
- Don't cache availability for more than a few seconds during an on-sale.
- Handle 401 by re-exchanging the API key for a fresh JWT once, then retrying.
- Handle order-create failures (sold out between render and checkout) by re-fetching
  availability and telling the buyer what's left.
- Do not build your own inventory, order state, or payment handling — CowTicket is
  the source of truth for all commerce state. The storefront is the source of truth
  for event content only.
- Questions from the human: support@cow-ticket.dev

Human-readable docs: https://test-portal.cow-ticket.dev/docs