{
  "name": "Claude CMS agent payments",
  "version": "1.0",
  "start_here": "https://claudecms.com/agents#playbook",
  "order_of_preference": [
    "buy_link",
    "buy_link_lookup",
    "create",
    "product page + Buy now"
  ],
  "buy_link": {
    "shortest": "https://<store>/product/<handle>?buy=1",
    "long": "https://<store>/checkout?buy=<handle>&qty=1",
    "params": "&variant=<id> for a product with several variants; &qty=<n> for more than one",
    "note": "Opens the store's own checkout with the item; nothing is created until the human pays. Product pages carry the long form as schema.org BuyAction and as the Buy now button."
  },
  "description": "Get a human buyer to a payment page for any store built on Claude CMS: add ?buy=1 to a product page URL, or compose a buy link from it (works for every assistant, no call), or create a hosted Stripe payment page through the API (agents that can POST). Money goes straight to the merchant's own Stripe account; no card details pass through.",
  "docs": "https://claudecms.com/agents",
  "llms_txt": "https://claudecms.com/llms.txt",
  "openapi": "https://claudecms.com/api/agent/openapi.json",
  "endpoints": {
    "buy_link": {
      "method": "GET",
      "url": "https://{store_domain}/checkout?buy={product_handle}&qty={quantity}",
      "note": "For agents that cannot POST: a link to hand to the human. It opens the store's own checkout with that product in the bag; add &variant={variant_id} for products with several variants. Nothing is created until the human pays."
    },
    "buy_link_lookup": {
      "method": "GET",
      "url": "https://claudecms.com/api/agent/checkout?store={store_domain}&handle={product_handle}&qty={quantity}",
      "note": "Also accepts sku= or variant_id= instead of handle=. Validates the store and product with a preview and returns data.buy_link, data.ready and data.amount_pence. Creates nothing — safe for assistants that can only fetch URLs."
    },
    "create": {
      "method": "POST",
      "url": "https://claudecms.com/api/agent/checkout"
    },
    "status": {
      "method": "GET",
      "url": "https://claudecms.com/api/agent/checkout?id={id}&t={token}"
    }
  },
  "auth": "none for agents (rate-limited per address, store and buyer); the merchant must have switched agent payments on for their store",
  "flow": [
    "Cannot POST? Add ?buy=1 to the product page URL (…/product/<handle>?buy=1) — or compose the long form …/checkout?buy=<handle>&qty=1 — and give it to the human. Done.",
    "Can fetch URLs but not POST? GET the buy_link_lookup URL and give the human data.buy_link.",
    "POST with preview:true to check the store is ready and see the quote.",
    "POST again without preview to get checkout_url (single use, expires in 24 hours).",
    "Give checkout_url to the human; they pay on Stripe's hosted page.",
    "GET status_url until status is paid; the merchant then has a normal order."
  ]
}