{
  "openapi": "3.0.3",
  "info": {
    "title": "Claude CMS agent payments",
    "version": "1.0",
    "description": "Get a human buyer to a payment page for a store built on Claude CMS. Simplest, for every assistant: add ?buy=1 to a product page URL (https://<store>/product/<handle>?buy=1), or compose https://<store>/checkout?buy=<handle>&qty=1, and hand it to the human — the GET below verifies it and returns the price. Agents that can POST may instead create a hosted Stripe payment page. The agent never handles card details; the buyer pays on Stripe's page and the money settles in the merchant's own Stripe account. Guide: https://claudecms.com/agents"
  },
  "servers": [
    {
      "url": "https://claudecms.com/api/agent"
    }
  ],
  "paths": {
    "/checkout": {
      "post": {
        "summary": "Create a payment page (or quote it with preview)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateRequest"
              },
              "examples": {
                "products": {
                  "summary": "Buy products by SKU",
                  "value": {
                    "store": "example.com",
                    "items": [
                      {
                        "sku": "SKU-12345",
                        "quantity": 1
                      }
                    ],
                    "buyer_email": "sam@example.com",
                    "shipping_country": "US",
                    "agent": "MyAssistant/2.1"
                  }
                },
                "amount": {
                  "summary": "A plain amount",
                  "value": {
                    "store": "example-store",
                    "amount_pence": 4500,
                    "description": "Consultation, 12 October",
                    "buyer_email": "sam@example.com",
                    "reference": "consult-2026-10-12-sam"
                  }
                },
                "preview": {
                  "summary": "Quote first, create nothing",
                  "value": {
                    "store": "example.com",
                    "items": [
                      {
                        "handle": "example-product",
                        "quantity": 2
                      }
                    ],
                    "preview": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Checkout"
                    }
                  }
                }
              }
            }
          },
          "200": {
            "description": "Preview quote, or an existing open link returned for the same reference",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Quote"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "502": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "get": {
        "summary": "Buy-link lookup: validate a store and product, get the buy link and the price. Creates nothing.",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "t",
            "in": "query",
            "description": "The token from the create response",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "store",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Store domain, Claude CMS store handle, or a product page URL (buy-link lookup)."
          },
          {
            "name": "handle",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Product handle — the last part of the product page URL (buy-link lookup)."
          },
          {
            "name": "sku",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Product SKU, instead of handle (buy-link lookup)."
          },
          {
            "name": "variant_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Variant id, instead of handle (buy-link lookup)."
          },
          {
            "name": "qty",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Quantity, 1-50 (buy-link lookup)."
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Two-letter shipping country for the preview (buy-link lookup)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Checkout"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        },
        "description": " With store= and handle= (or sku= / variant_id=) instead of id/t, the same GET validates the store and product with a preview and returns data.buy_link: a URL for the human that opens the store's own checkout with the item. Nothing is created. For assistants that can fetch URLs but cannot POST. Shortest form of the same link: the product page URL plus ?buy=1 (https://<store>/product/<handle>?buy=1), with the same variant= and qty= parameters."
      }
    }
  },
  "components": {
    "responses": {
      "Error": {
        "description": "Error",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                },
                "blockers": {
                  "type": "array",
                  "items": {
                    "type": "object"
                  }
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "Item": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string"
          },
          "handle": {
            "type": "string",
            "description": "Product handle (URL slug). Add variant when the product has several."
          },
          "variant": {
            "type": "string",
            "description": "Option text or SKU that picks one variant of a handle"
          },
          "variant_id": {
            "type": "integer"
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 999,
            "default": 1
          }
        }
      },
      "CreateRequest": {
        "type": "object",
        "required": [
          "store"
        ],
        "properties": {
          "store": {
            "type": "string",
            "description": "The merchant's website domain or Claude CMS store handle"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Item"
            },
            "description": "What to buy. Shipping and tax are added on the payment page from the store's own rates."
          },
          "amount_pence": {
            "type": "integer",
            "minimum": 100,
            "description": "Instead of items: the total to pay, in the store currency's minor unit (2500 = 25.00). Needs description."
          },
          "description": {
            "type": "string",
            "maxLength": 255
          },
          "buyer_email": {
            "type": "string",
            "format": "email"
          },
          "reference": {
            "type": "string",
            "maxLength": 80,
            "description": "Your own id for this payment; repeating it returns the same open link"
          },
          "shipping_country": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2; defaults to where the store ships"
          },
          "success_url": {
            "type": "string",
            "format": "uri"
          },
          "cancel_url": {
            "type": "string",
            "format": "uri"
          },
          "agent": {
            "type": "string",
            "maxLength": 120,
            "description": "Your name/version; shown to the merchant on the order"
          },
          "preview": {
            "type": "boolean",
            "description": "Validate and quote; create nothing"
          }
        }
      },
      "Quote": {
        "type": "object",
        "properties": {
          "preview": {
            "type": "boolean"
          },
          "ready": {
            "type": "boolean"
          },
          "blockers": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "kind": {
            "type": "string",
            "enum": [
              "items",
              "amount"
            ]
          },
          "amount_pence": {
            "type": "integer"
          },
          "currency": {
            "type": "string"
          },
          "lines": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "merchant": {
            "type": "object"
          },
          "shipping_country": {
            "type": "string",
            "nullable": true
          },
          "note": {
            "type": "string"
          }
        }
      },
      "Checkout": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "token": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "paid",
              "expired",
              "cancelled",
              "failed"
            ]
          },
          "kind": {
            "type": "string"
          },
          "checkout_url": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "Give this to the human. Single use; null once the link is no longer open."
          },
          "status_url": {
            "type": "string",
            "format": "uri"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "amount_pence": {
            "type": "integer"
          },
          "currency": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "lines": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "reference": {
            "type": "string",
            "nullable": true
          },
          "merchant": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "handle": {
                "type": "string"
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "paid_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "order_number": {
            "type": "string",
            "nullable": true
          },
          "reused": {
            "type": "boolean"
          }
        }
      }
    }
  }
}