{
  "openapi": "3.1.0",
  "info": {
    "title": "BenchTill Custom Integration API",
    "version": "1.0.0",
    "description": "Server-to-server only. Bearer key required; POS cookies are ignored and any browser Origin is denied. Owner grants scopes and explicit shops. Keys remain valid only while the business licence and issuing owner are active. No financial, stock, payroll or repair-state writes. 120 requests/key/minute and 300 requests/source-IP/minute; counters retained for a bounded120-minute window. Optional key expiry is owner configured, up to365days; null has no automatic expiry. Never put keys in a browser, URL or public application. Read endpoints return saved values, not tax re-evaluation. Revocation/key creation are owner POS settings, outside this public API. Owner-configured outbound reference webhooks are described separately under webhooks; developer keys cannot register endpoints. The booking reference application is server-to-server and is not a hosted connector. Version 1 also offers an observational accessory availability feed and owner-reviewed catalogue mappings; these are not a native ecommerce connector."
  },
  "servers": [
    {
      "url": "https://www.benchtill.com"
    }
  ],
  "security": [
    {
      "BearerApiKey": []
    }
  ],
  "x-benchtill-scopes": [
    {
      "name": "stores.read",
      "description": "Read approved active shops and public contact details."
    },
    {
      "name": "customers.read",
      "description": "Read contact information attributable to an approved shop."
    },
    {
      "name": "customers.write",
      "description": "Create contacts and update only contacts whose every affected shop is approved."
    },
    {
      "name": "inventory.read",
      "description": "Read listed products and used-device asking prices/status, excluding internal costs."
    },
    {
      "name": "sales.read",
      "description": "Read signed saved receipt amounts, item snapshots, refunds and void state."
    },
    {
      "name": "repairs.read",
      "description": "Read ticket references, public stages and customer-price summaries, excluding private notes."
    },
    {
      "name": "orders.read",
      "description": "Read order headers and item quantities, excluding supplier credentials and costs."
    },
    {
      "name": "appointments.read",
      "description": "Read booking contact details, services and server-calculated availability."
    },
    {
      "name": "appointments.write",
      "description": "Create appointments using saved shop services, timezone and capacity rules."
    }
  ],
  "paths": {
    "/integrations/v1/me": {
      "get": {
        "summary": "Inspect the authenticated integration key and business context",
        "x-benchtill-scopes": [],
        "responses": {
          "200": {
            "description": "Current authorised result. Reads can change between requests; pagination is not a global database snapshot.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/v1/stores": {
      "get": {
        "summary": "List only approved active shops (maximum100 approved per key)",
        "x-benchtill-scopes": [
          "stores.read"
        ],
        "responses": {
          "200": {
            "description": "Current authorised result. Reads can change between requests; pagination is not a global database snapshot.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoreList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/v1/stores/{id}": {
      "get": {
        "summary": "Read one approved active shop",
        "x-benchtill-scopes": [
          "stores.read"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Must equal storeId query."
          }
        ],
        "responses": {
          "200": {
            "description": "Current authorised result. Reads can change between requests; pagination is not a global database snapshot.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StoreResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/v1/customers": {
      "get": {
        "summary": "List approved-shop customers",
        "description": "ID-ordered cursor pagination. Pages are live reads, not a consistent multi-page snapshot. Re-scan to reconcile; this is not a complete change stream.",
        "x-benchtill-scopes": [
          "customers.read"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            },
            "description": ""
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 2000
            },
            "description": "Opaque signed nextCursor. Repeat the exact key, shop, filters and limit."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "description": "Case-insensitive saved display-field search; not fuzzy phone identity matching."
          },
          {
            "name": "createdAfter",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          },
          {
            "name": "createdBefore",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          }
        ],
        "responses": {
          "200": {
            "description": "Current authorised result. Reads can change between requests; pagination is not a global database snapshot.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Post Customer",
        "x-benchtill-scopes": [
          "customers.write"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Keep this UUID and normalized body unchanged through unknown outcomes. Namespace is the API key, method, resource and shop."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCustomer"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Saved result. Identical authorized retries return the same data with replayed:true.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/v1/customers/{id}": {
      "get": {
        "summary": "Read one approved-shop customer",
        "x-benchtill-scopes": [
          "customers.read"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "createdAfter",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          },
          {
            "name": "createdBefore",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          }
        ],
        "responses": {
          "200": {
            "description": "Current authorised result. Reads can change between requests; pagination is not a global database snapshot.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Patch Customer",
        "x-benchtill-scopes": [
          "customers.write"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Keep this UUID and normalized body unchanged through unknown outcomes. Namespace is the API key, method, resource and shop."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateCustomer"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved result. Identical authorized retries return the same data with replayed:true.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/v1/inventory": {
      "get": {
        "summary": "List approved-shop inventory",
        "description": "ID-ordered cursor pagination. Pages are live reads, not a consistent multi-page snapshot. Re-scan to reconcile; this is not a complete change stream. Raw quantity remains stock on hand, not available-to-sell stock. Customer reservation and exchange holds are not deducted. The separate inventory-availability resource reports supported advisory availability.",
        "x-benchtill-scopes": [
          "inventory.read"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            },
            "description": ""
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 2000
            },
            "description": "Opaque signed nextCursor. Repeat the exact key, shop, filters and limit."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "description": "Case-insensitive saved display-field search; not fuzzy phone identity matching."
          }
        ],
        "responses": {
          "200": {
            "description": "Current authorised result. Reads can change between requests; pagination is not a global database snapshot.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/v1/inventory/{id}": {
      "get": {
        "summary": "Read one approved-shop inventory",
        "x-benchtill-scopes": [
          "inventory.read"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current authorised result. Reads can change between requests; pagination is not a global database snapshot.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Raw quantity remains stock on hand, not available-to-sell stock. Customer reservation and exchange holds are not deducted. The separate inventory-availability resource reports supported advisory availability."
      }
    },
    "/integrations/v1/used-devices": {
      "get": {
        "summary": "List approved-shop used-devices",
        "description": "ID-ordered cursor pagination. Pages are live reads, not a consistent multi-page snapshot. Re-scan to reconcile; this is not a complete change stream.",
        "x-benchtill-scopes": [
          "inventory.read"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            },
            "description": ""
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 2000
            },
            "description": "Opaque signed nextCursor. Repeat the exact key, shop, filters and limit."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "description": "Case-insensitive saved display-field search; not fuzzy phone identity matching."
          },
          {
            "name": "createdAfter",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          },
          {
            "name": "createdBefore",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          }
        ],
        "responses": {
          "200": {
            "description": "Current authorised result. Reads can change between requests; pagination is not a global database snapshot.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsedDeviceList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/v1/used-devices/{id}": {
      "get": {
        "summary": "Read one approved-shop useddevice",
        "x-benchtill-scopes": [
          "inventory.read"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "createdAfter",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          },
          {
            "name": "createdBefore",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          }
        ],
        "responses": {
          "200": {
            "description": "Current authorised result. Reads can change between requests; pagination is not a global database snapshot.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsedDeviceResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/v1/sales": {
      "get": {
        "summary": "List approved-shop sales",
        "description": "ID-ordered cursor pagination. Pages are live reads, not a consistent multi-page snapshot. Re-scan to reconcile; this is not a complete change stream.",
        "x-benchtill-scopes": [
          "sales.read"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            },
            "description": ""
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 2000
            },
            "description": "Opaque signed nextCursor. Repeat the exact key, shop, filters and limit."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "description": "Case-insensitive saved display-field search; not fuzzy phone identity matching."
          },
          {
            "name": "createdAfter",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          },
          {
            "name": "createdBefore",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          }
        ],
        "responses": {
          "200": {
            "description": "Current authorised result. Reads can change between requests; pagination is not a global database snapshot.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SaleList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/v1/sales/{id}": {
      "get": {
        "summary": "Read one approved-shop sale",
        "x-benchtill-scopes": [
          "sales.read"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "createdAfter",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          },
          {
            "name": "createdBefore",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          }
        ],
        "responses": {
          "200": {
            "description": "Current authorised result. Reads can change between requests; pagination is not a global database snapshot.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SaleResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/v1/repairs": {
      "get": {
        "summary": "List approved-shop repairs",
        "description": "ID-ordered cursor pagination. Pages are live reads, not a consistent multi-page snapshot. Re-scan to reconcile; this is not a complete change stream.",
        "x-benchtill-scopes": [
          "repairs.read"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            },
            "description": ""
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 2000
            },
            "description": "Opaque signed nextCursor. Repeat the exact key, shop, filters and limit."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "description": "Case-insensitive saved display-field search; not fuzzy phone identity matching."
          },
          {
            "name": "createdAfter",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          },
          {
            "name": "createdBefore",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          }
        ],
        "responses": {
          "200": {
            "description": "Current authorised result. Reads can change between requests; pagination is not a global database snapshot.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RepairList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/v1/repairs/{id}": {
      "get": {
        "summary": "Read one approved-shop repair",
        "x-benchtill-scopes": [
          "repairs.read"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "createdAfter",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          },
          {
            "name": "createdBefore",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          }
        ],
        "responses": {
          "200": {
            "description": "Current authorised result. Reads can change between requests; pagination is not a global database snapshot.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RepairResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/v1/orders": {
      "get": {
        "summary": "List approved-shop orders",
        "description": "ID-ordered cursor pagination. Pages are live reads, not a consistent multi-page snapshot. Re-scan to reconcile; this is not a complete change stream.",
        "x-benchtill-scopes": [
          "orders.read"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            },
            "description": ""
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 2000
            },
            "description": "Opaque signed nextCursor. Repeat the exact key, shop, filters and limit."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "description": "Case-insensitive saved display-field search; not fuzzy phone identity matching."
          },
          {
            "name": "createdAfter",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          },
          {
            "name": "createdBefore",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          }
        ],
        "responses": {
          "200": {
            "description": "Current authorised result. Reads can change between requests; pagination is not a global database snapshot.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/v1/orders/{id}": {
      "get": {
        "summary": "Read one approved-shop order",
        "x-benchtill-scopes": [
          "orders.read"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "createdAfter",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          },
          {
            "name": "createdBefore",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          }
        ],
        "responses": {
          "200": {
            "description": "Current authorised result. Reads can change between requests; pagination is not a global database snapshot.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/v1/appointments": {
      "get": {
        "summary": "List approved-shop appointments",
        "description": "ID-ordered cursor pagination. Pages are live reads, not a consistent multi-page snapshot. Re-scan to reconcile; this is not a complete change stream.",
        "x-benchtill-scopes": [
          "appointments.read"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            },
            "description": ""
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 2000
            },
            "description": "Opaque signed nextCursor. Repeat the exact key, shop, filters and limit."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "description": "Case-insensitive saved display-field search; not fuzzy phone identity matching."
          },
          {
            "name": "createdAfter",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          },
          {
            "name": "createdBefore",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          },
          {
            "name": "updatedSince",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Actual appointment updated_at filter; not a universal event/change stream."
          }
        ],
        "responses": {
          "200": {
            "description": "Current authorised result. Reads can change between requests; pagination is not a global database snapshot.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AppointmentList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Post Appointment",
        "x-benchtill-scopes": [
          "appointments.write"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Keep this UUID and normalized body unchanged through unknown outcomes. Namespace is the API key, method, resource and shop."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAppointment"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Saved result. Identical authorized retries return the same data with replayed:true.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AppointmentResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/v1/appointments/{id}": {
      "get": {
        "summary": "Read one approved-shop appointment",
        "x-benchtill-scopes": [
          "appointments.read"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "createdAfter",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          },
          {
            "name": "createdBefore",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "UTC ISO timestamp ending in Z; inclusive after, exclusive before."
          },
          {
            "name": "updatedSince",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Actual appointment updated_at filter; not a universal event/change stream."
          }
        ],
        "responses": {
          "200": {
            "description": "Current authorised result. Reads can change between requests; pagination is not a global database snapshot.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AppointmentResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/v1/appointments/services": {
      "get": {
        "summary": "Read available saved services",
        "description": "Requires either appointments.read or appointments.write. No booking/customer data returned.",
        "x-benchtill-scopes": [
          "appointments.read",
          "appointments.write"
        ],
        "x-benchtill-scope-mode": "any",
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "displayAt",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time",
              "maxLength": 24,
              "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:00(?:\\.000)?Z$"
            },
            "description": "One optional scalar valid-calendar minute-aligned UTC instant for display of an existing saved website intent/result. It does not inspect bookings or change booking authority; response display.at is canonical UTC and local is server-derived. Duplicate, array, non-minute and invalid dates are rejected."
          }
        ],
        "responses": {
          "200": {
            "description": "Current authorised result. Reads can change between requests; pagination is not a global database snapshot.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServicesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/v1/appointments/availability": {
      "get": {
        "summary": "Read server-calculated shop slots",
        "description": "Requires either appointments.read or appointments.write. Does not hold a slot or expose another customer.",
        "x-benchtill-scopes": [
          "appointments.read",
          "appointments.write"
        ],
        "x-benchtill-scope-mode": "any",
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "serviceId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "date",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Shop-local calendar date."
          }
        ],
        "responses": {
          "200": {
            "description": "Current authorised result. Reads can change between requests; pagination is not a global database snapshot.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AvailabilityResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/v1/inventory-availability": {
      "get": {
        "summary": "List observed accessory availability",
        "description": "Eligible products are active, listed Accessories without any purchase-receipt serial history (including released serial history at any store), a special-order product flag, or active same-store repair special orders. Devices, serialized stock, bundles, parts and other categories are unsupported. Conservative exclusions may omit otherwise ordinary units. Observational stock only: this feed does not reserve inventory, accept orders, synchronize a channel or prevent overselling. Quantity can change immediately. Re-read before use; multiple mappings do not allocate separate stock pools. ID-ordered keyset pagination; every page is a current read, not a global snapshot. Re-scan all pages to reconcile changes; no inventory-change webhook is emitted.",
        "x-benchtill-scopes": [
          "inventory.read"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            },
            "description": ""
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 2000
            },
            "description": "Opaque signed nextCursor. Repeat the exact key, shop, filters and limit."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "description": "Case-insensitive name, internal SKU or store display-name search."
          }
        ],
        "responses": {
          "200": {
            "description": "Current read-only observation. No reservation, order, payment, stock write or provider request occurs.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryAvailabilityList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/v1/inventory-availability/{id}": {
      "get": {
        "summary": "Read one observed accessory availability",
        "x-benchtill-scopes": [
          "inventory.read"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current read-only observation. No reservation, order, payment, stock write or provider request occurs.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryAvailabilityResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Eligible products are active, listed Accessories without any purchase-receipt serial history (including released serial history at any store), a special-order product flag, or active same-store repair special orders. Devices, serialized stock, bundles, parts and other categories are unsupported. Conservative exclusions may omit otherwise ordinary units. Observational stock only: this feed does not reserve inventory, accept orders, synchronize a channel or prevent overselling. Quantity can change immediately. Re-read before use; multiple mappings do not allocate separate stock pools."
      }
    },
    "/integrations/v1/catalogue-mappings": {
      "get": {
        "summary": "List reviewed catalogue mappings",
        "description": "Eligible products are active, listed Accessories without any purchase-receipt serial history (including released serial history at any store), a special-order product flag, or active same-store repair special orders. Devices, serialized stock, bundles, parts and other categories are unsupported. Conservative exclusions may omit otherwise ordinary units. Observational stock only: this feed does not reserve inventory, accept orders, synchronize a channel or prevent overselling. Quantity can change immediately. Re-read before use; multiple mappings do not allocate separate stock pools. ID-ordered keyset pagination; every page is a current read, not a global snapshot. Re-scan all pages to reconcile changes; no inventory-change webhook is emitted. Owners save these links in Tools \u2192 Catalogue mapping. Default status=all includes retired/unavailable records with zero mapping availability. Integrations must process those records to unpublish; active-only queries do not supply retirement notices. Developer keys cannot create/retire mappings.",
        "x-benchtill-scopes": [
          "inventory.read"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            },
            "description": ""
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 2000
            },
            "description": "Opaque signed nextCursor. Repeat the exact key, shop, filters and limit."
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "description": "Case-insensitive account label, external reference or external SKU search."
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "active",
                "retired"
              ],
              "default": "all"
            },
            "description": "Use all for synchronization so retirement/unavailability is not silently omitted."
          }
        ],
        "responses": {
          "200": {
            "description": "Current read-only observation. No reservation, order, payment, stock write or provider request occurs.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogueMappingList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/integrations/v1/catalogue-mappings/{id}": {
      "get": {
        "summary": "Read one reviewed catalogue mappings",
        "x-benchtill-scopes": [
          "inventory.read"
        ],
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "One explicitly key-approved, currently active shop. Body storeId, when supplied, must be an integer matching this query."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "active",
                "retired"
              ],
              "default": "all"
            },
            "description": "Use all for synchronization so retirement/unavailability is not silently omitted."
          }
        ],
        "responses": {
          "200": {
            "description": "Current read-only observation. No reservation, order, payment, stock write or provider request occurs.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-store"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogueMappingResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid scalar query, body or identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired or revoked Bearer key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Business licence expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope/shop, unavailable owner/business, or browser Origin present.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource not found within the approved shop.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Changed idempotent intent or existing/capacity conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON body larger than 16 KiB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON content type required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Durable key/IP rate limit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                },
                "description": "Seconds until the next rate window."
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; retain the original idempotent intent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Eligible products are active, listed Accessories without any purchase-receipt serial history (including released serial history at any store), a special-order product flag, or active same-store repair special orders. Devices, serialized stock, bundles, parts and other categories are unsupported. Conservative exclusions may omit otherwise ordinary units. Observational stock only: this feed does not reserve inventory, accept orders, synchronize a channel or prevent overselling. Quantity can change immediately. Re-read before use; multiple mappings do not allocate separate stock pools. Owners save these links in Tools \u2192 Catalogue mapping. Default status=all includes retired/unavailable records with zero mapping availability. Integrations must process those records to unpublish; active-only queries do not supply retirement notices. Developer keys cannot create/retire mappings."
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "bt_api_<43 base64url characters>"
      },
      "BenchTillWebhookSignature": {
        "type": "apiKey",
        "in": "header",
        "name": "X-BenchTill-Signature",
        "description": "Receiver authentication, not a developer API key. v1=hex HMAC-SHA256 using the full endpoint signing secret over timestamp + dot + exact raw request body. Verify timestamp within 300 seconds, use constant-time comparison and bind business/store before parsing/processing. See quickstart."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "requestId": {
            "type": "string",
            "format": "uuid"
          }
        },
        "required": [
          "error",
          "code",
          "requestId"
        ]
      },
      "TaxPolicy": {
        "type": [
          "object",
          "null"
        ],
        "additionalProperties": false,
        "properties": {
          "country": {
            "type": [
              "string",
              "null"
            ]
          },
          "currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "province": {
            "type": [
              "string",
              "null"
            ]
          },
          "localityScope": {
            "type": [
              "string",
              "null"
            ]
          },
          "policyVersion": {
            "type": [
              "string",
              "null"
            ]
          },
          "timezone": {
            "type": [
              "string",
              "null"
            ]
          },
          "gstNumber": {
            "type": [
              "string",
              "null"
            ]
          },
          "provincialTaxNumber": {
            "type": [
              "string",
              "null"
            ]
          },
          "gstLabel": {
            "type": [
              "string",
              "null"
            ]
          },
          "pstLabel": {
            "type": [
              "string",
              "null"
            ]
          },
          "vatRegistrationNumber": {
            "type": [
              "string",
              "null"
            ]
          },
          "pricesIncludeTax": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "pricesIncludeVat": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "vatRegistered": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "gstRegistered": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "provincialTaxRegistered": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "hasMarginItems": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "vatRate": {
            "type": [
              "number",
              "null"
            ]
          },
          "gstRate": {
            "type": [
              "number",
              "null"
            ]
          },
          "pstRate": {
            "type": [
              "number",
              "null"
            ]
          },
          "gstNumerator": {
            "type": [
              "number",
              "null"
            ]
          },
          "pstNumerator": {
            "type": [
              "number",
              "null"
            ]
          },
          "rateDenominator": {
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [],
        "description": "Only fields frozen on the saved transaction. UK inclusive metadata is reconstructed solely from saved header/line fields. Missing registration or legacy rates stay null."
      },
      "Store": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1
          },
          "name": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "active": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "name",
          "address",
          "phone",
          "active"
        ]
      },
      "Customer": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1
          },
          "name": {
            "type": "string"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "address": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "lastVisit": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "name",
          "phone",
          "email",
          "address",
          "createdAt",
          "lastVisit"
        ]
      },
      "Inventory": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "sku": {
            "type": [
              "string",
              "null"
            ]
          },
          "barcode": {
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "subcategory": {
            "type": [
              "string",
              "null"
            ]
          },
          "priceMinor": {
            "type": "integer",
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "currency": {
            "type": "string"
          },
          "quantity": {
            "type": "integer",
            "description": "Raw saved stock on hand. This field is unchanged and does not subtract customer reservation or exchange checkout holds. Use inventory-availability.availableQuantity for the supported observational subset."
          },
          "minimumQuantity": {
            "type": [
              "integer",
              "null"
            ]
          },
          "maximumQuantity": {
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "storeId",
          "sku",
          "barcode",
          "name",
          "category",
          "subcategory",
          "priceMinor",
          "currency",
          "quantity",
          "minimumQuantity",
          "maximumQuantity"
        ]
      },
      "UsedDevice": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "model": {
            "type": "string"
          },
          "storage": {
            "type": [
              "string",
              "null"
            ]
          },
          "color": {
            "type": [
              "string",
              "null"
            ]
          },
          "grade": {
            "type": "string",
            "enum": [
              "New",
              "A",
              "B",
              "C",
              "D"
            ]
          },
          "deviceType": {
            "type": "string",
            "enum": [
              "phone",
              "tablet",
              "other"
            ]
          },
          "status": {
            "type": "string"
          },
          "askingPriceMinor": {
            "type": "integer",
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "currency": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "storeId",
          "model",
          "storage",
          "color",
          "grade",
          "deviceType",
          "status",
          "askingPriceMinor",
          "currency",
          "createdAt"
        ]
      },
      "SaleItem": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1
          },
          "productId": {
            "type": [
              "integer",
              "null"
            ]
          },
          "description": {
            "type": "string"
          },
          "descriptionRedacted": {
            "type": "boolean"
          },
          "category": {
            "type": "string"
          },
          "quantity": {
            "type": "integer"
          },
          "unitPriceDecimal": {
            "type": "string",
            "pattern": "^-?\\d+(?:\\.\\d+)?$",
            "description": "Exact saved unit price decimal; UK net unit prices can include fractional pennies. Use saved line net/gross totals for accounting."
          },
          "netAfterDiscountMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "grossAfterDiscountMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "gstMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "pstMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "taxMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "taxTreatment": {
            "type": [
              "string",
              "null"
            ]
          },
          "taxPolicy": {
            "$ref": "#/components/schemas/TaxPolicy"
          },
          "taxSnapshotAvailable": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "productId",
          "description",
          "descriptionRedacted",
          "category",
          "quantity",
          "unitPriceDecimal",
          "netAfterDiscountMinor",
          "grossAfterDiscountMinor",
          "gstMinor",
          "pstMinor",
          "taxMinor",
          "taxTreatment",
          "taxPolicy",
          "taxSnapshotAvailable"
        ]
      },
      "Payment": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "method": {
            "type": "string"
          },
          "amountMinor": {
            "type": "integer",
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "method",
          "amountMinor"
        ]
      },
      "Sale": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1
          },
          "receiptNumber": {
            "type": "string"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "transactionKind": {
            "type": "string"
          },
          "refundOf": {
            "type": [
              "integer",
              "null"
            ]
          },
          "voided": {
            "type": "boolean"
          },
          "paymentMethod": {
            "type": "string"
          },
          "currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "taxPolicy": {
            "$ref": "#/components/schemas/TaxPolicy"
          },
          "taxSnapshotAvailable": {
            "type": "boolean"
          },
          "taxSnapshotKind": {
            "type": "string",
            "enum": [
              "policy",
              "uk_inclusive",
              "legacy_unknown"
            ]
          },
          "pricesIncludeTax": {
            "type": "boolean"
          },
          "subtotalMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "discountMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "gstMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "pstMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "taxMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "totalMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "recordedTotalMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Signed receipt total including exchange credit where recorded.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "actualTenderTotalMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Signed saved tenders excluding exchange_credit, including store_credit redemption. This is not new cash only.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "recognizedGoodsTotalMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Saved collection physical-line gross; deposit/gift liabilities are zero. Void state must still be respected; this field is not a complete accounts ledger.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "appliedDepositMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "id",
          "receiptNumber",
          "storeId",
          "createdAt",
          "transactionKind",
          "refundOf",
          "voided",
          "paymentMethod",
          "currency",
          "taxPolicy",
          "taxSnapshotAvailable",
          "taxSnapshotKind",
          "pricesIncludeTax",
          "subtotalMinor",
          "discountMinor",
          "gstMinor",
          "pstMinor",
          "taxMinor",
          "totalMinor",
          "recordedTotalMinor",
          "actualTenderTotalMinor",
          "recognizedGoodsTotalMinor",
          "appliedDepositMinor"
        ]
      },
      "SaleDetail": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1
          },
          "receiptNumber": {
            "type": "string"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "transactionKind": {
            "type": "string"
          },
          "refundOf": {
            "type": [
              "integer",
              "null"
            ]
          },
          "voided": {
            "type": "boolean"
          },
          "paymentMethod": {
            "type": "string"
          },
          "currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "taxPolicy": {
            "$ref": "#/components/schemas/TaxPolicy"
          },
          "taxSnapshotAvailable": {
            "type": "boolean"
          },
          "taxSnapshotKind": {
            "type": "string",
            "enum": [
              "policy",
              "uk_inclusive",
              "legacy_unknown"
            ]
          },
          "pricesIncludeTax": {
            "type": "boolean"
          },
          "subtotalMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "discountMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "gstMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "pstMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "taxMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "totalMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "recordedTotalMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Signed receipt total including exchange credit where recorded.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "actualTenderTotalMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Signed saved tenders excluding exchange_credit, including store_credit redemption. This is not new cash only.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "recognizedGoodsTotalMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Saved collection physical-line gross; deposit/gift liabilities are zero. Void state must still be respected; this field is not a complete accounts ledger.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "appliedDepositMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SaleItem"
            }
          },
          "payments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Payment"
            }
          }
        },
        "required": [
          "id",
          "receiptNumber",
          "storeId",
          "createdAt",
          "transactionKind",
          "refundOf",
          "voided",
          "paymentMethod",
          "currency",
          "taxPolicy",
          "taxSnapshotAvailable",
          "taxSnapshotKind",
          "pricesIncludeTax",
          "subtotalMinor",
          "discountMinor",
          "gstMinor",
          "pstMinor",
          "taxMinor",
          "totalMinor",
          "recordedTotalMinor",
          "actualTenderTotalMinor",
          "recognizedGoodsTotalMinor",
          "appliedDepositMinor",
          "items",
          "payments"
        ]
      },
      "Repair": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1
          },
          "reference": {
            "type": "string"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "customerId": {
            "type": [
              "integer",
              "null"
            ]
          },
          "device": {
            "type": "string"
          },
          "issueType": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "warranty": {
            "type": "boolean"
          },
          "quoteMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "depositMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "extraChargeMinor": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact signed saved amount in hundredths of the stated currency; null means unavailable, never recomputed.",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "taxPolicy": {
            "$ref": "#/components/schemas/TaxPolicy"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "statusUpdatedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "reference",
          "storeId",
          "customerId",
          "device",
          "issueType",
          "status",
          "warranty",
          "quoteMinor",
          "depositMinor",
          "extraChargeMinor",
          "currency",
          "taxPolicy",
          "createdAt",
          "statusUpdatedAt"
        ]
      },
      "Order": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "reference": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "supplierOrderReference": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "receivedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "closedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "storeId",
          "reference",
          "status",
          "supplierOrderReference",
          "createdAt",
          "receivedAt",
          "closedAt"
        ]
      },
      "OrderItem": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1
          },
          "productId": {
            "type": "integer",
            "minimum": 1
          },
          "name": {
            "type": "string"
          },
          "supplierSku": {
            "type": [
              "string",
              "null"
            ]
          },
          "sku": {
            "type": [
              "string",
              "null"
            ]
          },
          "barcode": {
            "type": [
              "string",
              "null"
            ]
          },
          "orderedQuantity": {
            "type": "integer"
          },
          "receivedQuantity": {
            "type": "integer"
          },
          "closedQuantity": {
            "type": "integer"
          },
          "outstandingQuantity": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "productId",
          "name",
          "supplierSku",
          "sku",
          "barcode",
          "orderedQuantity",
          "receivedQuantity",
          "closedQuantity",
          "outstandingQuantity"
        ]
      },
      "OrderDetail": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "reference": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "supplierOrderReference": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "receivedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "closedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderItem"
            }
          }
        },
        "required": [
          "id",
          "storeId",
          "reference",
          "status",
          "supplierOrderReference",
          "createdAt",
          "receivedAt",
          "closedAt",
          "items"
        ]
      },
      "Service": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "durationMinutes": {
            "type": "integer",
            "minimum": 15,
            "maximum": 240
          },
          "active": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "name",
          "durationMinutes",
          "active"
        ]
      },
      "SavedService": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "durationMinutes": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "name",
          "durationMinutes"
        ]
      },
      "Appointment": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "reference": {
            "type": "string"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "status": {
            "type": "string",
            "enum": [
              "confirmed",
              "arrived",
              "completed",
              "cancelled",
              "no_show"
            ]
          },
          "version": {
            "type": "integer",
            "minimum": 1
          },
          "service": {
            "$ref": "#/components/schemas/SavedService"
          },
          "startAt": {
            "type": "string",
            "format": "date-time"
          },
          "endAt": {
            "type": "string",
            "format": "date-time"
          },
          "customerName": {
            "type": "string"
          },
          "customerPhone": {
            "type": "string"
          },
          "customerEmail": {
            "type": [
              "string",
              "null"
            ]
          },
          "device": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "reference",
          "storeId",
          "status",
          "version",
          "service",
          "startAt",
          "endAt",
          "customerName",
          "customerPhone",
          "customerEmail",
          "device",
          "createdAt"
        ]
      },
      "Me": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "apiVersion": {
            "type": "string",
            "const": "1"
          },
          "keyId": {
            "type": "string",
            "format": "uuid"
          },
          "label": {
            "type": "string"
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "stores.read",
                "customers.read",
                "customers.write",
                "inventory.read",
                "sales.read",
                "repairs.read",
                "orders.read",
                "appointments.read",
                "appointments.write"
              ]
            }
          },
          "storeIds": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 1
            }
          },
          "expiresAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "businessId": {
            "type": "string",
            "format": "uuid"
          },
          "country": {
            "type": "string",
            "enum": [
              "GB",
              "CA"
            ]
          },
          "currency": {
            "type": "string",
            "enum": [
              "GBP",
              "CAD"
            ]
          },
          "timeZone": {
            "type": "string"
          }
        },
        "required": [
          "apiVersion",
          "keyId",
          "label",
          "scopes",
          "storeIds",
          "expiresAt",
          "businessId",
          "country",
          "currency",
          "timeZone"
        ]
      },
      "CreateCustomer": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "phone": {
            "type": "string",
            "minLength": 8,
            "maxLength": 40,
            "description": "Exact local or international phone, normalized using the saved business country."
          },
          "email": {
            "type": "string",
            "maxLength": 254,
            "description": "Valid email or empty string to remove it."
          },
          "address": {
            "type": "string",
            "maxLength": 500
          }
        },
        "required": [
          "name",
          "phone"
        ]
      },
      "UpdateCustomer": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "phone": {
            "type": "string",
            "minLength": 8,
            "maxLength": 40,
            "description": "Exact local or international phone, normalized using the saved business country."
          },
          "email": {
            "type": "string",
            "maxLength": 254,
            "description": "Valid email or empty string to remove it."
          },
          "address": {
            "type": "string",
            "maxLength": 500
          }
        },
        "required": [],
        "anyOf": [
          {
            "required": [
              "name"
            ]
          },
          {
            "required": [
              "phone"
            ]
          },
          {
            "required": [
              "email"
            ]
          },
          {
            "required": [
              "address"
            ]
          }
        ]
      },
      "CreateAppointment": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "serviceId": {
            "type": "string",
            "format": "uuid"
          },
          "startAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:00(?:\\.000)?Z$",
            "description": "Use startAt returned by availability unchanged: an exact minute-aligned UTC slot."
          },
          "customerName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "customerPhone": {
            "type": "string",
            "minLength": 8,
            "maxLength": 40
          },
          "customerEmail": {
            "type": "string",
            "maxLength": 254
          },
          "device": {
            "type": "string",
            "maxLength": 160
          },
          "note": {
            "type": "string",
            "maxLength": 1000
          }
        },
        "required": [
          "serviceId",
          "startAt",
          "customerName",
          "customerPhone"
        ]
      },
      "StoreList": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Store"
            }
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "requestId",
          "data",
          "nextCursor"
        ]
      },
      "StoreResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "$ref": "#/components/schemas/Store"
          },
          "replayed": {
            "type": "boolean"
          }
        },
        "required": [
          "requestId",
          "storeId",
          "data"
        ]
      },
      "CustomerList": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Customer"
            }
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "requestId",
          "storeId",
          "data",
          "nextCursor"
        ]
      },
      "CustomerResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "$ref": "#/components/schemas/Customer"
          },
          "replayed": {
            "type": "boolean"
          }
        },
        "required": [
          "requestId",
          "storeId",
          "data"
        ]
      },
      "InventoryList": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Inventory"
            }
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "requestId",
          "storeId",
          "data",
          "nextCursor"
        ]
      },
      "InventoryResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "$ref": "#/components/schemas/Inventory"
          },
          "replayed": {
            "type": "boolean"
          }
        },
        "required": [
          "requestId",
          "storeId",
          "data"
        ]
      },
      "UsedDeviceList": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UsedDevice"
            }
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "requestId",
          "storeId",
          "data",
          "nextCursor"
        ]
      },
      "UsedDeviceResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "$ref": "#/components/schemas/UsedDevice"
          },
          "replayed": {
            "type": "boolean"
          }
        },
        "required": [
          "requestId",
          "storeId",
          "data"
        ]
      },
      "SaleList": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Sale"
            }
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "requestId",
          "storeId",
          "data",
          "nextCursor"
        ]
      },
      "SaleResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "$ref": "#/components/schemas/SaleDetail"
          },
          "replayed": {
            "type": "boolean"
          }
        },
        "required": [
          "requestId",
          "storeId",
          "data"
        ]
      },
      "RepairList": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Repair"
            }
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "requestId",
          "storeId",
          "data",
          "nextCursor"
        ]
      },
      "RepairResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "$ref": "#/components/schemas/Repair"
          },
          "replayed": {
            "type": "boolean"
          }
        },
        "required": [
          "requestId",
          "storeId",
          "data"
        ]
      },
      "OrderList": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Order"
            }
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "requestId",
          "storeId",
          "data",
          "nextCursor"
        ]
      },
      "OrderResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "$ref": "#/components/schemas/OrderDetail"
          },
          "replayed": {
            "type": "boolean"
          }
        },
        "required": [
          "requestId",
          "storeId",
          "data"
        ]
      },
      "AppointmentList": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Appointment"
            }
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "requestId",
          "storeId",
          "data",
          "nextCursor"
        ]
      },
      "AppointmentResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "$ref": "#/components/schemas/Appointment"
          },
          "replayed": {
            "type": "boolean"
          }
        },
        "required": [
          "requestId",
          "storeId",
          "data"
        ]
      },
      "MeResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "data": {
            "$ref": "#/components/schemas/Me"
          }
        },
        "required": [
          "requestId",
          "data"
        ]
      },
      "ServicesResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "timeZone": {
            "type": "string"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Service"
            }
          },
          "ready": {
            "type": "boolean"
          },
          "todayLocal": {
            "type": "string",
            "format": "date",
            "minLength": 10,
            "maxLength": 10,
            "description": "Current shop-local date derived by the server using the accepted store calendar policy, not the visitor clock/timezone."
          },
          "display": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": false,
            "properties": {
              "at": {
                "type": "string",
                "format": "date-time",
                "maxLength": 24,
                "description": "Canonical minute-aligned UTC value supplied in displayAt; binding only."
              },
              "local": {
                "type": "string",
                "minLength": 16,
                "maxLength": 16,
                "pattern": "^\\d{4}-\\d{2}-\\d{2}T(?:[01]\\d|2[0-3]):[0-5]\\d$",
                "description": "Server-derived shop-local display literal under the same current store calendar policy as availability. Display only; submit the original UTC startAt unchanged."
              },
              "timeZone": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128
              }
            },
            "required": [
              "at",
              "local",
              "timeZone"
            ],
            "description": "Optional display of one supplied saved UTC instant. No booking read/hold, lookup or mutation; null when displayAt omitted."
          }
        },
        "required": [
          "requestId",
          "storeId",
          "timeZone",
          "data",
          "ready"
        ]
      },
      "AvailabilityResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "timeZone": {
            "type": "string"
          },
          "slots": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "startAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "endAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "remaining": {
                  "type": "integer",
                  "minimum": 1
                },
                "startLocal": {
                  "type": "string",
                  "minLength": 16,
                  "maxLength": 16,
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}T(?:[01]\\d|2[0-3]):[0-5]\\d$",
                  "description": "Server-derived shop-local display literal under the same current store calendar policy as availability. Display only; submit the original UTC startAt unchanged."
                },
                "endLocal": {
                  "type": "string",
                  "minLength": 16,
                  "maxLength": 16,
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}T(?:[01]\\d|2[0-3]):[0-5]\\d$",
                  "description": "Server-derived shop-local display literal under the same current store calendar policy as availability. Display only; submit the original UTC startAt unchanged."
                }
              },
              "required": [
                "startAt",
                "endAt",
                "remaining"
              ]
            }
          }
        },
        "required": [
          "requestId",
          "storeId",
          "date",
          "timeZone",
          "slots"
        ]
      },
      "WebhookEvent": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "type",
          "schemaVersion",
          "businessId",
          "storeId",
          "occurredAt",
          "resource"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Signed stable event identity: durable duplicate detection key."
          },
          "type": {
            "type": "string",
            "enum": [
              "customer.created",
              "customer.updated",
              "appointment.created",
              "appointment.updated",
              "appointment.cancelled",
              "repair.status_changed",
              "sale.recorded"
            ]
          },
          "schemaVersion": {
            "type": "integer",
            "const": 1
          },
          "businessId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "Event time, not signature freshness time. Legitimate retries can be old."
          },
          "resource": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "type",
              "id",
              "version"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "customers",
                  "appointments",
                  "repairs",
                  "sales"
                ],
                "description": "Must agree with event type; see reference receiver."
              },
              "id": {
                "type": "string",
                "description": "Appointment UUID or positive integer encoded as a string."
              },
              "version": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 1
              }
            }
          }
        }
      },
      "InventoryAvailability": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "name": {
            "type": "string"
          },
          "sku": {
            "type": [
              "string",
              "null"
            ]
          },
          "barcode": {
            "type": [
              "string",
              "null"
            ]
          },
          "category": {
            "type": "string",
            "const": "Accessories"
          },
          "currency": {
            "type": "string"
          },
          "priceMinor": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Current saved catalogue selling price in currency minor units, not a checkout total. This resource does not calculate tax, shipping or discounts."
          },
          "onHandQuantity": {
            "type": "integer",
            "description": "Raw saved stock balance, before holds. A legacy negative balance is not silently rewritten."
          },
          "customerReservedQuantity": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "All held product allocations whose customer reservation is active; no current-session exclusion."
          },
          "exchangeHeldQuantity": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "All prepared, settlement_pending and needs_review exchange checkout product holds; unknown settlement does not automatically expire."
          },
          "availableQuantity": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "max(0, onHandQuantity - customerReservedQuantity - exchangeHeldQuantity). Observation only; not a reservation."
          },
          "eligible": {
            "type": "boolean",
            "const": true
          }
        },
        "required": [
          "id",
          "storeId",
          "name",
          "sku",
          "barcode",
          "category",
          "currency",
          "priceMinor",
          "onHandQuantity",
          "customerReservedQuantity",
          "exchangeHeldQuantity",
          "availableQuantity",
          "eligible"
        ],
        "description": "Eligible products are active, listed Accessories without any purchase-receipt serial history (including released serial history at any store), a special-order product flag, or active same-store repair special orders. Devices, serialized stock, bundles, parts and other categories are unsupported. Conservative exclusions may omit otherwise ordinary units. Observational stock only: this feed does not reserve inventory, accept orders, synchronize a channel or prevent overselling. Quantity can change immediately. Re-read before use; multiple mappings do not allocate separate stock pools."
      },
      "CatalogueMapping": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "productId": {
            "type": "integer",
            "minimum": 1
          },
          "channel": {
            "type": "string",
            "enum": [
              "shopify",
              "woocommerce",
              "other"
            ],
            "description": "Owner-entered descriptive label; not a verified connection."
          },
          "accountLabel": {
            "type": "string",
            "maxLength": 80,
            "description": "Owner-entered normalized account label; not provider-authenticated identity."
          },
          "externalId": {
            "type": "string",
            "maxLength": 150,
            "description": "Exact external catalogue/product/variant reference reviewed by the owner."
          },
          "externalSku": {
            "type": "string",
            "maxLength": 100
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "retired"
            ]
          },
          "version": {
            "type": "integer",
            "minimum": 1
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "retiredAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "availabilityStatus": {
            "type": "string",
            "enum": [
              "available",
              "product_unavailable",
              "retired"
            ],
            "description": "available means the product is supported; quantity can still be zero. Retired/unsupported/missing products always expose zero availability."
          },
          "availableQuantity": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "product": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/InventoryAvailability"
              },
              {
                "type": "null"
              }
            ],
            "description": "Current eligible product, or null when it is missing, inactive, unlisted or outside the supported subset. A retired mapping can retain eligible product metadata but its mapping-level availableQuantity is zero."
          }
        },
        "required": [
          "id",
          "storeId",
          "productId",
          "channel",
          "accountLabel",
          "externalId",
          "externalSku",
          "status",
          "version",
          "createdAt",
          "retiredAt",
          "availabilityStatus",
          "availableQuantity",
          "product"
        ],
        "description": "Reviewed metadata only. Identity/review snapshot is immutable; owner must retire a mapping to replace it. Default lists include retired records. No provider publishing or stock allocation occurs."
      },
      "InventoryAvailabilityList": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InventoryAvailability"
            }
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Opaque signed cursor; repeat key, resource, store, filters and limit. Null ends this page sequence; no multi-page snapshot is promised."
          },
          "observedAt": {
            "type": "string",
            "format": "date-time"
          },
          "notice": {
            "type": "string"
          },
          "supportedScope": {
            "type": "string"
          }
        },
        "required": [
          "requestId",
          "storeId",
          "data",
          "nextCursor",
          "observedAt",
          "notice",
          "supportedScope"
        ]
      },
      "InventoryAvailabilityResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "$ref": "#/components/schemas/InventoryAvailability"
          },
          "nextCursor": {
            "type": "null"
          },
          "observedAt": {
            "type": "string",
            "format": "date-time"
          },
          "notice": {
            "type": "string"
          },
          "supportedScope": {
            "type": "string"
          }
        },
        "required": [
          "requestId",
          "storeId",
          "data",
          "nextCursor",
          "observedAt",
          "notice",
          "supportedScope"
        ]
      },
      "CatalogueMappingList": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CatalogueMapping"
            }
          },
          "nextCursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Opaque signed cursor; repeat key, resource, store, filters and limit. Null ends this page sequence; no multi-page snapshot is promised."
          },
          "observedAt": {
            "type": "string",
            "format": "date-time"
          },
          "notice": {
            "type": "string"
          },
          "supportedScope": {
            "type": "string"
          }
        },
        "required": [
          "requestId",
          "storeId",
          "data",
          "nextCursor",
          "observedAt",
          "notice",
          "supportedScope"
        ]
      },
      "CatalogueMappingResponse": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "storeId": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "$ref": "#/components/schemas/CatalogueMapping"
          },
          "nextCursor": {
            "type": "null"
          },
          "observedAt": {
            "type": "string",
            "format": "date-time"
          },
          "notice": {
            "type": "string"
          },
          "supportedScope": {
            "type": "string"
          }
        },
        "required": [
          "requestId",
          "storeId",
          "data",
          "nextCursor",
          "observedAt",
          "notice",
          "supportedScope"
        ]
      }
    }
  },
  "externalDocs": {
    "description": "Runnable booking website and signed webhook receiver: setup, recovery and limitations",
    "url": "https://www.benchtill.com/developers/examples/booking/README.md"
  },
  "webhooks": {
    "recordChanged": {
      "post": {
        "summary": "Receive an owner-subscribed record reference at your HTTPS endpoint",
        "description": "Outbound only: not a BenchTill callable API route. Owner registration, active access and enabled integration worker required. Future matching events only; at least once, unordered, no complete change stream or automatic history backfill. Persist the verified event before acknowledging. Sample stores an inbox but does not process external side effects. No contact details or amounts. Endpoint management is a POS owner operation, not a developer-key scope.",
        "security": [
          {
            "BenchTillWebhookSignature": []
          }
        ],
        "parameters": [
          {
            "name": "X-BenchTill-Timestamp",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^\\d{10,12}$"
            },
            "description": "Unix seconds for this send attempt."
          },
          {
            "name": "X-BenchTill-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^v1=[a-f0-9]{64}$"
            },
            "description": "HMAC of timestamp + dot + exact raw body; use the complete endpoint secret."
          },
          {
            "name": "X-BenchTill-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Must equal body.id."
          },
          {
            "name": "X-BenchTill-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Stable endpoint/event delivery ID; this header is not independently signed."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Equals X-BenchTill-Delivery. Deduplicate the signed body.id, not only this header."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookEvent"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Verified event durably accepted, including an already accepted identical event."
          },
          "400": {
            "description": "Invalid signature, timestamp or envelope; not automatically retried."
          },
          "409": {
            "description": "Signed event identity conflicts with previously saved content; not automatically retried."
          },
          "429": {
            "description": "Transient refusal; sender applies bounded Retry-After and backoff."
          },
          "503": {
            "description": "No durable acknowledgement yet; sender retries with backoff. Eight automatic attempts maximum."
          }
        }
      }
    }
  }
}
