{
  "openapi": "3.0.3",
  "info": {
    "title": "Checkout Tax API",
    "version": "1.0.0",
    "description": "VAT & sales-tax rate lookup plus B2B reverse-charge decision for digital-goods sellers. Coverage: EU-27, UK, US (state-level), Canada, Australia. Guidance only, not legal advice. Rates last reviewed 2026-07."
  },
  "servers": [
    {
      "url": "https://checkout-tax-api.pages.dev"
    }
  ],
  "paths": {
    "/rate": {
      "get": {
        "summary": "Get the applicable tax rate for a jurisdiction",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ISO 3166-1 alpha-2 (e.g. DE, GB, US)"
          },
          {
            "name": "region",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "US state / CA province (e.g. CA, ON)"
          },
          {
            "name": "product_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "digital",
                "standard"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Rate result"
          },
          "400": {
            "description": "Invalid input"
          }
        }
      }
    },
    "/decide": {
      "post": {
        "summary": "Decide charge-VAT / reverse-charge / out-of-scope",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "seller_country",
                  "buyer_country"
                ],
                "properties": {
                  "seller_country": {
                    "type": "string",
                    "description": "Seller establishment (EU-27 or GB in v1)"
                  },
                  "buyer_country": {
                    "type": "string"
                  },
                  "buyer_vat_id": {
                    "type": "string",
                    "description": "Buyer VAT number (format-checked)"
                  },
                  "buyer_region": {
                    "type": "string"
                  },
                  "product_type": {
                    "type": "string",
                    "enum": [
                      "digital",
                      "standard"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Decision result"
          },
          "400": {
            "description": "Invalid input"
          }
        }
      }
    },
    "/health": {
      "get": {
        "summary": "Health check",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  }
}