{
  "openapi": "3.0.0",
  "info": {
    "title": "MarketBox 2.0 Open API",
    "version": "1.0.0",
    "description": "The MarketBox public API for building booking experiences. Core model: create an order, then draw its order items down into bookings. Single bookings reference an order item per service line; package bookings draw one PACKAGE item down across N sessions. To schedule a package, build a slate (POST /availability/package-slate) and book it by slateId (POST /orders/{orderId}/package-bookings). See the guides for end-to-end walkthroughs.",
    "contact": {
      "name": "MarketBox support"
    }
  },
  "servers": [
    {
      "url": "https://apiv2.gomarketbox.com",
      "description": "MarketBox Open API"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "API key minted in the MarketBox dashboard. Scope is restricted to the projects you select at creation time. Every route needs the key's standard API access (`*`) except `POST /v1/projects/{projectId}/events`, which needs `events:write`; a key without `*` is refused with 403 `CAPABILITY_NOT_GRANTED`."
      },
      "EndUserBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "The signed-in person's Cognito access token, issued to this application's app client. Sent with the API key on the /clients/me and /suppliers/me routes."
      }
    },
    "schemas": {
      "SiteEvent": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/SiteEventOpportunity"
          },
          {
            "$ref": "#/components/schemas/SiteEventImpression"
          },
          {
            "$ref": "#/components/schemas/SiteEventClick"
          },
          {
            "$ref": "#/components/schemas/SiteEventProfileView"
          },
          {
            "$ref": "#/components/schemas/SiteEventCoverageMiss"
          },
          {
            "$ref": "#/components/schemas/SiteEventSearchRendered"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "opportunity": "#/components/schemas/SiteEventOpportunity",
            "impression": "#/components/schemas/SiteEventImpression",
            "click": "#/components/schemas/SiteEventClick",
            "profile_view": "#/components/schemas/SiteEventProfileView",
            "coverage_miss": "#/components/schemas/SiteEventCoverageMiss",
            "search.rendered": "#/components/schemas/SiteEventSearchRendered"
          }
        },
        "description": "One site event. `type` picks the shape; the fields every type shares are listed on each."
      },
      "SiteEventOpportunity": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["opportunity"],
            "example": "opportunity",
            "description": "A list that includes suppliers was drawn: one event per list render."
          },
          "eventId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Your id for this event — a UUID (v4 or v7), unique within the project. The idempotency key: a retry re-sending the same id is accepted and counted once.",
            "example": "lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "When it happened, as an ISO 8601 instant with an offset or `Z` (R-1). Rejected per event when more than 24 hours ahead of receipt, or older than 72 hours without the `events:import` capability (400 days with it).",
            "example": "2026-10-03T14:05:10.020Z"
          },
          "sessionKey": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "An opaque per-session key you hash yourself, at most 64 characters. Never an email, IP or user id. Alternatively the `X-MB-Session-Key` header.",
            "example": "sess-example-01"
          },
          "searchId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "The `searchId` of the MarketBox search response the list came from, when it did (the `X-MB-Search-Id` header / body field of every search route).",
            "example": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
          },
          "path": {
            "type": "string",
            "maxLength": 300,
            "description": "The page path, at most 300 characters. The query string is stripped on receipt.",
            "example": "/en-ca/book/results"
          },
          "serviceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "The service the list or search was for, when there was one.",
            "example": "srv_01kv60qg12e82acr78edfnjhvv"
          },
          "locale": {
            "type": "string",
            "minLength": 2,
            "maxLength": 16,
            "description": "The page locale, as a BCP 47 tag.",
            "example": "en-CA"
          },
          "h3": {
            "type": "string",
            "pattern": "^88[0-9a-f]{13}$",
            "description": "The place in the event as a resolution-8 H3 cell. Send this or `lat`/`lng`, not both.",
            "example": "882b8e4a0dfffff"
          },
          "lat": {
            "type": "number",
            "minimum": -90,
            "maximum": 90,
            "description": "Latitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.",
            "example": 43.6532
          },
          "lng": {
            "type": "number",
            "minimum": -180,
            "maximum": 180,
            "description": "Longitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.",
            "example": -79.3832
          },
          "surface": {
            "type": "string",
            "enum": [
              "home",
              "results",
              "listing",
              "site_search",
              "profile",
              "widget",
              "assistant",
              "other"
            ],
            "description": "Where on the site the list was drawn.",
            "example": "results"
          },
          "suppliers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "supplierId": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128,
                  "description": "The MarketBox supplier id. Must belong to this project, or the event is rejected.",
                  "example": "sup_01kv60qh3m7wznp8s0d2rk9abc"
                },
                "position": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "0-based rank in the list as drawn (the same number a search response returns).",
                  "example": 0
                }
              },
              "required": ["supplierId", "position"],
              "additionalProperties": false
            },
            "maxItems": 100,
            "description": "The suppliers actually put on the page, in the order drawn, at most 100. Every id must belong to this project, or the whole event is rejected.",
            "example": [
              {
                "supplierId": "sup_01kv60qh3m7wznp8s0d2rk9abc",
                "position": 0
              },
              {
                "supplierId": "sup_01kv60qh3m7wznp8s0d2rk9def",
                "position": 1
              }
            ]
          }
        },
        "required": ["type", "eventId", "occurredAt", "surface", "suppliers"],
        "additionalProperties": false
      },
      "SiteEventImpression": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["impression"],
            "example": "impression",
            "description": "A supplier's card reached the screen (≥ 50 % in the viewport) for the first time in that list render."
          },
          "eventId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Your id for this event — a UUID (v4 or v7), unique within the project. The idempotency key: a retry re-sending the same id is accepted and counted once.",
            "example": "lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "When it happened, as an ISO 8601 instant with an offset or `Z` (R-1). Rejected per event when more than 24 hours ahead of receipt, or older than 72 hours without the `events:import` capability (400 days with it).",
            "example": "2026-10-03T14:05:10.020Z"
          },
          "sessionKey": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "An opaque per-session key you hash yourself, at most 64 characters. Never an email, IP or user id. Alternatively the `X-MB-Session-Key` header.",
            "example": "sess-example-01"
          },
          "searchId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "The `searchId` of the MarketBox search response the list came from, when it did (the `X-MB-Search-Id` header / body field of every search route).",
            "example": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
          },
          "path": {
            "type": "string",
            "maxLength": 300,
            "description": "The page path, at most 300 characters. The query string is stripped on receipt.",
            "example": "/en-ca/book/results"
          },
          "serviceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "The service the list or search was for, when there was one.",
            "example": "srv_01kv60qg12e82acr78edfnjhvv"
          },
          "locale": {
            "type": "string",
            "minLength": 2,
            "maxLength": 16,
            "description": "The page locale, as a BCP 47 tag.",
            "example": "en-CA"
          },
          "h3": {
            "type": "string",
            "pattern": "^88[0-9a-f]{13}$",
            "description": "The place in the event as a resolution-8 H3 cell. Send this or `lat`/`lng`, not both.",
            "example": "882b8e4a0dfffff"
          },
          "lat": {
            "type": "number",
            "minimum": -90,
            "maximum": 90,
            "description": "Latitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.",
            "example": 43.6532
          },
          "lng": {
            "type": "number",
            "minimum": -180,
            "maximum": 180,
            "description": "Longitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.",
            "example": -79.3832
          },
          "listId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "The `eventId` of the `opportunity` this card belongs to.",
            "example": "lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b"
          },
          "supplierId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "The MarketBox supplier id. Must belong to this project, or the event is rejected.",
            "example": "sup_01kv60qh3m7wznp8s0d2rk9abc"
          },
          "position": {
            "type": "integer",
            "minimum": 0,
            "description": "0-based rank in the list as drawn (the same number a search response returns).",
            "example": 0
          }
        },
        "required": [
          "type",
          "eventId",
          "occurredAt",
          "listId",
          "supplierId",
          "position"
        ],
        "additionalProperties": false
      },
      "SiteEventClick": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["click"],
            "example": "click",
            "description": "The client opened a supplier's profile or card from a list."
          },
          "eventId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Your id for this event — a UUID (v4 or v7), unique within the project. The idempotency key: a retry re-sending the same id is accepted and counted once.",
            "example": "lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "When it happened, as an ISO 8601 instant with an offset or `Z` (R-1). Rejected per event when more than 24 hours ahead of receipt, or older than 72 hours without the `events:import` capability (400 days with it).",
            "example": "2026-10-03T14:05:10.020Z"
          },
          "sessionKey": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "An opaque per-session key you hash yourself, at most 64 characters. Never an email, IP or user id. Alternatively the `X-MB-Session-Key` header.",
            "example": "sess-example-01"
          },
          "searchId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "The `searchId` of the MarketBox search response the list came from, when it did (the `X-MB-Search-Id` header / body field of every search route).",
            "example": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
          },
          "path": {
            "type": "string",
            "maxLength": 300,
            "description": "The page path, at most 300 characters. The query string is stripped on receipt.",
            "example": "/en-ca/book/results"
          },
          "serviceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "The service the list or search was for, when there was one.",
            "example": "srv_01kv60qg12e82acr78edfnjhvv"
          },
          "locale": {
            "type": "string",
            "minLength": 2,
            "maxLength": 16,
            "description": "The page locale, as a BCP 47 tag.",
            "example": "en-CA"
          },
          "h3": {
            "type": "string",
            "pattern": "^88[0-9a-f]{13}$",
            "description": "The place in the event as a resolution-8 H3 cell. Send this or `lat`/`lng`, not both.",
            "example": "882b8e4a0dfffff"
          },
          "lat": {
            "type": "number",
            "minimum": -90,
            "maximum": 90,
            "description": "Latitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.",
            "example": 43.6532
          },
          "lng": {
            "type": "number",
            "minimum": -180,
            "maximum": 180,
            "description": "Longitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.",
            "example": -79.3832
          },
          "supplierId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "The MarketBox supplier id. Must belong to this project, or the event is rejected.",
            "example": "sup_01kv60qh3m7wznp8s0d2rk9abc"
          },
          "impressionId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "The `eventId` of the `impression` that was clicked. Send this, or `listId` when you do not track impressions.",
            "example": "imp_2b7e1d5c-9f4a-4b8e-a3c6-7d0e2f1a9b4c"
          },
          "listId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "The `eventId` of the `opportunity` the card was in, when no `impressionId` is known.",
            "example": "lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b"
          }
        },
        "required": ["type", "eventId", "occurredAt", "supplierId"],
        "additionalProperties": false
      },
      "SiteEventProfileView": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["profile_view"],
            "example": "profile_view",
            "description": "A supplier's profile page loaded, from anywhere."
          },
          "eventId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Your id for this event — a UUID (v4 or v7), unique within the project. The idempotency key: a retry re-sending the same id is accepted and counted once.",
            "example": "lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "When it happened, as an ISO 8601 instant with an offset or `Z` (R-1). Rejected per event when more than 24 hours ahead of receipt, or older than 72 hours without the `events:import` capability (400 days with it).",
            "example": "2026-10-03T14:05:10.020Z"
          },
          "sessionKey": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "An opaque per-session key you hash yourself, at most 64 characters. Never an email, IP or user id. Alternatively the `X-MB-Session-Key` header.",
            "example": "sess-example-01"
          },
          "searchId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "The `searchId` of the MarketBox search response the list came from, when it did (the `X-MB-Search-Id` header / body field of every search route).",
            "example": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
          },
          "path": {
            "type": "string",
            "maxLength": 300,
            "description": "The page path, at most 300 characters. The query string is stripped on receipt.",
            "example": "/en-ca/book/results"
          },
          "serviceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "The service the list or search was for, when there was one.",
            "example": "srv_01kv60qg12e82acr78edfnjhvv"
          },
          "locale": {
            "type": "string",
            "minLength": 2,
            "maxLength": 16,
            "description": "The page locale, as a BCP 47 tag.",
            "example": "en-CA"
          },
          "h3": {
            "type": "string",
            "pattern": "^88[0-9a-f]{13}$",
            "description": "The place in the event as a resolution-8 H3 cell. Send this or `lat`/`lng`, not both.",
            "example": "882b8e4a0dfffff"
          },
          "lat": {
            "type": "number",
            "minimum": -90,
            "maximum": 90,
            "description": "Latitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.",
            "example": 43.6532
          },
          "lng": {
            "type": "number",
            "minimum": -180,
            "maximum": 180,
            "description": "Longitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.",
            "example": -79.3832
          },
          "supplierId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "The MarketBox supplier id. Must belong to this project, or the event is rejected.",
            "example": "sup_01kv60qh3m7wznp8s0d2rk9abc"
          },
          "referrerClass": {
            "type": "string",
            "enum": [
              "internal",
              "search",
              "direct",
              "social",
              "ads",
              "other_site",
              "assistant"
            ],
            "description": "How the visitor reached the profile page: from your own site, a search engine, a typed URL, a social network, an ad, another site, or an AI assistant.",
            "example": "internal"
          }
        },
        "required": [
          "type",
          "eventId",
          "occurredAt",
          "supplierId",
          "referrerClass"
        ],
        "additionalProperties": false
      },
      "SiteEventCoverageMiss": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["coverage_miss"],
            "example": "coverage_miss",
            "description": "A client entered an address and the site found nobody, without calling a MarketBox search."
          },
          "eventId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Your id for this event — a UUID (v4 or v7), unique within the project. The idempotency key: a retry re-sending the same id is accepted and counted once.",
            "example": "lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "When it happened, as an ISO 8601 instant with an offset or `Z` (R-1). Rejected per event when more than 24 hours ahead of receipt, or older than 72 hours without the `events:import` capability (400 days with it).",
            "example": "2026-10-03T14:05:10.020Z"
          },
          "sessionKey": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "An opaque per-session key you hash yourself, at most 64 characters. Never an email, IP or user id. Alternatively the `X-MB-Session-Key` header.",
            "example": "sess-example-01"
          },
          "searchId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "The `searchId` of the MarketBox search response the list came from, when it did (the `X-MB-Search-Id` header / body field of every search route).",
            "example": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
          },
          "path": {
            "type": "string",
            "maxLength": 300,
            "description": "The page path, at most 300 characters. The query string is stripped on receipt.",
            "example": "/en-ca/book/results"
          },
          "serviceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "The service the list or search was for, when there was one.",
            "example": "srv_01kv60qg12e82acr78edfnjhvv"
          },
          "locale": {
            "type": "string",
            "minLength": 2,
            "maxLength": 16,
            "description": "The page locale, as a BCP 47 tag.",
            "example": "en-CA"
          },
          "h3": {
            "type": "string",
            "pattern": "^88[0-9a-f]{13}$",
            "description": "The place in the event as a resolution-8 H3 cell. Send this or `lat`/`lng`, not both.",
            "example": "882b8e4a0dfffff"
          },
          "lat": {
            "type": "number",
            "minimum": -90,
            "maximum": 90,
            "description": "Latitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.",
            "example": 43.6532
          },
          "lng": {
            "type": "number",
            "minimum": -180,
            "maximum": 180,
            "description": "Longitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.",
            "example": -79.3832
          }
        },
        "required": ["type", "eventId", "occurredAt"],
        "additionalProperties": false
      },
      "SiteEventSearchRendered": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["search.rendered"],
            "example": "search.rendered",
            "description": "The results of a MarketBox search were drawn. This is what makes a search count: a search with no render counts for nothing. A later page drawn is another event with the same `searchId`."
          },
          "eventId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Your id for this event — a UUID (v4 or v7), unique within the project. The idempotency key: a retry re-sending the same id is accepted and counted once.",
            "example": "lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "When it happened, as an ISO 8601 instant with an offset or `Z` (R-1). Rejected per event when more than 24 hours ahead of receipt, or older than 72 hours without the `events:import` capability (400 days with it).",
            "example": "2026-10-03T14:05:10.020Z"
          },
          "sessionKey": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "An opaque per-session key you hash yourself, at most 64 characters. Never an email, IP or user id. Alternatively the `X-MB-Session-Key` header.",
            "example": "sess-example-01"
          },
          "searchId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "The `searchId` of the search response whose results were drawn.",
            "example": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
          },
          "path": {
            "type": "string",
            "maxLength": 300,
            "description": "The page path, at most 300 characters. The query string is stripped on receipt.",
            "example": "/en-ca/book/results"
          },
          "serviceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "The service the list or search was for, when there was one.",
            "example": "srv_01kv60qg12e82acr78edfnjhvv"
          },
          "locale": {
            "type": "string",
            "minLength": 2,
            "maxLength": 16,
            "description": "The page locale, as a BCP 47 tag.",
            "example": "en-CA"
          },
          "h3": {
            "type": "string",
            "pattern": "^88[0-9a-f]{13}$",
            "description": "The place in the event as a resolution-8 H3 cell. Send this or `lat`/`lng`, not both.",
            "example": "882b8e4a0dfffff"
          },
          "lat": {
            "type": "number",
            "minimum": -90,
            "maximum": 90,
            "description": "Latitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.",
            "example": 43.6532
          },
          "lng": {
            "type": "number",
            "minimum": -180,
            "maximum": 180,
            "description": "Longitude of the place in the event. Reduced to a resolution-8 H3 cell on receipt; never stored.",
            "example": -79.3832
          },
          "surface": {
            "type": "string",
            "enum": [
              "home",
              "results",
              "listing",
              "site_search",
              "profile",
              "widget",
              "assistant",
              "other"
            ],
            "description": "Where on the site the list was drawn.",
            "example": "results"
          },
          "suppliers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "supplierId": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128,
                  "description": "The MarketBox supplier id. Must belong to this project, or the event is rejected.",
                  "example": "sup_01kv60qh3m7wznp8s0d2rk9abc"
                },
                "position": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "0-based rank in the list as drawn (the same number a search response returns).",
                  "example": 0
                }
              },
              "required": ["supplierId", "position"],
              "additionalProperties": false
            },
            "maxItems": 100,
            "description": "The suppliers actually put on the page, in the order drawn, at most 100. Every id must belong to this project, or the whole event is rejected.",
            "example": [
              {
                "supplierId": "sup_01kv60qh3m7wznp8s0d2rk9abc",
                "position": 0
              },
              {
                "supplierId": "sup_01kv60qh3m7wznp8s0d2rk9def",
                "position": 1
              }
            ]
          }
        },
        "required": [
          "type",
          "eventId",
          "occurredAt",
          "searchId",
          "surface",
          "suppliers"
        ],
        "additionalProperties": false
      },
      "ErrorMessage": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code, e.g. NOT_FOUND."
          },
          "message": {
            "type": "string",
            "description": "Human-readable description of what went wrong."
          },
          "statusCode": {
            "type": "integer",
            "description": "The HTTP status code of this response."
          },
          "requestId": {
            "type": "string",
            "description": "The id of this request, also returned as the X-Request-Id header. Quote it in a support ticket."
          }
        },
        "required": ["code", "message", "statusCode", "requestId"],
        "example": {
          "code": "NOT_FOUND",
          "message": "Booking not found",
          "statusCode": 404,
          "requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
        }
      },
      "SiteEventsBeaconBatch": {
        "type": "object",
        "properties": {
          "events": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/SiteEventOpportunity"
                },
                {
                  "$ref": "#/components/schemas/SiteEventImpression"
                },
                {
                  "$ref": "#/components/schemas/SiteEventClick"
                },
                {
                  "$ref": "#/components/schemas/SiteEventProfileView"
                },
                {
                  "$ref": "#/components/schemas/SiteEventCoverageMiss"
                },
                {
                  "$ref": "#/components/schemas/SiteEventSearchRendered"
                }
              ],
              "discriminator": {
                "propertyName": "type",
                "mapping": {
                  "opportunity": "#/components/schemas/SiteEventOpportunity",
                  "impression": "#/components/schemas/SiteEventImpression",
                  "click": "#/components/schemas/SiteEventClick",
                  "profile_view": "#/components/schemas/SiteEventProfileView",
                  "coverage_miss": "#/components/schemas/SiteEventCoverageMiss",
                  "search.rendered": "#/components/schemas/SiteEventSearchRendered"
                }
              },
              "description": "One site event. `type` picks the shape; the fields every type shares are listed on each."
            },
            "minItems": 1,
            "maxItems": 50,
            "description": "The events, at most 50 per beacon (and 64 KB in all). The same shapes as `POST /events`; each is validated on its own and a rejected one never fails the batch.",
            "example": [
              {
                "eventId": "lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b",
                "type": "search.rendered",
                "occurredAt": "2026-10-03T14:05:10.020Z",
                "sessionKey": "sess-example-01",
                "searchId": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n",
                "surface": "widget",
                "suppliers": [
                  {
                    "supplierId": "sup_01kv60qh3m7wznp8s0d2rk9abc",
                    "position": 0
                  }
                ]
              }
            ]
          }
        },
        "required": ["events"]
      },
      "SupplierPlaneAccess": {
        "type": "object",
        "properties": {
          "allowed": {
            "type": "boolean",
            "description": "True only for `SUPPLIER_ACTIVE`: use the supplier plane with `supplierId`. Otherwise show `message`.",
            "example": false
          },
          "reasonCode": {
            "type": "string",
            "enum": [
              "SUPPLIER_ACTIVE",
              "SUPPLIER_RECORD_INACTIVE",
              "NO_ACCOUNT",
              "NOT_A_MEMBER",
              "MEMBERSHIP_INACTIVE",
              "NO_SUPPLIER_ROLE",
              "SUPPLIER_NOT_LINKED"
            ],
            "description": "Why. `SUPPLIER_ACTIVE`: an ACTIVE membership holding SUPPLIER and a linked, active supplier record. `SUPPLIER_RECORD_INACTIVE`: the same, but the record is `active: false`. `NO_ACCOUNT`: the token is valid but names no MarketBox account. `NOT_A_MEMBER`: no membership in this project. `MEMBERSHIP_INACTIVE`: the membership has ended (every role removed). `NO_SUPPLIER_ROLE`: an ACTIVE membership without SUPPLIER. `SUPPLIER_NOT_LINKED`: holds SUPPLIER, but no single supplier record is linked to the person.",
            "example": "NO_SUPPLIER_ROLE"
          },
          "message": {
            "type": "string",
            "description": "The reason, for a person. The data routes refuse with the same text.",
            "example": "You don't have supplier access on this project."
          },
          "supplierId": {
            "type": "string",
            "nullable": true,
            "description": "The supplier record linked to the person here, for `SUPPLIER_ACTIVE` and `SUPPLIER_RECORD_INACTIVE`; otherwise null.",
            "example": null
          },
          "roles": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": ["CLIENT", "ADMIN", "MANAGER", "DEVELOPER", "SUPPLIER"]
            },
            "description": "Every role the person holds on the project, in the order CLIENT, ADMIN, MANAGER, DEVELOPER, SUPPLIER. `[]` unless the membership is ACTIVE. `X-MB-Acting-Role` is ignored.",
            "example": ["CLIENT"]
          },
          "membershipStatus": {
            "type": "string",
            "nullable": true,
            "enum": ["ACTIVE", "INACTIVE", null],
            "description": "The membership: `ACTIVE`, or `INACTIVE` for every other status. Null when the person has no account or no membership here.",
            "example": "ACTIVE"
          }
        },
        "required": [
          "allowed",
          "reasonCode",
          "message",
          "supplierId",
          "roles",
          "membershipStatus"
        ]
      },
      "Address": {
        "type": "object",
        "nullable": true,
        "properties": {
          "addressOneLine": {
            "type": "string",
            "minLength": 1,
            "description": "The whole address on one line, as a person would write it.",
            "example": "10 Main St, Toronto, ON M5V 1A1, Canada"
          },
          "streetNumber": {
            "type": "string",
            "minLength": 1,
            "description": "The street number.",
            "example": "10"
          },
          "streetName": {
            "type": "string",
            "minLength": 1,
            "description": "The street name.",
            "example": "Main St"
          },
          "city": {
            "type": "string",
            "minLength": 1,
            "description": "The city or town.",
            "example": "Toronto"
          },
          "state": {
            "type": "string",
            "minLength": 1,
            "description": "The state, province or region; an ISO 3166-2 code when one matches.",
            "example": "ON"
          },
          "country": {
            "type": "string",
            "minLength": 1,
            "description": "The country; ISO 3166-1 alpha-2, alpha-3 or the English name.",
            "example": "CA"
          },
          "zipCode": {
            "type": "string",
            "minLength": 1,
            "description": "The postal or ZIP code, in any national format.",
            "example": "M5V 1A1"
          },
          "unitNumber": {
            "type": "string",
            "nullable": true,
            "description": "The unit, suite or apartment, if any.",
            "example": "4B"
          }
        },
        "required": [
          "addressOneLine",
          "streetNumber",
          "streetName",
          "city",
          "state",
          "country",
          "zipCode"
        ]
      },
      "Money": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "integer",
            "minimum": 0
          },
          "currency": {
            "type": "string",
            "minLength": 1,
            "maxLength": 3
          }
        },
        "required": ["amount", "currency"]
      },
      "Booking": {
        "type": "object",
        "properties": {
          "projectId": {
            "type": "string"
          },
          "tenantId": {
            "type": "string"
          },
          "bookingId": {
            "type": "string"
          },
          "seriesId": {
            "type": "string",
            "nullable": true
          },
          "occurrenceLocalDate": {
            "type": "string",
            "nullable": true
          },
          "isException": {
            "type": "boolean"
          },
          "supplierId": {
            "type": "string",
            "nullable": true
          },
          "clientId": {
            "type": "string"
          },
          "packageOrderItemId": {
            "type": "string",
            "nullable": true
          },
          "bookingStartUtc": {
            "type": "string",
            "format": "date-time"
          },
          "bookingEndUtc": {
            "type": "string",
            "format": "date-time"
          },
          "bookingTz": {
            "type": "string"
          },
          "bookingLocalDate": {
            "type": "string"
          },
          "bookingLocalStartTime": {
            "type": "string"
          },
          "bookingLocalEndTime": {
            "type": "string"
          },
          "bookingLocalEndDate": {
            "type": "string"
          },
          "locale": {
            "type": "string"
          },
          "attribution": {
            "type": "object",
            "properties": {
              "searchId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "description": "The `searchId` of the MarketBox search response the buyer booked from — the `X-MB-Search-Id` header / body field of every search route. Stored as given; a value MarketBox never issued is kept but not trusted.",
                "example": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
              },
              "sessionKey": {
                "type": "string",
                "minLength": 1,
                "maxLength": 64,
                "description": "The same opaque per-session key you send with site events, at most 64 characters. Never an email, IP or user id.",
                "example": "sess-example-01"
              },
              "surface": {
                "type": "string",
                "enum": [
                  "home",
                  "results",
                  "listing",
                  "site_search",
                  "profile",
                  "widget",
                  "assistant",
                  "other"
                ],
                "description": "Where on your site the buyer started the purchase.",
                "example": "results"
              }
            },
            "additionalProperties": false,
            "description": "Which search and site session this purchase came from. Optional; set once on the order and copied onto every booking it funds. See the search-log guide, \"Booking attribution\"."
          },
          "locationType": {
            "type": "string",
            "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"]
          },
          "locationId": {
            "type": "string",
            "nullable": true
          },
          "latitude": {
            "type": "number",
            "nullable": true
          },
          "longitude": {
            "type": "number",
            "nullable": true
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "capacity": {
            "type": "integer",
            "minimum": 0,
            "exclusiveMinimum": true
          },
          "participantCount": {
            "type": "integer",
            "minimum": 0
          },
          "waitlistCount": {
            "type": "integer",
            "minimum": 0
          },
          "isGroupBooking": {
            "type": "boolean"
          },
          "status": {
            "type": "string",
            "enum": [
              "SCHEDULED",
              "STARTED",
              "AWAITING_CONFIRMATION",
              "DISPUTED",
              "COMPLETED",
              "CANCELLED",
              "CLIENT_NO_SHOW",
              "SUPPLIER_NO_SHOW",
              "NO_SHOW"
            ]
          },
          "statusUpdatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "statusUpdatedBy": {
            "type": "string"
          },
          "statusUpdatedByCapacity": {
            "type": "string",
            "enum": ["ADMIN", "SUPPLIER", "CLIENT", "SYSTEM", "API"]
          },
          "cancellationReason": {
            "type": "string",
            "nullable": true
          },
          "cancelledBy": {
            "type": "string",
            "nullable": true
          },
          "cancellationInitiatedBy": {
            "type": "string",
            "enum": ["CLIENT", "SUPPLIER", "BUSINESS"]
          },
          "cancellationReasonCode": {
            "type": "string",
            "enum": [
              "CLIENT_REQUESTED",
              "CLIENT_UNWELL",
              "SUPPLIER_UNAVAILABLE",
              "WEATHER",
              "FACILITY_UNAVAILABLE",
              "BOOKED_IN_ERROR",
              "OTHER"
            ]
          },
          "creditTreatment": {
            "type": "string",
            "enum": [
              "RETURN",
              "FORFEIT",
              "REFUND_ORIGINAL_PAYMENT",
              "NOT_APPLICABLE"
            ]
          },
          "durationOverrideMinutes": {
            "type": "integer",
            "minimum": 0,
            "exclusiveMinimum": true,
            "maximum": 1440
          },
          "durationOverrideReason": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "counts": {
            "type": "object",
            "properties": {
              "services": {
                "type": "integer",
                "minimum": 0
              },
              "notes": {
                "type": "integer",
                "minimum": 0
              },
              "participants": {
                "type": "integer",
                "minimum": 0
              }
            },
            "required": ["services", "notes", "participants"]
          },
          "deleted": {
            "type": "boolean"
          },
          "version": {
            "type": "integer",
            "minimum": 0
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "createdBy": {
            "type": "string"
          },
          "updatedBy": {
            "type": "string"
          }
        },
        "required": [
          "projectId",
          "tenantId",
          "bookingId",
          "supplierId",
          "clientId",
          "bookingStartUtc",
          "bookingEndUtc",
          "bookingTz",
          "bookingLocalDate",
          "bookingLocalStartTime",
          "bookingLocalEndTime",
          "bookingLocalEndDate",
          "locationType",
          "locationId",
          "latitude",
          "longitude",
          "address",
          "capacity",
          "participantCount",
          "waitlistCount",
          "isGroupBooking",
          "status",
          "statusUpdatedAt",
          "counts",
          "deleted",
          "version",
          "createdAt",
          "updatedAt",
          "createdBy",
          "updatedBy"
        ]
      },
      "BookingReport": {
        "type": "object",
        "properties": {
          "projectId": {
            "type": "string"
          },
          "bookingId": {
            "type": "string"
          },
          "reporterRole": {
            "type": "string",
            "enum": ["CLIENT", "SUPPLIER"]
          },
          "reporterId": {
            "type": "string"
          },
          "reportType": {
            "type": "string",
            "enum": ["ATTENDANCE"]
          },
          "attended": {
            "type": "boolean"
          },
          "note": {
            "type": "string",
            "maxLength": 1000
          },
          "deleted": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "createdBy": {
            "type": "string"
          },
          "updatedBy": {
            "type": "string"
          }
        },
        "required": [
          "projectId",
          "bookingId",
          "reporterRole",
          "reporterId",
          "reportType",
          "attended",
          "deleted",
          "createdAt",
          "updatedAt",
          "createdBy",
          "updatedBy"
        ]
      },
      "Order": {
        "type": "object",
        "properties": {
          "projectId": {
            "type": "string"
          },
          "tenantId": {
            "type": "string"
          },
          "orderId": {
            "type": "string"
          },
          "clientId": {
            "type": "string"
          },
          "currency": {
            "type": "string",
            "minLength": 3,
            "maxLength": 3
          },
          "subtotal": {
            "$ref": "#/components/schemas/Money"
          },
          "feeTotal": {
            "$ref": "#/components/schemas/Money"
          },
          "tax": {
            "$ref": "#/components/schemas/Money"
          },
          "total": {
            "$ref": "#/components/schemas/Money"
          },
          "amountPaid": {
            "$ref": "#/components/schemas/Money"
          },
          "amountRefunded": {
            "$ref": "#/components/schemas/Money"
          },
          "status": {
            "type": "string",
            "enum": ["DRAFT", "PENDING", "PAID", "CANCELLED"]
          },
          "statusUpdatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "cancellationReason": {
            "type": "string",
            "nullable": true
          },
          "cancelledBy": {
            "type": "string",
            "nullable": true
          },
          "paymentMethod": {
            "type": "string",
            "enum": ["STRIPE", "CASH", "EXTERNAL", "COMP", "MIXED", "LEGACY"]
          },
          "settledAt": {
            "type": "string",
            "format": "date-time"
          },
          "amountComped": {
            "$ref": "#/components/schemas/Money"
          },
          "pricingRegion": {
            "type": "object",
            "nullable": true,
            "properties": {
              "country": {
                "type": "string",
                "nullable": true
              },
              "state": {
                "type": "string",
                "nullable": true
              },
              "postalCode": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "locale": {
            "type": "string"
          },
          "attribution": {
            "type": "object",
            "properties": {
              "searchId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "description": "The `searchId` of the MarketBox search response the buyer booked from — the `X-MB-Search-Id` header / body field of every search route. Stored as given; a value MarketBox never issued is kept but not trusted.",
                "example": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
              },
              "sessionKey": {
                "type": "string",
                "minLength": 1,
                "maxLength": 64,
                "description": "The same opaque per-session key you send with site events, at most 64 characters. Never an email, IP or user id.",
                "example": "sess-example-01"
              },
              "surface": {
                "type": "string",
                "enum": [
                  "home",
                  "results",
                  "listing",
                  "site_search",
                  "profile",
                  "widget",
                  "assistant",
                  "other"
                ],
                "description": "Where on your site the buyer started the purchase.",
                "example": "results"
              }
            },
            "additionalProperties": false,
            "description": "Which search and site session this purchase came from. Optional; set once on the order and copied onto every booking it funds. See the search-log guide, \"Booking attribution\"."
          },
          "deleted": {
            "type": "boolean"
          },
          "version": {
            "type": "integer",
            "minimum": 0
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "createdBy": {
            "type": "string"
          },
          "updatedBy": {
            "type": "string"
          }
        },
        "required": [
          "projectId",
          "tenantId",
          "orderId",
          "clientId",
          "currency",
          "subtotal",
          "tax",
          "total",
          "amountPaid",
          "amountRefunded",
          "status",
          "statusUpdatedAt",
          "deleted",
          "version",
          "createdAt",
          "updatedAt",
          "createdBy",
          "updatedBy"
        ]
      },
      "OrderItem": {
        "type": "object",
        "properties": {
          "projectId": {
            "type": "string"
          },
          "orderId": {
            "type": "string"
          },
          "orderItemId": {
            "type": "string"
          },
          "skuType": {
            "type": "string",
            "enum": [
              "SINGLE_SESSION",
              "PACKAGE",
              "SUBSCRIPTION",
              "MEMBERSHIP",
              "DEPOSIT"
            ]
          },
          "serviceId": {
            "type": "string"
          },
          "offeringId": {
            "type": "string"
          },
          "packageId": {
            "type": "string",
            "nullable": true
          },
          "quantity": {
            "type": "integer",
            "minimum": 0,
            "exclusiveMinimum": true
          },
          "quantityAllocated": {
            "type": "integer",
            "minimum": 0
          },
          "quantityRemaining": {
            "type": "integer",
            "minimum": 0
          },
          "unitPrice": {
            "$ref": "#/components/schemas/Money"
          },
          "lineTotal": {
            "$ref": "#/components/schemas/Money"
          },
          "taxSnapshot": {
            "type": "object",
            "nullable": true,
            "properties": {
              "taxable": {
                "type": "boolean"
              },
              "taxPercentage": {
                "type": "number",
                "minimum": 0
              }
            },
            "required": ["taxable"]
          },
          "feeSnapshot": {
            "type": "array",
            "nullable": true,
            "items": {
              "type": "object",
              "properties": {
                "feeId": {
                  "type": "string",
                  "minLength": 1,
                  "description": "Stable identifier for this fee, unique within the business model.",
                  "example": "fee_booking"
                },
                "name": {
                  "type": "object",
                  "additionalProperties": {
                    "type": "string"
                  },
                  "description": "Buyer-facing label, rendered as its own line on the order summary.",
                  "example": {
                    "en": "Booking fee"
                  }
                },
                "calculation": {
                  "type": "string",
                  "enum": ["FLAT", "PERCENT"],
                  "description": "How a service fee is calculated. FLAT charges a fixed amount; PERCENT charges a percentage of the pre-tax total of the lines the fee governs.",
                  "example": "FLAT"
                },
                "amount": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "FLAT fees only. Integer minor units, charged in whatever currency the order is placed in — 2500 is CA$25.00 on a CAD order and US$25.00 on a USD one. Use a PERCENT fee if you need it to scale.",
                  "example": 2500
                },
                "percentage": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 100,
                  "description": "PERCENT fees only. Applied to the pre-tax total of this business model's lines on the order.",
                  "example": 5
                },
                "taxable": {
                  "type": "boolean",
                  "default": false,
                  "description": "When true, the fee is taxed at the rate of the order lines it is charged alongside (sessions or packages sold under this business model) that are taxed at a positive rate. Lines that are not taxable or taxed at 0% lend no rate; if none of the lines is taxed, the fee is not taxed either.",
                  "example": false
                }
              },
              "required": ["feeId", "name", "calculation"]
            }
          },
          "businessModelId": {
            "type": "string",
            "nullable": true
          },
          "label": {
            "type": "object",
            "nullable": true,
            "additionalProperties": {
              "type": "string"
            }
          },
          "priceRuleId": {
            "type": "string",
            "nullable": true,
            "description": "Which regional price rule this line resolved to. Compare against the offering/package `pricing[]` to see exactly which price was applied."
          },
          "priceScope": {
            "type": "string",
            "nullable": true,
            "enum": ["DEFAULT", "COUNTRY", "STATE", "POSTAL", null],
            "description": "Specificity of the matched rule: DEFAULT, COUNTRY, STATE or POSTAL. DEFAULT means no regional rule matched and the fallback price was used."
          },
          "priceSource": {
            "type": "string",
            "enum": ["RULE", "MANUAL"],
            "description": "Where this line’s price came from. RULE: resolved from the offering or package `pricing[]` (see `priceRuleId`). MANUAL: set by staff when the order was created, in place of the rule price; `priceRuleId` is null and `unitPrice` will not match any rule. Absent on items written before this field existed."
          },
          "taxExemptReason": {
            "type": "string",
            "enum": [
              "NO_RATE",
              "NOT_TAXABLE",
              "ZERO_RATE",
              "MIGRATED_V1",
              "PACKAGE_EXEMPT_LEGACY"
            ],
            "description": "Why this line carries no tax. NO_RATE: neither the matched price rule, its parent rules, nor the service set a rate. NOT_TAXABLE: the resolved tax settings mark it not taxable. ZERO_RATE: taxable at 0%. MIGRATED_V1: imported from MarketBox v1, which recorded tax on the order rather than per line. PACKAGE_EXEMPT_LEGACY: a package line written while package purchases were untaxed (June–September 2026). Absent when the line is taxed at a positive rate, and on lines written before this field existed."
          },
          "expiresAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time"
          },
          "deleted": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "createdBy": {
            "type": "string"
          },
          "updatedBy": {
            "type": "string"
          }
        },
        "required": [
          "projectId",
          "orderId",
          "orderItemId",
          "skuType",
          "serviceId",
          "offeringId",
          "quantity",
          "quantityAllocated",
          "quantityRemaining",
          "unitPrice",
          "lineTotal",
          "deleted",
          "createdAt",
          "updatedAt",
          "createdBy",
          "updatedBy"
        ]
      },
      "ServicePackage": {
        "type": "object",
        "properties": {
          "entityType": {
            "type": "string",
            "enum": ["SERVICE_PACKAGE"]
          },
          "projectId": {
            "type": "string"
          },
          "serviceId": {
            "type": "string"
          },
          "offeringId": {
            "type": "string"
          },
          "packageId": {
            "type": "string"
          },
          "name": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "description": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "pricingModel": {
            "type": "string",
            "enum": ["PER_SESSION", "FLAT"]
          },
          "pricing": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "ruleId": {
                  "type": "string",
                  "minLength": 1
                },
                "scope": {
                  "type": "string",
                  "enum": ["DEFAULT", "COUNTRY", "STATE", "POSTAL"],
                  "description": "How specifically a price rule targets a region. Resolution picks the most specific match: POSTAL beats STATE beats COUNTRY beats DEFAULT. DEFAULT is the fallback every offering must define (\"any region\"). On an order item, `priceScope` reports which one actually applied — seeing DEFAULT where you expected a regional price means the region did not resolve."
                },
                "country": {
                  "type": "string",
                  "minLength": 1
                },
                "state": {
                  "type": "string",
                  "minLength": 1
                },
                "postalCodes": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "price": {
                  "$ref": "#/components/schemas/Money"
                },
                "tax": {
                  "type": "object",
                  "properties": {
                    "taxable": {
                      "type": "boolean"
                    },
                    "taxPercentage": {
                      "type": "number",
                      "minimum": 0
                    }
                  },
                  "required": ["taxable"]
                }
              },
              "required": ["ruleId", "scope", "price"]
            },
            "minItems": 1
          },
          "creditCount": {
            "type": "integer",
            "minimum": 0,
            "exclusiveMinimum": true
          },
          "discountPercent": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "description": "Percentage discount (0-100) recorded when this package's prices were seeded from the offering's prices (price = offering price * creditCount * (1 - discountPercent/100)). Informational metadata only: `pricing` is the authoritative source of the amounts charged. Individual prices can be manually overridden after seeding, and the offering's prices may change later, so this value is not guaranteed to match the actual prices - never derive amounts from it."
          },
          "validityDays": {
            "type": "integer",
            "nullable": true,
            "minimum": 0,
            "exclusiveMinimum": true
          },
          "status": {
            "type": "string",
            "enum": ["DRAFT", "ACTIVE", "ARCHIVED"],
            "description": "Lifecycle of the package bundle. ARCHIVED hides it from the storefront and blocks new orders, but order items already placed against it stay bookable."
          },
          "capacity": {
            "type": "integer",
            "minimum": 0,
            "exclusiveMinimum": true
          },
          "deleted": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "createdBy": {
            "type": "string"
          },
          "updatedBy": {
            "type": "string"
          }
        },
        "required": [
          "entityType",
          "projectId",
          "serviceId",
          "offeringId",
          "packageId",
          "pricingModel",
          "pricing",
          "creditCount",
          "validityDays",
          "status",
          "capacity",
          "deleted",
          "createdAt",
          "updatedAt",
          "createdBy",
          "updatedBy"
        ]
      },
      "ClientProfile": {
        "type": "object",
        "properties": {
          "entityType": {
            "type": "string",
            "enum": ["CLIENT_PROFILE"]
          },
          "clientId": {
            "type": "string"
          },
          "projectId": {
            "type": "string"
          },
          "firstName": {
            "type": "string"
          },
          "lastName": {
            "type": "string"
          },
          "fullName": {
            "type": "string"
          },
          "firstNameNormalized": {
            "type": "string"
          },
          "lastNameNormalized": {
            "type": "string"
          },
          "fullNameNormalized": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "emailNormalized": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "defaultAddressId": {
            "type": "string"
          },
          "externalId": {
            "type": "string"
          },
          "externalData": {
            "type": "object",
            "additionalProperties": {
              "nullable": true
            }
          },
          "userId": {
            "type": "string"
          },
          "invitationStatus": {
            "type": "string",
            "enum": ["NONE", "INVITED", "LINKED"]
          },
          "stripeCustomerId": {
            "type": "string",
            "nullable": true
          },
          "stripeAccountId": {
            "type": "string",
            "nullable": true
          },
          "notes": {
            "type": "string"
          },
          "lifetimeSpend": {
            "type": "number"
          },
          "orderCount": {
            "type": "number"
          },
          "lastPurchaseAt": {
            "type": "string"
          },
          "lastPaymentMethodId": {
            "type": "string"
          },
          "lastPayment": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": ["CARD"]
              },
              "brand": {
                "type": "string"
              },
              "last4": {
                "type": "string",
                "minLength": 4,
                "maxLength": 4
              },
              "expMonth": {
                "type": "integer",
                "nullable": true,
                "minimum": 1,
                "maximum": 12
              },
              "expYear": {
                "type": "integer",
                "nullable": true
              },
              "paidAt": {
                "type": "string"
              }
            },
            "required": ["type", "brand", "last4", "paidAt"]
          },
          "defaultLocale": {
            "type": "string"
          },
          "active": {
            "type": "boolean"
          },
          "deleted": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string"
          },
          "updatedAt": {
            "type": "string"
          },
          "createdBy": {
            "type": "string"
          },
          "updatedBy": {
            "type": "string"
          },
          "addresses": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "addressOneLine": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The whole address on one line, as a person would write it.",
                  "example": "10 Main St, Toronto, ON M5V 1A1, Canada"
                },
                "streetNumber": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The street number.",
                  "example": "10"
                },
                "streetName": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The street name.",
                  "example": "Main St"
                },
                "city": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The city or town.",
                  "example": "Toronto"
                },
                "state": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The state, province or region; an ISO 3166-2 code when one matches.",
                  "example": "ON"
                },
                "country": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The country; ISO 3166-1 alpha-2, alpha-3 or the English name.",
                  "example": "CA"
                },
                "zipCode": {
                  "type": "string",
                  "minLength": 1,
                  "description": "The postal or ZIP code, in any national format.",
                  "example": "M5V 1A1"
                },
                "unitNumber": {
                  "type": "string",
                  "nullable": true,
                  "description": "The unit, suite or apartment, if any.",
                  "example": "4B"
                },
                "id": {
                  "type": "string",
                  "minLength": 1
                },
                "source": {
                  "type": "string",
                  "enum": ["BOOKING", "MANUAL"]
                },
                "latitude": {
                  "type": "number",
                  "nullable": true
                },
                "longitude": {
                  "type": "number",
                  "nullable": true
                }
              },
              "required": [
                "addressOneLine",
                "streetNumber",
                "streetName",
                "city",
                "state",
                "country",
                "zipCode",
                "id"
              ]
            }
          }
        },
        "required": [
          "entityType",
          "clientId",
          "projectId",
          "firstName",
          "lastName",
          "fullName",
          "firstNameNormalized",
          "lastNameNormalized",
          "fullNameNormalized",
          "email",
          "emailNormalized",
          "invitationStatus",
          "stripeCustomerId",
          "stripeAccountId",
          "active",
          "deleted",
          "createdAt",
          "updatedAt",
          "createdBy",
          "updatedBy",
          "addresses"
        ]
      },
      "ParticipantSettings": {
        "type": "object",
        "properties": {
          "supplier": {
            "type": "object",
            "properties": {
              "canCancelBookings": {
                "type": "boolean",
                "description": "Suppliers can cancel upcoming sessions they are assigned to.",
                "example": false
              },
              "cancelNoticeHours": {
                "type": "integer",
                "minimum": 0,
                "maximum": 8760,
                "description": "Minimum hours before the session starts that this action is still allowed. 0 = allowed any time before the start.",
                "example": 24
              },
              "canRescheduleBookings": {
                "type": "boolean",
                "description": "Suppliers can move an upcoming session to another time (same supplier).",
                "example": true
              },
              "rescheduleNoticeHours": {
                "type": "integer",
                "minimum": 0,
                "maximum": 8760,
                "description": "Minimum hours before the session starts that this action is still allowed. 0 = allowed any time before the start.",
                "example": 24
              },
              "canSeeClientLastName": {
                "type": "boolean",
                "description": "When false, suppliers see the client first name and last initial only.",
                "example": true
              },
              "canSeeClientEmail": {
                "type": "boolean",
                "description": "Suppliers can see the client email address.",
                "example": false
              },
              "canSeeClientPhone": {
                "type": "boolean",
                "description": "Suppliers can see the client phone number.",
                "example": false
              }
            },
            "required": [
              "canCancelBookings",
              "cancelNoticeHours",
              "canRescheduleBookings",
              "rescheduleNoticeHours",
              "canSeeClientLastName",
              "canSeeClientEmail",
              "canSeeClientPhone"
            ],
            "description": "What suppliers may do with, and see on, bookings of this service.",
            "example": {
              "canCancelBookings": false,
              "cancelNoticeHours": 24,
              "canRescheduleBookings": true,
              "rescheduleNoticeHours": 24,
              "canSeeClientLastName": true,
              "canSeeClientEmail": false,
              "canSeeClientPhone": false
            }
          },
          "client": {
            "type": "object",
            "properties": {
              "canRescheduleBookings": {
                "type": "boolean",
                "description": "Clients can move their own upcoming sessions to another available time.",
                "example": true
              },
              "rescheduleNoticeHours": {
                "type": "integer",
                "minimum": 0,
                "maximum": 8760,
                "description": "Minimum hours before the session starts that this action is still allowed. 0 = allowed any time before the start.",
                "example": 24
              },
              "participantDisplay": {
                "type": "string",
                "enum": ["HIDDEN", "FIRST_NAME", "FULL"],
                "description": "How participants are named to clients on their own bookings: FULL (full names), FIRST_NAME (first names only) or HIDDEN (no names; a count such as \"2 participants\").",
                "example": "FULL"
              }
            },
            "required": ["canRescheduleBookings", "rescheduleNoticeHours"],
            "description": "What clients may do with, and see on, their own bookings of this service. Clients cannot cancel.",
            "example": {
              "canRescheduleBookings": true,
              "rescheduleNoticeHours": 24,
              "participantDisplay": "FULL"
            }
          }
        },
        "required": ["supplier", "client"],
        "description": "Participant interaction settings: what suppliers and clients may do with, and see on, bookings of this service. Replaced whole on update — send every field, except `client.participantDisplay`: omitted, it keeps its stored value. Enforced for supplier- and client-role callers; API-key (integrator) calls act for the business and are not restricted by it.",
        "example": {
          "supplier": {
            "canCancelBookings": false,
            "cancelNoticeHours": 24,
            "canRescheduleBookings": true,
            "rescheduleNoticeHours": 24,
            "canSeeClientLastName": true,
            "canSeeClientEmail": false,
            "canSeeClientPhone": false
          },
          "client": {
            "canRescheduleBookings": true,
            "rescheduleNoticeHours": 24,
            "participantDisplay": "FULL"
          }
        }
      },
      "SiteEventsAccepted": {
        "type": "object",
        "properties": {
          "accepted": {
            "type": "integer",
            "description": "Events accepted and recorded. `accepted + rejected.length` is the number sent. When nothing could be recorded the answer is 503, not 202, so retry on it.",
            "example": 41
          },
          "duplicates": {
            "type": "integer",
            "description": "Always 0 for now. A repeated `eventId` is accepted and counted once by the rollup, so a retry never double-counts; this field will report what the rollup collapsed.",
            "example": 0
          },
          "rejected": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SiteEventRejection"
            },
            "description": "The events not accepted, in batch order. Fix and resend only these."
          }
        },
        "required": ["accepted", "duplicates", "rejected"]
      },
      "SiteEventRejection": {
        "type": "object",
        "properties": {
          "index": {
            "type": "integer",
            "description": "The position of the rejected element in `events`, 0-based.",
            "example": 3
          },
          "eventId": {
            "type": "string",
            "nullable": true,
            "description": "Its `eventId`, or null when the element had none.",
            "example": "clk_9d7e1f0a-2b4c-4d8e-9f3a-6b5c4d3e2f1a"
          },
          "code": {
            "type": "string",
            "enum": [
              "INVALID_EVENT",
              "UNKNOWN_SUPPLIER",
              "OCCURRED_AT_TOO_OLD",
              "OCCURRED_AT_IN_FUTURE"
            ],
            "description": "`INVALID_EVENT`: the element does not match its type's shape (`message` says where). `UNKNOWN_SUPPLIER`: a `supplierId` is not in this project. `OCCURRED_AT_TOO_OLD`: older than 72 hours (400 days with `events:import`). `OCCURRED_AT_IN_FUTURE`: more than 24 hours ahead.",
            "example": "UNKNOWN_SUPPLIER"
          },
          "message": {
            "type": "string",
            "description": "What was wrong, for a person.",
            "example": "supplier sup_01kv60qh3m7wznp8s0d2rk9abc is not in this project"
          }
        },
        "required": ["index", "eventId", "code", "message"]
      },
      "SiteEventsBatch": {
        "type": "object",
        "properties": {
          "events": {
            "type": "array",
            "items": {
              "type": "object",
              "allOf": [
                {
                  "$ref": "#/components/schemas/SiteEvent"
                }
              ],
              "description": "One site event. `type` picks the shape: `opportunity`, `impression`, `click`, `profile_view`, `coverage_miss` or `search.rendered`. An element that does not match its shape is rejected on its own in the 202 body, never the whole batch."
            },
            "minItems": 1,
            "maxItems": 500,
            "example": [
              {
                "eventId": "lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b",
                "type": "search.rendered",
                "occurredAt": "2026-10-03T14:05:10.020Z",
                "sessionKey": "sess-example-01",
                "searchId": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n",
                "surface": "results",
                "path": "/en-ca/book/results",
                "suppliers": [
                  {
                    "supplierId": "sup_01kv60qh3m7wznp8s0d2rk9abc",
                    "position": 0
                  },
                  {
                    "supplierId": "sup_01kv60qh3m7wznp8s0d2rk9def",
                    "position": 1
                  }
                ]
              },
              {
                "eventId": "imp_2b7e1d5c-9f4a-4b8e-a3c6-7d0e2f1a9b4c",
                "type": "impression",
                "occurredAt": "2026-10-03T14:05:11.900Z",
                "sessionKey": "sess-example-01",
                "listId": "lst_7f3b2c9e-4a1d-4e7f-9b3a-2c5d8e1f0a6b",
                "supplierId": "sup_01kv60qh3m7wznp8s0d2rk9def",
                "position": 1
              },
              {
                "eventId": "clk_9d7e1f0a-2b4c-4d8e-9f3a-6b5c4d3e2f1a",
                "type": "click",
                "occurredAt": "2026-10-03T14:05:20.004Z",
                "sessionKey": "sess-example-01",
                "impressionId": "imp_2b7e1d5c-9f4a-4b8e-a3c6-7d0e2f1a9b4c",
                "supplierId": "sup_01kv60qh3m7wznp8s0d2rk9def"
              }
            ],
            "description": "The events, at most 500 per request (and 256 KB in all). Each is validated on its own."
          }
        },
        "required": ["events"]
      }
    },
    "parameters": {}
  },
  "paths": {
    "/v1/projects/{projectId}/events/beacon": {
      "post": {
        "tags": ["Events"],
        "summary": "Report site events straight from the browser (publishable key, no response body)",
        "description": "The browser path for the same events as `POST /events`, for sites without a server of their own and for MarketBox’s own widget. Built for `navigator.sendBeacon` and `fetch(…, { keepalive: true })` on a page that may be closing, so nothing about it needs a header: the credential is the publishable key in `?key=pk_…`, the body may be `text/plain` as well as `application/json` (no CORS preflight), and the answer is 204 with no body. `@mb-core/insights-beacon` does all of this for you.\n\n**The publishable key** is minted with the application and shown on the API Access screen beside the API key. It is public by design — it ships in your page — and can only do this: send events, from the exact origins listed on the application (`https://book.acme.com`, never `*`). The browser’s `Origin` header must be one of them; a missing or other origin is refused (403). Keep the API key on your server; it is never accepted here (401).\n\n**Limits.** At most 50 events and 64 KB per beacon (413 past either, nothing read). About 50 beacons a second per key, with bursts of 100 (429 past that). Each event is validated on its own exactly as on `POST /events`, with the same rules: `occurredAt` within 24 hours ahead and 72 hours back, supplier ids of this project, a place as an H3 cell or `lat`/`lng` reduced on receipt. A rejected event is dropped silently (the 204 says nothing); send from your server with `POST /events` when you want the rejections back. Events are stored with `channel: \"browser\"`; a `searchId` is kept as sent.",
        "security": [],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "description": "The application’s publishable key, `pk_…`, from the dashboard’s API Access screen. It is public by design and may only send events, from the origins listed on the application. An API key is never accepted here (401).",
              "example": "pk_01k7q3x9h4e8rb2d6m0z5a7c1n"
            },
            "required": true,
            "description": "The application’s publishable key, `pk_…`, from the dashboard’s API Access screen. It is public by design and may only send events, from the origins listed on the application. An API key is never accepted here (401).",
            "name": "key",
            "in": "query"
          }
        ],
        "requestBody": {
          "description": "The batch of events, as JSON. Sent as `text/plain` by a beacon.",
          "required": true,
          "content": {
            "text/plain": {
              "schema": {
                "$ref": "#/components/schemas/SiteEventsBeaconBatch"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SiteEventsBeaconBatch"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "The beacon was read; accepted events are recorded. No body."
          },
          "400": {
            "description": "Not a batch: the body is not JSON or has no `events` array",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "No publishable key in `?key=`, or not a live one (an API key is never accepted here)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The `Origin` is missing or not in the application’s allowlist, or the key belongs to another project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "413": {
            "description": "Over 50 events or 64 KB; nothing was read",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "429": {
            "description": "Too many beacons from this key; retry after a second",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "503": {
            "description": "MarketBox could not check the key or the suppliers; nothing was recorded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/access": {
      "get": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Whether the signed-in person may use the supplier plane, and why not",
        "description": "Answers 200 for every signed-in person, with `allowed` and a `reasonCode`; it never answers 4xx for a person-level outcome. Call it on sign-in, and use the plane with the returned `supplierId` only when `allowed` is true; otherwise show `message`. `reasonCode` is one of: `SUPPLIER_ACTIVE` (allowed), `SUPPLIER_RECORD_INACTIVE`, `NO_ACCOUNT`, `NOT_A_MEMBER`, `MEMBERSHIP_INACTIVE`, `NO_SUPPLIER_ROLE` and `SUPPLIER_NOT_LINKED`. The other `/suppliers/me` routes refuse with the same codes and messages. It describes the person: `X-MB-Acting-Role` is ignored, and `roles` lists every role they hold here. Only the app’s credentials still fail: a missing or invalid user token (401), a key without standard access (403 `CAPABILITY_NOT_GRANTED`), or a project outside the key’s scope (403). Requires the API key and the person’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "The person’s access",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SupplierPlaneAccess"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key lacks standard access (CAPABILITY_NOT_GRANTED), or cannot access this project (FORBIDDEN)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Project not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/bookings": {
      "get": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "List the signed-in supplier’s bookings",
        "description": "Every booking assigned to the supplier the user token resolves to, in the window — the rows the MarketBox dashboard shows them under My Bookings, built by the same code. Each row carries `viewerActions` (what the supplier may do with it now, by the service’s participant settings and the server’s clock) and, with `expand`, the client as the settings allow the supplier to see them, the services, the package position, the location, the participants and the supplier’s own attendance report. Not paginated: the whole window is returned, so keep windows short (a day or a week). Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time",
              "description": "Earliest booking start to include (ISO 8601 instant, UTC). A single day is one day’s window.",
              "example": "2026-10-19T00:00:00.000Z"
            },
            "required": false,
            "description": "Earliest booking start to include (ISO 8601 instant, UTC). A single day is one day’s window.",
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time",
              "description": "Latest booking start to include (ISO 8601 instant, UTC).",
              "example": "2026-10-26T00:00:00.000Z"
            },
            "required": false,
            "description": "Latest booking start to include (ISO 8601 instant, UTC).",
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "SCHEDULED",
                "STARTED",
                "AWAITING_CONFIRMATION",
                "DISPUTED",
                "COMPLETED",
                "CANCELLED",
                "CLIENT_NO_SHOW",
                "SUPPLIER_NO_SHOW",
                "NO_SHOW"
              ],
              "description": "Only bookings in this status.",
              "example": "SCHEDULED"
            },
            "required": false,
            "description": "Only bookings in this status.",
            "name": "status",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated set of expansions, any order: client, services, package, location, participants, myReport. Each adds one optional key, absent unless requested. Unknown values are rejected. Every value except `client` requires startDate and endDate, at most 93 days apart.",
              "example": "client,services,location,participants,myReport"
            },
            "required": false,
            "description": "Comma-separated set of expansions, any order: client, services, package, location, participants, myReport. Each adds one optional key, absent unless requested. Unknown values are rejected. Every value except `client` requires startDate and endDate, at most 93 days apart.",
            "name": "expand",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Bookings list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "projectId": {
                            "type": "string"
                          },
                          "tenantId": {
                            "type": "string"
                          },
                          "bookingId": {
                            "type": "string"
                          },
                          "seriesId": {
                            "type": "string",
                            "nullable": true
                          },
                          "occurrenceLocalDate": {
                            "type": "string",
                            "nullable": true
                          },
                          "isException": {
                            "type": "boolean"
                          },
                          "supplierId": {
                            "type": "string",
                            "nullable": true
                          },
                          "clientId": {
                            "type": "string"
                          },
                          "packageOrderItemId": {
                            "type": "string",
                            "nullable": true
                          },
                          "bookingStartUtc": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "bookingEndUtc": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "bookingTz": {
                            "type": "string"
                          },
                          "bookingLocalDate": {
                            "type": "string"
                          },
                          "bookingLocalStartTime": {
                            "type": "string"
                          },
                          "bookingLocalEndTime": {
                            "type": "string"
                          },
                          "bookingLocalEndDate": {
                            "type": "string"
                          },
                          "locale": {
                            "type": "string"
                          },
                          "attribution": {
                            "type": "object",
                            "properties": {
                              "searchId": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 128,
                                "description": "The `searchId` of the MarketBox search response the buyer booked from — the `X-MB-Search-Id` header / body field of every search route. Stored as given; a value MarketBox never issued is kept but not trusted.",
                                "example": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
                              },
                              "sessionKey": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 64,
                                "description": "The same opaque per-session key you send with site events, at most 64 characters. Never an email, IP or user id.",
                                "example": "sess-example-01"
                              },
                              "surface": {
                                "type": "string",
                                "enum": [
                                  "home",
                                  "results",
                                  "listing",
                                  "site_search",
                                  "profile",
                                  "widget",
                                  "assistant",
                                  "other"
                                ],
                                "description": "Where on your site the buyer started the purchase.",
                                "example": "results"
                              }
                            },
                            "additionalProperties": false,
                            "description": "Which search and site session this purchase came from. Optional; set once on the order and copied onto every booking it funds. See the search-log guide, \"Booking attribution\"."
                          },
                          "locationType": {
                            "type": "string",
                            "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"]
                          },
                          "locationId": {
                            "type": "string",
                            "nullable": true
                          },
                          "latitude": {
                            "type": "number",
                            "nullable": true
                          },
                          "longitude": {
                            "type": "number",
                            "nullable": true
                          },
                          "address": {
                            "$ref": "#/components/schemas/Address"
                          },
                          "capacity": {
                            "type": "integer",
                            "minimum": 0,
                            "exclusiveMinimum": true
                          },
                          "participantCount": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "waitlistCount": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "isGroupBooking": {
                            "type": "boolean"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "SCHEDULED",
                              "STARTED",
                              "AWAITING_CONFIRMATION",
                              "DISPUTED",
                              "COMPLETED",
                              "CANCELLED",
                              "CLIENT_NO_SHOW",
                              "SUPPLIER_NO_SHOW",
                              "NO_SHOW"
                            ]
                          },
                          "statusUpdatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "statusUpdatedBy": {
                            "type": "string"
                          },
                          "statusUpdatedByCapacity": {
                            "type": "string",
                            "enum": [
                              "ADMIN",
                              "SUPPLIER",
                              "CLIENT",
                              "SYSTEM",
                              "API"
                            ]
                          },
                          "cancellationReason": {
                            "type": "string",
                            "nullable": true
                          },
                          "cancelledBy": {
                            "type": "string",
                            "nullable": true
                          },
                          "cancellationInitiatedBy": {
                            "type": "string",
                            "enum": ["CLIENT", "SUPPLIER", "BUSINESS"]
                          },
                          "cancellationReasonCode": {
                            "type": "string",
                            "enum": [
                              "CLIENT_REQUESTED",
                              "CLIENT_UNWELL",
                              "SUPPLIER_UNAVAILABLE",
                              "WEATHER",
                              "FACILITY_UNAVAILABLE",
                              "BOOKED_IN_ERROR",
                              "OTHER"
                            ]
                          },
                          "creditTreatment": {
                            "type": "string",
                            "enum": [
                              "RETURN",
                              "FORFEIT",
                              "REFUND_ORIGINAL_PAYMENT",
                              "NOT_APPLICABLE"
                            ]
                          },
                          "durationOverrideMinutes": {
                            "type": "integer",
                            "minimum": 0,
                            "exclusiveMinimum": true,
                            "maximum": 1440
                          },
                          "durationOverrideReason": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 500
                          },
                          "counts": {
                            "type": "object",
                            "properties": {
                              "services": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "notes": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "participants": {
                                "type": "integer",
                                "minimum": 0
                              }
                            },
                            "required": ["services", "notes", "participants"]
                          },
                          "deleted": {
                            "type": "boolean"
                          },
                          "version": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "createdBy": {
                            "type": "string"
                          },
                          "updatedBy": {
                            "type": "string"
                          },
                          "client": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "displayName": {
                                "type": "string",
                                "description": "The client as this viewer may see them."
                              },
                              "email": {
                                "type": "string",
                                "description": "Only when the service shows suppliers the email."
                              },
                              "phone": {
                                "type": "string",
                                "description": "Only when the service shows suppliers the phone."
                              }
                            },
                            "required": ["displayName"],
                            "description": "The client, as the booking’s participant settings allow this viewer to see them. Present only with `expand=client`; null when the profile is unreachable."
                          },
                          "viewerActions": {
                            "type": "object",
                            "properties": {
                              "canCancel": {
                                "type": "boolean"
                              },
                              "canReschedule": {
                                "type": "boolean"
                              },
                              "blockedReason": {
                                "type": "string"
                              }
                            },
                            "required": ["canCancel", "canReschedule"],
                            "description": "What this viewer may do with the booking now, by the server’s clock and the service’s participant settings."
                          },
                          "services": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "name": {
                                "type": "string",
                                "description": "The first service’s name."
                              },
                              "count": {
                                "type": "integer",
                                "description": "How many services the booking has."
                              }
                            },
                            "required": ["name", "count"],
                            "description": "The first service's name and how many services the booking has."
                          },
                          "package": {
                            "oneOf": [
                              {
                                "type": "object",
                                "properties": {
                                  "credit": {
                                    "type": "string",
                                    "enum": ["HELD"]
                                  },
                                  "position": {
                                    "type": "integer"
                                  },
                                  "total": {
                                    "type": "integer"
                                  }
                                },
                                "required": ["credit", "position", "total"]
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "credit": {
                                    "type": "string",
                                    "enum": ["RETURNED"]
                                  },
                                  "total": {
                                    "type": "integer"
                                  }
                                },
                                "required": ["credit", "total"]
                              },
                              {
                                "nullable": true
                              }
                            ],
                            "description": "Where the booking sits in its package — \"Booking 3 of 10\". `HELD`: the booking holds one of the package's credits (booked, delivered, or forfeited by a late cancel or no-show), and `position` is its 1-based place among the credit-holding bookings by start time. `RETURNED`: it was cancelled and its credit went back on the package, so it has no place. `total` is the package's PURCHASED credit count; a position above it means the package holds more sessions than were sold (migrated data only). Null when the booking has no package, or when its credit record or the purchased count is unreachable."
                          },
                          "location": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "name": {
                                "type": "string",
                                "description": "The location’s name — what staff call it."
                              },
                              "addressOneLine": {
                                "type": "string",
                                "nullable": true,
                                "description": "Its address on one line, when known."
                              }
                            },
                            "required": ["name", "addressOneLine"],
                            "description": "The company location's name — what staff call it — for PHYSICAL bookings."
                          },
                          "participants": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "labels": {
                                "type": "array",
                                "nullable": true,
                                "items": {
                                  "type": "string"
                                },
                                "description": "Names as this viewer may see them."
                              },
                              "count": {
                                "type": "integer",
                                "description": "Participants this viewer may see on the booking."
                              }
                            },
                            "required": ["labels", "count"],
                            "description": "The participants this caller may see, named as the service allows (client `participantDisplay`, or the supplier projection). `labels: null` = show a placeholder from `count`, never an empty list."
                          },
                          "myReport": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "reportable": {
                                "type": "boolean",
                                "description": "Whether a new report is taken now (server clock)."
                              },
                              "filed": {
                                "type": "boolean",
                                "description": "Whether this caller has filed their own report."
                              },
                              "attended": {
                                "type": "boolean",
                                "nullable": true,
                                "description": "The filed answer; null when not filed."
                              }
                            },
                            "required": ["reportable", "filed", "attended"],
                            "description": "The caller's OWN attendance report: whether a new one is taken now (server clock), whether they filed one, and its answer."
                          }
                        },
                        "required": [
                          "projectId",
                          "tenantId",
                          "bookingId",
                          "supplierId",
                          "clientId",
                          "bookingStartUtc",
                          "bookingEndUtc",
                          "bookingTz",
                          "bookingLocalDate",
                          "bookingLocalStartTime",
                          "bookingLocalEndTime",
                          "bookingLocalEndDate",
                          "locationType",
                          "locationId",
                          "latitude",
                          "longitude",
                          "address",
                          "capacity",
                          "participantCount",
                          "waitlistCount",
                          "isGroupBooking",
                          "status",
                          "statusUpdatedAt",
                          "counts",
                          "deleted",
                          "version",
                          "createdAt",
                          "updatedAt",
                          "createdBy",
                          "updatedBy",
                          "viewerActions"
                        ]
                      }
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Unknown expand value, or a missing/oversized window",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such booking of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/bookings/{bookingId}": {
      "get": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "One of the signed-in supplier’s bookings, with services and participants",
        "description": "The booking as the dashboard’s own-booking detail shows it: the row with the client as the participant settings allow, its service lines, and its participants named as the supplier may see them. No notes (staff-authored) and no other party’s report. A booking that is not the supplier’s is a 404, indistinguishable from a missing one. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "The booking",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "booking": {
                          "type": "object",
                          "properties": {
                            "projectId": {
                              "type": "string"
                            },
                            "tenantId": {
                              "type": "string"
                            },
                            "bookingId": {
                              "type": "string"
                            },
                            "seriesId": {
                              "type": "string",
                              "nullable": true
                            },
                            "occurrenceLocalDate": {
                              "type": "string",
                              "nullable": true
                            },
                            "isException": {
                              "type": "boolean"
                            },
                            "supplierId": {
                              "type": "string",
                              "nullable": true
                            },
                            "clientId": {
                              "type": "string"
                            },
                            "packageOrderItemId": {
                              "type": "string",
                              "nullable": true
                            },
                            "bookingStartUtc": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "bookingEndUtc": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "bookingTz": {
                              "type": "string"
                            },
                            "bookingLocalDate": {
                              "type": "string"
                            },
                            "bookingLocalStartTime": {
                              "type": "string"
                            },
                            "bookingLocalEndTime": {
                              "type": "string"
                            },
                            "bookingLocalEndDate": {
                              "type": "string"
                            },
                            "locale": {
                              "type": "string"
                            },
                            "attribution": {
                              "type": "object",
                              "properties": {
                                "searchId": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 128,
                                  "description": "The `searchId` of the MarketBox search response the buyer booked from — the `X-MB-Search-Id` header / body field of every search route. Stored as given; a value MarketBox never issued is kept but not trusted.",
                                  "example": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
                                },
                                "sessionKey": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 64,
                                  "description": "The same opaque per-session key you send with site events, at most 64 characters. Never an email, IP or user id.",
                                  "example": "sess-example-01"
                                },
                                "surface": {
                                  "type": "string",
                                  "enum": [
                                    "home",
                                    "results",
                                    "listing",
                                    "site_search",
                                    "profile",
                                    "widget",
                                    "assistant",
                                    "other"
                                  ],
                                  "description": "Where on your site the buyer started the purchase.",
                                  "example": "results"
                                }
                              },
                              "additionalProperties": false,
                              "description": "Which search and site session this purchase came from. Optional; set once on the order and copied onto every booking it funds. See the search-log guide, \"Booking attribution\"."
                            },
                            "locationType": {
                              "type": "string",
                              "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"]
                            },
                            "locationId": {
                              "type": "string",
                              "nullable": true
                            },
                            "latitude": {
                              "type": "number",
                              "nullable": true
                            },
                            "longitude": {
                              "type": "number",
                              "nullable": true
                            },
                            "address": {
                              "$ref": "#/components/schemas/Address"
                            },
                            "capacity": {
                              "type": "integer",
                              "minimum": 0,
                              "exclusiveMinimum": true
                            },
                            "participantCount": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "waitlistCount": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "isGroupBooking": {
                              "type": "boolean"
                            },
                            "status": {
                              "type": "string",
                              "enum": [
                                "SCHEDULED",
                                "STARTED",
                                "AWAITING_CONFIRMATION",
                                "DISPUTED",
                                "COMPLETED",
                                "CANCELLED",
                                "CLIENT_NO_SHOW",
                                "SUPPLIER_NO_SHOW",
                                "NO_SHOW"
                              ]
                            },
                            "statusUpdatedAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "statusUpdatedBy": {
                              "type": "string"
                            },
                            "statusUpdatedByCapacity": {
                              "type": "string",
                              "enum": [
                                "ADMIN",
                                "SUPPLIER",
                                "CLIENT",
                                "SYSTEM",
                                "API"
                              ]
                            },
                            "cancellationReason": {
                              "type": "string",
                              "nullable": true
                            },
                            "cancelledBy": {
                              "type": "string",
                              "nullable": true
                            },
                            "cancellationInitiatedBy": {
                              "type": "string",
                              "enum": ["CLIENT", "SUPPLIER", "BUSINESS"]
                            },
                            "cancellationReasonCode": {
                              "type": "string",
                              "enum": [
                                "CLIENT_REQUESTED",
                                "CLIENT_UNWELL",
                                "SUPPLIER_UNAVAILABLE",
                                "WEATHER",
                                "FACILITY_UNAVAILABLE",
                                "BOOKED_IN_ERROR",
                                "OTHER"
                              ]
                            },
                            "creditTreatment": {
                              "type": "string",
                              "enum": [
                                "RETURN",
                                "FORFEIT",
                                "REFUND_ORIGINAL_PAYMENT",
                                "NOT_APPLICABLE"
                              ]
                            },
                            "durationOverrideMinutes": {
                              "type": "integer",
                              "minimum": 0,
                              "exclusiveMinimum": true,
                              "maximum": 1440
                            },
                            "durationOverrideReason": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 500
                            },
                            "counts": {
                              "type": "object",
                              "properties": {
                                "services": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "notes": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "participants": {
                                  "type": "integer",
                                  "minimum": 0
                                }
                              },
                              "required": ["services", "notes", "participants"]
                            },
                            "deleted": {
                              "type": "boolean"
                            },
                            "version": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "createdAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "updatedAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "createdBy": {
                              "type": "string"
                            },
                            "updatedBy": {
                              "type": "string"
                            },
                            "client": {
                              "type": "object",
                              "nullable": true,
                              "properties": {
                                "displayName": {
                                  "type": "string",
                                  "description": "The client as this viewer may see them."
                                },
                                "email": {
                                  "type": "string",
                                  "description": "Only when the service shows suppliers the email."
                                },
                                "phone": {
                                  "type": "string",
                                  "description": "Only when the service shows suppliers the phone."
                                }
                              },
                              "required": ["displayName"],
                              "description": "The client, as the booking’s participant settings allow this viewer to see them. Present only with `expand=client`; null when the profile is unreachable."
                            },
                            "viewerActions": {
                              "type": "object",
                              "properties": {
                                "canCancel": {
                                  "type": "boolean"
                                },
                                "canReschedule": {
                                  "type": "boolean"
                                },
                                "blockedReason": {
                                  "type": "string"
                                }
                              },
                              "required": ["canCancel", "canReschedule"],
                              "description": "What this viewer may do with the booking now, by the server’s clock and the service’s participant settings."
                            }
                          },
                          "required": [
                            "projectId",
                            "tenantId",
                            "bookingId",
                            "supplierId",
                            "clientId",
                            "bookingStartUtc",
                            "bookingEndUtc",
                            "bookingTz",
                            "bookingLocalDate",
                            "bookingLocalStartTime",
                            "bookingLocalEndTime",
                            "bookingLocalEndDate",
                            "locationType",
                            "locationId",
                            "latitude",
                            "longitude",
                            "address",
                            "capacity",
                            "participantCount",
                            "waitlistCount",
                            "isGroupBooking",
                            "status",
                            "statusUpdatedAt",
                            "counts",
                            "deleted",
                            "version",
                            "createdAt",
                            "updatedAt",
                            "createdBy",
                            "updatedBy",
                            "viewerActions"
                          ]
                        },
                        "services": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "projectId": {
                                "type": "string"
                              },
                              "bookingId": {
                                "type": "string"
                              },
                              "bookingServiceId": {
                                "type": "string"
                              },
                              "businessModelType": {
                                "type": "string",
                                "enum": [
                                  "SINGLE_BOOKING",
                                  "PACKAGE",
                                  "SCHEDULED_PACKAGE",
                                  "SCHEDULED_SUBSCRIPTION",
                                  "FLEXIBLE_SUBSCRIPTION"
                                ],
                                "description": "How the service is sold. SINGLE_BOOKING is one booking at a time; PACKAGE sells prepaid credits drawn down by later bookings; the SCHEDULED_* and FLEXIBLE_* variants add recurrence and subscription billing. This drives which order item skuType applies."
                              },
                              "offeringSnapshot": {
                                "type": "object",
                                "properties": {
                                  "serviceId": {
                                    "type": "string",
                                    "minLength": 1
                                  },
                                  "offeringId": {
                                    "type": "string",
                                    "minLength": 1
                                  },
                                  "name": {
                                    "type": "object",
                                    "additionalProperties": {
                                      "type": "string"
                                    }
                                  },
                                  "price": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "duration": {
                                    "oneOf": [
                                      {
                                        "type": "object",
                                        "properties": {
                                          "type": {
                                            "type": "string",
                                            "enum": ["FIXED"]
                                          },
                                          "minutes": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "exclusiveMinimum": true
                                          }
                                        },
                                        "required": ["type", "minutes"]
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "type": {
                                            "type": "string",
                                            "enum": ["FLEXIBLE"]
                                          },
                                          "defaultMinutes": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "exclusiveMinimum": true
                                          },
                                          "minMinutes": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "exclusiveMinimum": true
                                          },
                                          "stepMinutes": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "exclusiveMinimum": true
                                          },
                                          "pricePerStep": {
                                            "$ref": "#/components/schemas/Money"
                                          }
                                        },
                                        "required": [
                                          "type",
                                          "defaultMinutes",
                                          "minMinutes",
                                          "stepMinutes"
                                        ]
                                      }
                                    ]
                                  },
                                  "attributeValues": {
                                    "type": "array",
                                    "items": {
                                      "type": "object",
                                      "properties": {
                                        "attributeId": {
                                          "type": "string",
                                          "minLength": 1
                                        },
                                        "attributeNameSnapshot": {
                                          "type": "object",
                                          "additionalProperties": {
                                            "type": "string"
                                          }
                                        },
                                        "attributeType": {
                                          "type": "string",
                                          "enum": ["STRING", "NUMBER", "ENUM"],
                                          "description": "Value type of a service attribute. ENUM attributes carry an allowed-values list."
                                        },
                                        "value": {
                                          "anyOf": [
                                            {
                                              "type": "object",
                                              "additionalProperties": {
                                                "type": "string"
                                              }
                                            },
                                            {
                                              "type": "number"
                                            },
                                            {
                                              "type": "string"
                                            }
                                          ]
                                        },
                                        "valueId": {
                                          "type": "string"
                                        }
                                      },
                                      "required": [
                                        "attributeId",
                                        "attributeNameSnapshot",
                                        "attributeType"
                                      ]
                                    }
                                  }
                                },
                                "required": [
                                  "serviceId",
                                  "offeringId",
                                  "price",
                                  "duration",
                                  "attributeValues"
                                ]
                              },
                              "quantity": {
                                "type": "integer",
                                "minimum": 0,
                                "exclusiveMinimum": true
                              },
                              "durationMinutes": {
                                "type": "integer",
                                "minimum": 0,
                                "exclusiveMinimum": true
                              },
                              "unitPrice": {
                                "$ref": "#/components/schemas/Money"
                              },
                              "lineAmount": {
                                "$ref": "#/components/schemas/Money"
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "SCHEDULED",
                                  "IN_PROGRESS",
                                  "COMPLETED",
                                  "CANCELLED",
                                  "NO_SHOW"
                                ]
                              },
                              "deleted": {
                                "type": "boolean"
                              },
                              "createdAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "updatedAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "createdBy": {
                                "type": "string"
                              },
                              "updatedBy": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "projectId",
                              "bookingId",
                              "bookingServiceId",
                              "businessModelType",
                              "offeringSnapshot",
                              "quantity",
                              "durationMinutes",
                              "unitPrice",
                              "lineAmount",
                              "status",
                              "deleted",
                              "createdAt",
                              "updatedAt",
                              "createdBy",
                              "updatedBy"
                            ]
                          },
                          "description": "The booking’s service lines."
                        },
                        "participants": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "projectId": {
                                "type": "string"
                              },
                              "bookingId": {
                                "type": "string"
                              },
                              "clientId": {
                                "type": "string"
                              },
                              "participantStatus": {
                                "type": "string",
                                "enum": [
                                  "REGISTERED",
                                  "WAITLISTED",
                                  "CANCELLED",
                                  "NO_SHOW",
                                  "ATTENDED"
                                ]
                              },
                              "checkInStatus": {
                                "type": "string",
                                "enum": ["PENDING", "CHECKED_IN", "NO_SHOW"]
                              },
                              "checkInAt": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time"
                              },
                              "registeredAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "waitlistPosition": {
                                "type": "integer",
                                "nullable": true,
                                "minimum": 0
                              },
                              "deleted": {
                                "type": "boolean"
                              },
                              "createdAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "updatedAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "createdBy": {
                                "type": "string"
                              },
                              "updatedBy": {
                                "type": "string"
                              },
                              "displayName": {
                                "type": "string",
                                "description": "The participant named as this caller may see them (client `participantDisplay`, or the supplier projection). Absent when the name may not be shown or is unknown — render a placeholder, never the clientId."
                              }
                            },
                            "required": [
                              "projectId",
                              "bookingId",
                              "clientId",
                              "participantStatus",
                              "checkInStatus",
                              "registeredAt",
                              "deleted",
                              "createdAt",
                              "updatedAt",
                              "createdBy",
                              "updatedBy"
                            ]
                          },
                          "description": "The participants this viewer may see."
                        }
                      },
                      "required": ["booking", "services", "participants"]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such booking of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "patch": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Move one of the signed-in supplier’s bookings to another time",
        "description": "The supplier moves their own booking, exactly as from the MarketBox dashboard: time only, keeping its length, supplier, location and zone. Only a SCHEDULED booking, only when its service lets suppliers reschedule (403 `PARTICIPANT_ACTION_DISABLED`), outside the notice window (409 `NOTICE_WINDOW_PASSED`), to a new start also outside it (422 `NEW_START_INSIDE_NOTICE_WINDOW`). The new slot must be free on the supplier’s calendar, inside their working hours and not in blocked time (409 `SLOT_UNAVAILABLE`, or `SLOT_UNVERIFIABLE` when it could not be checked). The client and the business are emailed. A booking that is not the supplier’s is a 404, indistinguishable from a missing one. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "New start",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "startTime": {
                    "type": "string",
                    "format": "date-time",
                    "description": "The new start, as a UTC instant. The end follows from the booking’s current length; the supplier, location and zone do not change.",
                    "example": "2026-10-19T22:30:00.000Z"
                  }
                },
                "required": ["startTime"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rescheduled booking",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Booking"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error, or (BAD_REQUEST) the booking cannot move to that status or its zone is invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD); or the booking’s service does not let suppliers do this (PARTICIPANT_ACTION_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such booking of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "The booking is not scheduled (BOOKING_NOT_SCHEDULED), changes have closed for it (NOTICE_WINDOW_PASSED), the new time is not available (SLOT_UNAVAILABLE) or could not be checked (SLOT_UNVERIFIABLE), the booking changed since it was read (VERSION_CONFLICT), or the supplier calendar is under heavy contention (OCCUPANCY_CONTENTION; retry)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "422": {
            "description": "The new start is inside the notice window (NEW_START_INSIDE_NOTICE_WINDOW)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/bookings/{bookingId}/reports": {
      "get": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "The signed-in supplier’s own attendance report on one of their bookings",
        "description": "Whether a report may be filed now (by the server’s clock), what each answer would do to the booking if filed now, and the supplier’s report if one is on file — the same view the dashboard drawer reads. The client’s report is never returned. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Own report (null if not filed)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "reporterRole": {
                          "type": "string",
                          "enum": ["CLIENT", "SUPPLIER"],
                          "description": "Which side of the booking the caller reports as."
                        },
                        "reportable": {
                          "type": "boolean",
                          "description": "Whether a report may be filed now, by the server’s clock, whatever the answer."
                        },
                        "ifAttended": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "settlesTo": {
                              "type": "string",
                              "enum": [
                                "SCHEDULED",
                                "STARTED",
                                "AWAITING_CONFIRMATION",
                                "DISPUTED",
                                "COMPLETED",
                                "CANCELLED",
                                "CLIENT_NO_SHOW",
                                "SUPPLIER_NO_SHOW",
                                "NO_SHOW"
                              ],
                              "description": "The status the booking moves to when this answer is filed."
                            },
                            "consequences": {
                              "type": "string",
                              "description": "The transition rule’s consequences key; the dashboard copy is keyed by it."
                            }
                          },
                          "required": ["settlesTo", "consequences"],
                          "description": "What filing `attended: true` would do now, judged from the booking alone; the other party’s report is never read, so a supplier’s attended may still end DISPUTED. null when it moves nothing."
                        },
                        "ifNotAttended": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "settlesTo": {
                              "type": "string",
                              "enum": [
                                "SCHEDULED",
                                "STARTED",
                                "AWAITING_CONFIRMATION",
                                "DISPUTED",
                                "COMPLETED",
                                "CANCELLED",
                                "CLIENT_NO_SHOW",
                                "SUPPLIER_NO_SHOW",
                                "NO_SHOW"
                              ],
                              "description": "The status the booking moves to when this answer is filed."
                            },
                            "consequences": {
                              "type": "string",
                              "description": "The transition rule’s consequences key; the dashboard copy is keyed by it."
                            }
                          },
                          "required": ["settlesTo", "consequences"],
                          "description": "What filing `attended: false` would do now, judged from the booking alone. null when it moves nothing."
                        },
                        "report": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "attended": {
                              "type": "boolean",
                              "description": "The answer on file."
                            },
                            "note": {
                              "type": "string",
                              "description": "The note filed with it, when there was one."
                            },
                            "createdAt": {
                              "type": "string",
                              "description": "When it was filed (ISO 8601 instant)."
                            }
                          },
                          "required": ["attended", "createdAt"],
                          "description": "The caller’s own report, or null when none is filed."
                        }
                      },
                      "required": [
                        "reporterRole",
                        "reportable",
                        "ifAttended",
                        "ifNotAttended",
                        "report"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such booking of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "post": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "File the signed-in supplier’s attendance report on one of their bookings",
        "description": "A self-report: `attended` says whether the SUPPLIER showed up, and settles the booking exactly as filing from the dashboard does — attended → COMPLETED (or DISPUTED, when the client has reported that they did not attend), did not attend → SUPPLIER_NO_SHOW. 201 when filed, 200 when the identical answer was already on file, 409 `REPORT_ALREADY_EXISTS` for a different answer on file, 409 `BOOKING_ALREADY_SETTLED` on a booking already settled, 422 `BOOKING_NOT_REPORTABLE` when the booking is cancelled or has not ended yet. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Did you attend",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "attended": {
                    "type": "boolean",
                    "description": "Whether YOU attended. A self-report: it says nothing about the other party.",
                    "example": true
                  },
                  "note": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "An optional note kept with the report (at most 1000 characters).",
                    "example": "Arrived five minutes late, lesson ran to the full hour."
                  }
                },
                "required": ["attended"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Identical report already on file",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "reporterRole": {
                          "type": "string",
                          "enum": ["CLIENT", "SUPPLIER"],
                          "description": "Which side of the booking the caller reports as."
                        },
                        "reportable": {
                          "type": "boolean",
                          "description": "Whether a report may be filed now, by the server’s clock, whatever the answer."
                        },
                        "ifAttended": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "settlesTo": {
                              "type": "string",
                              "enum": [
                                "SCHEDULED",
                                "STARTED",
                                "AWAITING_CONFIRMATION",
                                "DISPUTED",
                                "COMPLETED",
                                "CANCELLED",
                                "CLIENT_NO_SHOW",
                                "SUPPLIER_NO_SHOW",
                                "NO_SHOW"
                              ],
                              "description": "The status the booking moves to when this answer is filed."
                            },
                            "consequences": {
                              "type": "string",
                              "description": "The transition rule’s consequences key; the dashboard copy is keyed by it."
                            }
                          },
                          "required": ["settlesTo", "consequences"],
                          "description": "What filing `attended: true` would do now, judged from the booking alone; the other party’s report is never read, so a supplier’s attended may still end DISPUTED. null when it moves nothing."
                        },
                        "ifNotAttended": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "settlesTo": {
                              "type": "string",
                              "enum": [
                                "SCHEDULED",
                                "STARTED",
                                "AWAITING_CONFIRMATION",
                                "DISPUTED",
                                "COMPLETED",
                                "CANCELLED",
                                "CLIENT_NO_SHOW",
                                "SUPPLIER_NO_SHOW",
                                "NO_SHOW"
                              ],
                              "description": "The status the booking moves to when this answer is filed."
                            },
                            "consequences": {
                              "type": "string",
                              "description": "The transition rule’s consequences key; the dashboard copy is keyed by it."
                            }
                          },
                          "required": ["settlesTo", "consequences"],
                          "description": "What filing `attended: false` would do now, judged from the booking alone. null when it moves nothing."
                        },
                        "report": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "attended": {
                              "type": "boolean",
                              "description": "The answer on file."
                            },
                            "note": {
                              "type": "string",
                              "description": "The note filed with it, when there was one."
                            },
                            "createdAt": {
                              "type": "string",
                              "description": "When it was filed (ISO 8601 instant)."
                            }
                          },
                          "required": ["attended", "createdAt"],
                          "description": "The caller’s own report, or null when none is filed."
                        }
                      },
                      "required": [
                        "reporterRole",
                        "reportable",
                        "ifAttended",
                        "ifNotAttended",
                        "report"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "201": {
            "description": "Report filed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "reporterRole": {
                          "type": "string",
                          "enum": ["CLIENT", "SUPPLIER"],
                          "description": "Which side of the booking the caller reports as."
                        },
                        "reportable": {
                          "type": "boolean",
                          "description": "Whether a report may be filed now, by the server’s clock, whatever the answer."
                        },
                        "ifAttended": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "settlesTo": {
                              "type": "string",
                              "enum": [
                                "SCHEDULED",
                                "STARTED",
                                "AWAITING_CONFIRMATION",
                                "DISPUTED",
                                "COMPLETED",
                                "CANCELLED",
                                "CLIENT_NO_SHOW",
                                "SUPPLIER_NO_SHOW",
                                "NO_SHOW"
                              ],
                              "description": "The status the booking moves to when this answer is filed."
                            },
                            "consequences": {
                              "type": "string",
                              "description": "The transition rule’s consequences key; the dashboard copy is keyed by it."
                            }
                          },
                          "required": ["settlesTo", "consequences"],
                          "description": "What filing `attended: true` would do now, judged from the booking alone; the other party’s report is never read, so a supplier’s attended may still end DISPUTED. null when it moves nothing."
                        },
                        "ifNotAttended": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "settlesTo": {
                              "type": "string",
                              "enum": [
                                "SCHEDULED",
                                "STARTED",
                                "AWAITING_CONFIRMATION",
                                "DISPUTED",
                                "COMPLETED",
                                "CANCELLED",
                                "CLIENT_NO_SHOW",
                                "SUPPLIER_NO_SHOW",
                                "NO_SHOW"
                              ],
                              "description": "The status the booking moves to when this answer is filed."
                            },
                            "consequences": {
                              "type": "string",
                              "description": "The transition rule’s consequences key; the dashboard copy is keyed by it."
                            }
                          },
                          "required": ["settlesTo", "consequences"],
                          "description": "What filing `attended: false` would do now, judged from the booking alone. null when it moves nothing."
                        },
                        "report": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "attended": {
                              "type": "boolean",
                              "description": "The answer on file."
                            },
                            "note": {
                              "type": "string",
                              "description": "The note filed with it, when there was one."
                            },
                            "createdAt": {
                              "type": "string",
                              "description": "When it was filed (ISO 8601 instant)."
                            }
                          },
                          "required": ["attended", "createdAt"],
                          "description": "The caller’s own report, or null when none is filed."
                        }
                      },
                      "required": [
                        "reporterRole",
                        "reportable",
                        "ifAttended",
                        "ifNotAttended",
                        "report"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such booking of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "A different answer is already on file, or the booking is already settled",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": ["REPORT_ALREADY_EXISTS"]
                        },
                        "message": {
                          "type": "string"
                        },
                        "statusCode": {
                          "type": "number",
                          "enum": [409]
                        },
                        "existing": {
                          "type": "object",
                          "properties": {
                            "attended": {
                              "type": "boolean"
                            }
                          },
                          "required": ["attended"]
                        }
                      },
                      "required": ["code", "message", "statusCode", "existing"]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": ["BOOKING_ALREADY_SETTLED"]
                        },
                        "message": {
                          "type": "string"
                        },
                        "statusCode": {
                          "type": "number",
                          "enum": [409]
                        }
                      },
                      "required": ["code", "message", "statusCode"]
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Booking cannot be reported on now",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/bookings/{bookingId}/cancel": {
      "post": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Cancel one of the signed-in supplier’s bookings",
        "description": "The supplier cancels their own booking, exactly as from the MarketBox dashboard: only a SCHEDULED booking, only when its service lets suppliers cancel (403 `PARTICIPANT_ACTION_DISABLED`), and only outside the service’s notice window (409 `NOTICE_WINDOW_PASSED`). Recorded as supplier-initiated, by the signed-in person; a package session goes back on the package; no refund is made. The client and the business are emailed. A booking that is not the supplier’s is a 404, indistinguishable from a missing one. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Why",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reasonCode": {
                    "type": "string",
                    "enum": [
                      "CLIENT_REQUESTED",
                      "CLIENT_UNWELL",
                      "SUPPLIER_UNAVAILABLE",
                      "WEATHER",
                      "FACILITY_UNAVAILABLE",
                      "BOOKED_IN_ERROR",
                      "OTHER"
                    ],
                    "description": "Why the booking is cancelled. Recorded on the booking’s history.",
                    "example": "SUPPLIER_UNAVAILABLE"
                  },
                  "note": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "Optional free text kept on the booking’s history (at most 1000 characters). Never emailed.",
                    "example": "Pool closed for maintenance that morning."
                  }
                },
                "required": ["reasonCode"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cancelled booking",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Booking"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error, or (BAD_REQUEST) the booking cannot move to that status or its zone is invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD); or the booking’s service does not let suppliers do this (PARTICIPANT_ACTION_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such booking of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "The booking is not scheduled (BOOKING_NOT_SCHEDULED), changes have closed for it (NOTICE_WINDOW_PASSED), or it changed since it was read (VERSION_CONFLICT)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/schedules": {
      "post": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Create a schedule for the signed-in supplier",
        "description": "A new recurring working pattern for the supplier the user token resolves to, exactly as the dashboard creates one: the offerings must be ACTIVE offerings of the supplier’s services, the locations must exist in the project, and an ACTIVE schedule may not overlap another ACTIVE one (409). Omit `timezone` to use the supplier’s profile zone, then the project default. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Schedule data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": ["ACTIVE", "INACTIVE"],
                    "default": "ACTIVE",
                    "description": "ACTIVE rows are offered for booking; INACTIVE rows are kept but offer nothing.",
                    "example": "ACTIVE"
                  },
                  "timezone": {
                    "type": "string",
                    "minLength": 1,
                    "description": "IANA zone the wall-clock times are in. Omit to use the supplier’s profile zone, then the project default (R-11); never UTC by accident.",
                    "example": "America/Toronto"
                  },
                  "startDate": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                    "description": "First calendar day the row applies to, YYYY-MM-DD in its zone.",
                    "example": "2026-01-05"
                  },
                  "endDate": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                    "description": "Last calendar day the row applies to (inclusive), YYYY-MM-DD; on or after startDate.",
                    "example": "2026-12-31"
                  },
                  "rrule": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The recurrence (RFC 5545 RRULE, weekly), expanded per occurrence in the row’s zone.",
                    "example": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE"
                  },
                  "exdates": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                      "example": "2026-07-01"
                    },
                    "default": [],
                    "description": "Calendar days (YYYY-MM-DD) skipped from the recurrence.",
                    "example": []
                  },
                  "weeklyTimeRanges": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "dayOfWeek": {
                          "type": "string",
                          "enum": ["MO", "TU", "WE", "TH", "FR", "SA", "SU"],
                          "description": "The weekday this range falls on, in the row’s zone.",
                          "example": "MO"
                        },
                        "startTime": {
                          "type": "string",
                          "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                          "description": "Wall-clock start, HH:MM in the row’s zone.",
                          "example": "09:00"
                        },
                        "endTime": {
                          "type": "string",
                          "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                          "description": "Wall-clock end, HH:MM in the row’s zone; must differ from startTime.",
                          "example": "17:00"
                        },
                        "crossesMidnight": {
                          "type": "boolean",
                          "description": "True exactly when endTime is earlier than startTime (the range ends next day).",
                          "example": false
                        },
                        "sortOrder": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Display order among the ranges of one day, from 0.",
                          "example": 0
                        }
                      },
                      "required": [
                        "dayOfWeek",
                        "startTime",
                        "endTime",
                        "crossesMidnight",
                        "sortOrder"
                      ]
                    },
                    "minItems": 1,
                    "description": "The working ranges per weekday; at least one.",
                    "example": [
                      {
                        "dayOfWeek": "MO",
                        "startTime": "09:00",
                        "endTime": "17:00",
                        "crossesMidnight": false,
                        "sortOrder": 0
                      }
                    ]
                  },
                  "appliesToAllOfferings": {
                    "type": "boolean",
                    "description": "True = every ACTIVE offering of the supplier’s services; false = exactly serviceOfferingIds.",
                    "example": true
                  },
                  "serviceOfferingIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "example": "off_01kv60qge5eh59ap0gw0pqrrys"
                    },
                    "default": [],
                    "description": "The offerings this schedule serves when appliesToAllOfferings is false; must be ACTIVE offerings of services the supplier provides.",
                    "example": []
                  },
                  "locationRefs": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "locationId": {
                          "type": "string",
                          "minLength": 1,
                          "description": "A location of the project the supplier works at under this schedule.",
                          "example": "loc_01kv60qgnef2kt3pvqgwmkbzfr"
                        },
                        "locationType": {
                          "type": "string",
                          "enum": ["PHYSICAL", "VIRTUAL"],
                          "description": "PHYSICAL (an address) or VIRTUAL (online); must match the location’s own type.",
                          "example": "PHYSICAL"
                        }
                      },
                      "required": ["locationId", "locationType"]
                    },
                    "default": [],
                    "description": "Where the supplier works under this schedule. A schedule needs locations, a travel zone, or both.",
                    "example": [
                      {
                        "locationId": "loc_01kv60qgnef2kt3pvqgwmkbzfr",
                        "locationType": "PHYSICAL"
                      }
                    ]
                  },
                  "travelZoneRef": {
                    "oneOf": [
                      {
                        "type": "object",
                        "properties": {
                          "travelZoneSource": {
                            "type": "string",
                            "enum": ["PROJECT_LOCATION"],
                            "description": "The zone is a TRAVEL_ZONE location defined by the project.",
                            "example": "PROJECT_LOCATION"
                          },
                          "travelZoneLocationId": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The project’s TRAVEL_ZONE location.",
                            "example": "loc_01kv60qgnef2kt3pvqgwmkbzfr"
                          }
                        },
                        "required": ["travelZoneSource", "travelZoneLocationId"]
                      },
                      {
                        "type": "object",
                        "properties": {
                          "travelZoneSource": {
                            "type": "string",
                            "enum": ["SUPPLIER_TRAVEL_ZONE"],
                            "description": "The zone is one the supplier drew or set themselves.",
                            "example": "SUPPLIER_TRAVEL_ZONE"
                          },
                          "supplierTravelZoneId": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The supplier’s own travel zone.",
                            "example": "stz_01kv60qgnef2kt3pvqgwmkbzfr"
                          }
                        },
                        "required": ["travelZoneSource", "supplierTravelZoneId"]
                      }
                    ],
                    "description": "The area the supplier travels to under this schedule, if any.",
                    "example": {
                      "travelZoneSource": "PROJECT_LOCATION",
                      "travelZoneLocationId": "loc_01kv60qgnef2kt3pvqgwmkbzfr"
                    }
                  },
                  "startLocation": {
                    "type": "object",
                    "nullable": true,
                    "properties": {
                      "address": {
                        "type": "object",
                        "properties": {
                          "addressOneLine": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The whole address on one line, as a person would write it.",
                            "example": "10 Main St, Toronto, ON M5V 1A1, Canada"
                          },
                          "streetNumber": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The street number.",
                            "example": "10"
                          },
                          "streetName": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The street name.",
                            "example": "Main St"
                          },
                          "city": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The city or town.",
                            "example": "Toronto"
                          },
                          "state": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The state, province or region; an ISO 3166-2 code when one matches.",
                            "example": "ON"
                          },
                          "country": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The country; ISO 3166-1 alpha-2, alpha-3 or the English name.",
                            "example": "CA"
                          },
                          "zipCode": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The postal or ZIP code, in any national format.",
                            "example": "M5V 1A1"
                          },
                          "unitNumber": {
                            "type": "string",
                            "nullable": true,
                            "description": "The unit, suite or apartment, if any.",
                            "example": "4B"
                          }
                        },
                        "required": [
                          "addressOneLine",
                          "streetNumber",
                          "streetName",
                          "city",
                          "state",
                          "country",
                          "zipCode"
                        ],
                        "description": "The full street address. It needs a street number and a postal code.",
                        "example": {
                          "addressOneLine": "10 Main St, Toronto, ON M5V 1A1, Canada",
                          "streetNumber": "10",
                          "streetName": "Main St",
                          "city": "Toronto",
                          "state": "ON",
                          "country": "CA",
                          "zipCode": "M5V 1A1"
                        }
                      },
                      "latitude": {
                        "type": "number",
                        "minimum": -90,
                        "maximum": 90,
                        "description": "Latitude of the address, in decimal degrees.",
                        "example": 43.6426
                      },
                      "longitude": {
                        "type": "number",
                        "minimum": -180,
                        "maximum": 180,
                        "description": "Longitude of the address, in decimal degrees.",
                        "example": -79.3871
                      }
                    },
                    "required": ["address", "latitude", "longitude"],
                    "description": "Where the supplier starts each working day under this schedule, if set. Send null to remove it.",
                    "example": {
                      "address": {
                        "addressOneLine": "10 Main St, Toronto, ON M5V 1A1, Canada",
                        "streetNumber": "10",
                        "streetName": "Main St",
                        "city": "Toronto",
                        "state": "ON",
                        "country": "CA",
                        "zipCode": "M5V 1A1"
                      },
                      "latitude": 43.6426,
                      "longitude": -79.3871
                    }
                  },
                  "endLocation": {
                    "type": "object",
                    "nullable": true,
                    "properties": {
                      "address": {
                        "type": "object",
                        "properties": {
                          "addressOneLine": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The whole address on one line, as a person would write it.",
                            "example": "10 Main St, Toronto, ON M5V 1A1, Canada"
                          },
                          "streetNumber": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The street number.",
                            "example": "10"
                          },
                          "streetName": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The street name.",
                            "example": "Main St"
                          },
                          "city": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The city or town.",
                            "example": "Toronto"
                          },
                          "state": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The state, province or region; an ISO 3166-2 code when one matches.",
                            "example": "ON"
                          },
                          "country": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The country; ISO 3166-1 alpha-2, alpha-3 or the English name.",
                            "example": "CA"
                          },
                          "zipCode": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The postal or ZIP code, in any national format.",
                            "example": "M5V 1A1"
                          },
                          "unitNumber": {
                            "type": "string",
                            "nullable": true,
                            "description": "The unit, suite or apartment, if any.",
                            "example": "4B"
                          }
                        },
                        "required": [
                          "addressOneLine",
                          "streetNumber",
                          "streetName",
                          "city",
                          "state",
                          "country",
                          "zipCode"
                        ],
                        "description": "The full street address. It needs a street number and a postal code.",
                        "example": {
                          "addressOneLine": "10 Main St, Toronto, ON M5V 1A1, Canada",
                          "streetNumber": "10",
                          "streetName": "Main St",
                          "city": "Toronto",
                          "state": "ON",
                          "country": "CA",
                          "zipCode": "M5V 1A1"
                        }
                      },
                      "latitude": {
                        "type": "number",
                        "minimum": -90,
                        "maximum": 90,
                        "description": "Latitude of the address, in decimal degrees.",
                        "example": 43.6426
                      },
                      "longitude": {
                        "type": "number",
                        "minimum": -180,
                        "maximum": 180,
                        "description": "Longitude of the address, in decimal degrees.",
                        "example": -79.3871
                      }
                    },
                    "required": ["address", "latitude", "longitude"],
                    "description": "Where the supplier ends each working day under this schedule, if set. Send null to remove it.",
                    "example": {
                      "address": {
                        "addressOneLine": "10 Main St, Toronto, ON M5V 1A1, Canada",
                        "streetNumber": "10",
                        "streetName": "Main St",
                        "city": "Toronto",
                        "state": "ON",
                        "country": "CA",
                        "zipCode": "M5V 1A1"
                      },
                      "latitude": 43.6426,
                      "longitude": -79.3871
                    }
                  },
                  "driveTiming": {
                    "type": "string",
                    "nullable": true,
                    "enum": ["INSIDE_HOURS", "OUTSIDE_HOURS", null],
                    "description": "Whether the drive to the first and from the last booking counts inside or outside working hours. Null uses the project default.",
                    "example": "OUTSIDE_HOURS"
                  },
                  "maxTravelOnStartDrive": {
                    "type": "boolean",
                    "nullable": true,
                    "description": "Whether the start drive is limited by the supplier’s maximum travel time. Null uses the project default.",
                    "example": true
                  },
                  "maxTravelOnEndDrive": {
                    "type": "boolean",
                    "nullable": true,
                    "description": "Whether the end drive is limited by the supplier’s maximum travel time. Null uses the project default.",
                    "example": true
                  }
                },
                "required": [
                  "startDate",
                  "endDate",
                  "rrule",
                  "weeklyTimeRanges",
                  "appliesToAllOfferings"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Schedule created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "scheduleId": {
                          "type": "string"
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "supplierId": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": ["ACTIVE", "INACTIVE"]
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "timezone": {
                          "type": "string"
                        },
                        "startDate": {
                          "type": "string"
                        },
                        "endDate": {
                          "type": "string"
                        },
                        "rrule": {
                          "type": "string"
                        },
                        "exdates": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "weeklyTimeRanges": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "dayOfWeek": {
                                "type": "string",
                                "enum": [
                                  "MO",
                                  "TU",
                                  "WE",
                                  "TH",
                                  "FR",
                                  "SA",
                                  "SU"
                                ],
                                "description": "The weekday this range falls on, in the row’s zone.",
                                "example": "MO"
                              },
                              "startTime": {
                                "type": "string",
                                "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                "description": "Wall-clock start, HH:MM in the row’s zone.",
                                "example": "09:00"
                              },
                              "endTime": {
                                "type": "string",
                                "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                "description": "Wall-clock end, HH:MM in the row’s zone; must differ from startTime.",
                                "example": "17:00"
                              },
                              "crossesMidnight": {
                                "type": "boolean",
                                "description": "True exactly when endTime is earlier than startTime (the range ends next day).",
                                "example": false
                              },
                              "sortOrder": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Display order among the ranges of one day, from 0.",
                                "example": 0
                              }
                            },
                            "required": [
                              "dayOfWeek",
                              "startTime",
                              "endTime",
                              "crossesMidnight",
                              "sortOrder"
                            ]
                          }
                        },
                        "appliesToAllOfferings": {
                          "type": "boolean"
                        },
                        "serviceOfferingIds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "locationRefs": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "locationId": {
                                "type": "string",
                                "minLength": 1,
                                "description": "A location of the project the supplier works at under this schedule.",
                                "example": "loc_01kv60qgnef2kt3pvqgwmkbzfr"
                              },
                              "locationType": {
                                "type": "string",
                                "enum": ["PHYSICAL", "VIRTUAL"],
                                "description": "PHYSICAL (an address) or VIRTUAL (online); must match the location’s own type.",
                                "example": "PHYSICAL"
                              }
                            },
                            "required": ["locationId", "locationType"]
                          }
                        },
                        "travelZoneRef": {
                          "oneOf": [
                            {
                              "type": "object",
                              "properties": {
                                "travelZoneSource": {
                                  "type": "string",
                                  "enum": ["PROJECT_LOCATION"],
                                  "description": "The zone is a TRAVEL_ZONE location defined by the project.",
                                  "example": "PROJECT_LOCATION"
                                },
                                "travelZoneLocationId": {
                                  "type": "string",
                                  "minLength": 1,
                                  "description": "The project’s TRAVEL_ZONE location.",
                                  "example": "loc_01kv60qgnef2kt3pvqgwmkbzfr"
                                }
                              },
                              "required": [
                                "travelZoneSource",
                                "travelZoneLocationId"
                              ]
                            },
                            {
                              "type": "object",
                              "properties": {
                                "travelZoneSource": {
                                  "type": "string",
                                  "enum": ["SUPPLIER_TRAVEL_ZONE"],
                                  "description": "The zone is one the supplier drew or set themselves.",
                                  "example": "SUPPLIER_TRAVEL_ZONE"
                                },
                                "supplierTravelZoneId": {
                                  "type": "string",
                                  "minLength": 1,
                                  "description": "The supplier’s own travel zone.",
                                  "example": "stz_01kv60qgnef2kt3pvqgwmkbzfr"
                                }
                              },
                              "required": [
                                "travelZoneSource",
                                "supplierTravelZoneId"
                              ]
                            }
                          ]
                        },
                        "startLocation": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "address": {
                              "$ref": "#/components/schemas/Address"
                            },
                            "latitude": {
                              "type": "number",
                              "minimum": -90,
                              "maximum": 90,
                              "description": "Latitude of the address, in decimal degrees.",
                              "example": 43.6426
                            },
                            "longitude": {
                              "type": "number",
                              "minimum": -180,
                              "maximum": 180,
                              "description": "Longitude of the address, in decimal degrees.",
                              "example": -79.3871
                            }
                          },
                          "required": ["address", "latitude", "longitude"]
                        },
                        "endLocation": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "address": {
                              "$ref": "#/components/schemas/Address"
                            },
                            "latitude": {
                              "type": "number",
                              "minimum": -90,
                              "maximum": 90,
                              "description": "Latitude of the address, in decimal degrees.",
                              "example": 43.6426
                            },
                            "longitude": {
                              "type": "number",
                              "minimum": -180,
                              "maximum": 180,
                              "description": "Longitude of the address, in decimal degrees.",
                              "example": -79.3871
                            }
                          },
                          "required": ["address", "latitude", "longitude"]
                        },
                        "driveTiming": {
                          "type": "string",
                          "nullable": true,
                          "enum": ["INSIDE_HOURS", "OUTSIDE_HOURS", null]
                        },
                        "maxTravelOnStartDrive": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "maxTravelOnEndDrive": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "physicalLocationIdsInsideTravelZone": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "dateRangeLabel": {
                          "type": "string"
                        },
                        "timeRangeSummary": {
                          "type": "string"
                        },
                        "daysSummary": {
                          "type": "string"
                        },
                        "coverageAreaSummary": {
                          "type": "string"
                        },
                        "offeringsSummary": {
                          "type": "string"
                        },
                        "version": {
                          "type": "integer",
                          "minimum": 0,
                          "exclusiveMinimum": true
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "updatedAt": {
                          "type": "string"
                        },
                        "deletedAt": {
                          "type": "string"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        },
                        "deletedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "scheduleId",
                        "projectId",
                        "supplierId",
                        "status",
                        "deleted",
                        "timezone",
                        "startDate",
                        "endDate",
                        "rrule",
                        "exdates",
                        "weeklyTimeRanges",
                        "appliesToAllOfferings",
                        "serviceOfferingIds",
                        "locationRefs",
                        "dateRangeLabel",
                        "timeRangeSummary",
                        "daysSummary",
                        "coverageAreaSummary",
                        "offeringsSummary",
                        "version",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such schedule of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "CONFLICT: the schedule overlaps an existing active one",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "422": {
            "description": "START_END_LOCATIONS_DISABLED: the project has start and end locations off, so a value cannot be set; SETTING_NOT_DELEGATED: the project has not delegated that setting to suppliers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "get": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "List the signed-in supplier’s schedules",
        "description": "The supplier’s schedules as the dashboard lists them: ACTIVE ones by default, INACTIVE and soft-deleted ones on request. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "enum": ["true", "false"],
              "description": "Also return INACTIVE schedules (kept but offering nothing).",
              "example": "false"
            },
            "required": false,
            "description": "Also return INACTIVE schedules (kept but offering nothing).",
            "name": "includeInactive",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": ["true", "false"],
              "description": "Also return soft-deleted schedules.",
              "example": "false"
            },
            "required": false,
            "description": "Also return soft-deleted schedules.",
            "name": "includeDeleted",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Schedules list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "scheduleId": {
                            "type": "string"
                          },
                          "projectId": {
                            "type": "string"
                          },
                          "supplierId": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": ["ACTIVE", "INACTIVE"]
                          },
                          "deleted": {
                            "type": "boolean"
                          },
                          "timezone": {
                            "type": "string"
                          },
                          "startDate": {
                            "type": "string"
                          },
                          "endDate": {
                            "type": "string"
                          },
                          "rrule": {
                            "type": "string"
                          },
                          "exdates": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "weeklyTimeRanges": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "dayOfWeek": {
                                  "type": "string",
                                  "enum": [
                                    "MO",
                                    "TU",
                                    "WE",
                                    "TH",
                                    "FR",
                                    "SA",
                                    "SU"
                                  ],
                                  "description": "The weekday this range falls on, in the row’s zone.",
                                  "example": "MO"
                                },
                                "startTime": {
                                  "type": "string",
                                  "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                  "description": "Wall-clock start, HH:MM in the row’s zone.",
                                  "example": "09:00"
                                },
                                "endTime": {
                                  "type": "string",
                                  "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                  "description": "Wall-clock end, HH:MM in the row’s zone; must differ from startTime.",
                                  "example": "17:00"
                                },
                                "crossesMidnight": {
                                  "type": "boolean",
                                  "description": "True exactly when endTime is earlier than startTime (the range ends next day).",
                                  "example": false
                                },
                                "sortOrder": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "Display order among the ranges of one day, from 0.",
                                  "example": 0
                                }
                              },
                              "required": [
                                "dayOfWeek",
                                "startTime",
                                "endTime",
                                "crossesMidnight",
                                "sortOrder"
                              ]
                            }
                          },
                          "appliesToAllOfferings": {
                            "type": "boolean"
                          },
                          "serviceOfferingIds": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "locationRefs": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "locationId": {
                                  "type": "string",
                                  "minLength": 1,
                                  "description": "A location of the project the supplier works at under this schedule.",
                                  "example": "loc_01kv60qgnef2kt3pvqgwmkbzfr"
                                },
                                "locationType": {
                                  "type": "string",
                                  "enum": ["PHYSICAL", "VIRTUAL"],
                                  "description": "PHYSICAL (an address) or VIRTUAL (online); must match the location’s own type.",
                                  "example": "PHYSICAL"
                                }
                              },
                              "required": ["locationId", "locationType"]
                            }
                          },
                          "travelZoneRef": {
                            "oneOf": [
                              {
                                "type": "object",
                                "properties": {
                                  "travelZoneSource": {
                                    "type": "string",
                                    "enum": ["PROJECT_LOCATION"],
                                    "description": "The zone is a TRAVEL_ZONE location defined by the project.",
                                    "example": "PROJECT_LOCATION"
                                  },
                                  "travelZoneLocationId": {
                                    "type": "string",
                                    "minLength": 1,
                                    "description": "The project’s TRAVEL_ZONE location.",
                                    "example": "loc_01kv60qgnef2kt3pvqgwmkbzfr"
                                  }
                                },
                                "required": [
                                  "travelZoneSource",
                                  "travelZoneLocationId"
                                ]
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "travelZoneSource": {
                                    "type": "string",
                                    "enum": ["SUPPLIER_TRAVEL_ZONE"],
                                    "description": "The zone is one the supplier drew or set themselves.",
                                    "example": "SUPPLIER_TRAVEL_ZONE"
                                  },
                                  "supplierTravelZoneId": {
                                    "type": "string",
                                    "minLength": 1,
                                    "description": "The supplier’s own travel zone.",
                                    "example": "stz_01kv60qgnef2kt3pvqgwmkbzfr"
                                  }
                                },
                                "required": [
                                  "travelZoneSource",
                                  "supplierTravelZoneId"
                                ]
                              }
                            ]
                          },
                          "startLocation": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "address": {
                                "$ref": "#/components/schemas/Address"
                              },
                              "latitude": {
                                "type": "number",
                                "minimum": -90,
                                "maximum": 90,
                                "description": "Latitude of the address, in decimal degrees.",
                                "example": 43.6426
                              },
                              "longitude": {
                                "type": "number",
                                "minimum": -180,
                                "maximum": 180,
                                "description": "Longitude of the address, in decimal degrees.",
                                "example": -79.3871
                              }
                            },
                            "required": ["address", "latitude", "longitude"]
                          },
                          "endLocation": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "address": {
                                "$ref": "#/components/schemas/Address"
                              },
                              "latitude": {
                                "type": "number",
                                "minimum": -90,
                                "maximum": 90,
                                "description": "Latitude of the address, in decimal degrees.",
                                "example": 43.6426
                              },
                              "longitude": {
                                "type": "number",
                                "minimum": -180,
                                "maximum": 180,
                                "description": "Longitude of the address, in decimal degrees.",
                                "example": -79.3871
                              }
                            },
                            "required": ["address", "latitude", "longitude"]
                          },
                          "driveTiming": {
                            "type": "string",
                            "nullable": true,
                            "enum": ["INSIDE_HOURS", "OUTSIDE_HOURS", null]
                          },
                          "maxTravelOnStartDrive": {
                            "type": "boolean",
                            "nullable": true
                          },
                          "maxTravelOnEndDrive": {
                            "type": "boolean",
                            "nullable": true
                          },
                          "physicalLocationIdsInsideTravelZone": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "dateRangeLabel": {
                            "type": "string"
                          },
                          "timeRangeSummary": {
                            "type": "string"
                          },
                          "daysSummary": {
                            "type": "string"
                          },
                          "coverageAreaSummary": {
                            "type": "string"
                          },
                          "offeringsSummary": {
                            "type": "string"
                          },
                          "version": {
                            "type": "integer",
                            "minimum": 0,
                            "exclusiveMinimum": true
                          },
                          "createdAt": {
                            "type": "string"
                          },
                          "updatedAt": {
                            "type": "string"
                          },
                          "deletedAt": {
                            "type": "string"
                          },
                          "createdBy": {
                            "type": "string"
                          },
                          "updatedBy": {
                            "type": "string"
                          },
                          "deletedBy": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "scheduleId",
                          "projectId",
                          "supplierId",
                          "status",
                          "deleted",
                          "timezone",
                          "startDate",
                          "endDate",
                          "rrule",
                          "exdates",
                          "weeklyTimeRanges",
                          "appliesToAllOfferings",
                          "serviceOfferingIds",
                          "locationRefs",
                          "dateRangeLabel",
                          "timeRangeSummary",
                          "daysSummary",
                          "coverageAreaSummary",
                          "offeringsSummary",
                          "version",
                          "createdAt",
                          "updatedAt",
                          "createdBy",
                          "updatedBy"
                        ]
                      }
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such schedule of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/schedules/{scheduleId}": {
      "get": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Get one of the signed-in supplier’s schedules",
        "description": "One schedule by id, if it belongs to the supplier the user token resolves to. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The schedule — one recurring pattern of when and where the supplier works.",
              "example": "sch_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The schedule — one recurring pattern of when and where the supplier works.",
            "name": "scheduleId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Schedule",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "scheduleId": {
                          "type": "string"
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "supplierId": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": ["ACTIVE", "INACTIVE"]
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "timezone": {
                          "type": "string"
                        },
                        "startDate": {
                          "type": "string"
                        },
                        "endDate": {
                          "type": "string"
                        },
                        "rrule": {
                          "type": "string"
                        },
                        "exdates": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "weeklyTimeRanges": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "dayOfWeek": {
                                "type": "string",
                                "enum": [
                                  "MO",
                                  "TU",
                                  "WE",
                                  "TH",
                                  "FR",
                                  "SA",
                                  "SU"
                                ],
                                "description": "The weekday this range falls on, in the row’s zone.",
                                "example": "MO"
                              },
                              "startTime": {
                                "type": "string",
                                "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                "description": "Wall-clock start, HH:MM in the row’s zone.",
                                "example": "09:00"
                              },
                              "endTime": {
                                "type": "string",
                                "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                "description": "Wall-clock end, HH:MM in the row’s zone; must differ from startTime.",
                                "example": "17:00"
                              },
                              "crossesMidnight": {
                                "type": "boolean",
                                "description": "True exactly when endTime is earlier than startTime (the range ends next day).",
                                "example": false
                              },
                              "sortOrder": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Display order among the ranges of one day, from 0.",
                                "example": 0
                              }
                            },
                            "required": [
                              "dayOfWeek",
                              "startTime",
                              "endTime",
                              "crossesMidnight",
                              "sortOrder"
                            ]
                          }
                        },
                        "appliesToAllOfferings": {
                          "type": "boolean"
                        },
                        "serviceOfferingIds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "locationRefs": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "locationId": {
                                "type": "string",
                                "minLength": 1,
                                "description": "A location of the project the supplier works at under this schedule.",
                                "example": "loc_01kv60qgnef2kt3pvqgwmkbzfr"
                              },
                              "locationType": {
                                "type": "string",
                                "enum": ["PHYSICAL", "VIRTUAL"],
                                "description": "PHYSICAL (an address) or VIRTUAL (online); must match the location’s own type.",
                                "example": "PHYSICAL"
                              }
                            },
                            "required": ["locationId", "locationType"]
                          }
                        },
                        "travelZoneRef": {
                          "oneOf": [
                            {
                              "type": "object",
                              "properties": {
                                "travelZoneSource": {
                                  "type": "string",
                                  "enum": ["PROJECT_LOCATION"],
                                  "description": "The zone is a TRAVEL_ZONE location defined by the project.",
                                  "example": "PROJECT_LOCATION"
                                },
                                "travelZoneLocationId": {
                                  "type": "string",
                                  "minLength": 1,
                                  "description": "The project’s TRAVEL_ZONE location.",
                                  "example": "loc_01kv60qgnef2kt3pvqgwmkbzfr"
                                }
                              },
                              "required": [
                                "travelZoneSource",
                                "travelZoneLocationId"
                              ]
                            },
                            {
                              "type": "object",
                              "properties": {
                                "travelZoneSource": {
                                  "type": "string",
                                  "enum": ["SUPPLIER_TRAVEL_ZONE"],
                                  "description": "The zone is one the supplier drew or set themselves.",
                                  "example": "SUPPLIER_TRAVEL_ZONE"
                                },
                                "supplierTravelZoneId": {
                                  "type": "string",
                                  "minLength": 1,
                                  "description": "The supplier’s own travel zone.",
                                  "example": "stz_01kv60qgnef2kt3pvqgwmkbzfr"
                                }
                              },
                              "required": [
                                "travelZoneSource",
                                "supplierTravelZoneId"
                              ]
                            }
                          ]
                        },
                        "startLocation": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "address": {
                              "$ref": "#/components/schemas/Address"
                            },
                            "latitude": {
                              "type": "number",
                              "minimum": -90,
                              "maximum": 90,
                              "description": "Latitude of the address, in decimal degrees.",
                              "example": 43.6426
                            },
                            "longitude": {
                              "type": "number",
                              "minimum": -180,
                              "maximum": 180,
                              "description": "Longitude of the address, in decimal degrees.",
                              "example": -79.3871
                            }
                          },
                          "required": ["address", "latitude", "longitude"]
                        },
                        "endLocation": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "address": {
                              "$ref": "#/components/schemas/Address"
                            },
                            "latitude": {
                              "type": "number",
                              "minimum": -90,
                              "maximum": 90,
                              "description": "Latitude of the address, in decimal degrees.",
                              "example": 43.6426
                            },
                            "longitude": {
                              "type": "number",
                              "minimum": -180,
                              "maximum": 180,
                              "description": "Longitude of the address, in decimal degrees.",
                              "example": -79.3871
                            }
                          },
                          "required": ["address", "latitude", "longitude"]
                        },
                        "driveTiming": {
                          "type": "string",
                          "nullable": true,
                          "enum": ["INSIDE_HOURS", "OUTSIDE_HOURS", null]
                        },
                        "maxTravelOnStartDrive": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "maxTravelOnEndDrive": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "physicalLocationIdsInsideTravelZone": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "dateRangeLabel": {
                          "type": "string"
                        },
                        "timeRangeSummary": {
                          "type": "string"
                        },
                        "daysSummary": {
                          "type": "string"
                        },
                        "coverageAreaSummary": {
                          "type": "string"
                        },
                        "offeringsSummary": {
                          "type": "string"
                        },
                        "version": {
                          "type": "integer",
                          "minimum": 0,
                          "exclusiveMinimum": true
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "updatedAt": {
                          "type": "string"
                        },
                        "deletedAt": {
                          "type": "string"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        },
                        "deletedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "scheduleId",
                        "projectId",
                        "supplierId",
                        "status",
                        "deleted",
                        "timezone",
                        "startDate",
                        "endDate",
                        "rrule",
                        "exdates",
                        "weeklyTimeRanges",
                        "appliesToAllOfferings",
                        "serviceOfferingIds",
                        "locationRefs",
                        "dateRangeLabel",
                        "timeRangeSummary",
                        "daysSummary",
                        "coverageAreaSummary",
                        "offeringsSummary",
                        "version",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such schedule of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "patch": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Update one of the signed-in supplier’s schedules",
        "description": "Change any of the schedule’s fields; send the row’s current `version` (optimistic concurrency — a stale one is a 409). Newly added offerings must be ACTIVE; an ACTIVE schedule may not come to overlap another (409). Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The schedule — one recurring pattern of when and where the supplier works.",
              "example": "sch_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The schedule — one recurring pattern of when and where the supplier works.",
            "name": "scheduleId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Fields to update",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": ["ACTIVE", "INACTIVE"],
                    "description": "ACTIVE rows are offered for booking; INACTIVE rows are kept but offer nothing.",
                    "example": "ACTIVE"
                  },
                  "timezone": {
                    "type": "string",
                    "minLength": 1,
                    "description": "IANA zone the wall-clock times are in. Omit to use the supplier’s profile zone, then the project default (R-11); never UTC by accident.",
                    "example": "America/Toronto"
                  },
                  "startDate": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                    "description": "First calendar day the row applies to, YYYY-MM-DD in its zone.",
                    "example": "2026-01-05"
                  },
                  "endDate": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                    "description": "Last calendar day the row applies to (inclusive), YYYY-MM-DD; on or after startDate.",
                    "example": "2026-12-31"
                  },
                  "rrule": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The recurrence (RFC 5545 RRULE, weekly), expanded per occurrence in the row’s zone.",
                    "example": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE"
                  },
                  "exdates": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                      "example": "2026-07-01"
                    },
                    "description": "Calendar days (YYYY-MM-DD) skipped from the recurrence.",
                    "example": []
                  },
                  "weeklyTimeRanges": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "dayOfWeek": {
                          "type": "string",
                          "enum": ["MO", "TU", "WE", "TH", "FR", "SA", "SU"],
                          "description": "The weekday this range falls on, in the row’s zone.",
                          "example": "MO"
                        },
                        "startTime": {
                          "type": "string",
                          "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                          "description": "Wall-clock start, HH:MM in the row’s zone.",
                          "example": "09:00"
                        },
                        "endTime": {
                          "type": "string",
                          "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                          "description": "Wall-clock end, HH:MM in the row’s zone; must differ from startTime.",
                          "example": "17:00"
                        },
                        "crossesMidnight": {
                          "type": "boolean",
                          "description": "True exactly when endTime is earlier than startTime (the range ends next day).",
                          "example": false
                        },
                        "sortOrder": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Display order among the ranges of one day, from 0.",
                          "example": 0
                        }
                      },
                      "required": [
                        "dayOfWeek",
                        "startTime",
                        "endTime",
                        "crossesMidnight",
                        "sortOrder"
                      ]
                    },
                    "minItems": 1,
                    "description": "The working ranges per weekday; at least one.",
                    "example": [
                      {
                        "dayOfWeek": "MO",
                        "startTime": "09:00",
                        "endTime": "17:00",
                        "crossesMidnight": false,
                        "sortOrder": 0
                      }
                    ]
                  },
                  "appliesToAllOfferings": {
                    "type": "boolean",
                    "description": "True = every ACTIVE offering of the supplier’s services; false = exactly serviceOfferingIds.",
                    "example": true
                  },
                  "serviceOfferingIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "example": "off_01kv60qge5eh59ap0gw0pqrrys"
                    },
                    "description": "The offerings this schedule serves when appliesToAllOfferings is false; must be ACTIVE offerings of services the supplier provides.",
                    "example": []
                  },
                  "locationRefs": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "locationId": {
                          "type": "string",
                          "minLength": 1,
                          "description": "A location of the project the supplier works at under this schedule.",
                          "example": "loc_01kv60qgnef2kt3pvqgwmkbzfr"
                        },
                        "locationType": {
                          "type": "string",
                          "enum": ["PHYSICAL", "VIRTUAL"],
                          "description": "PHYSICAL (an address) or VIRTUAL (online); must match the location’s own type.",
                          "example": "PHYSICAL"
                        }
                      },
                      "required": ["locationId", "locationType"]
                    },
                    "description": "Where the supplier works under this schedule. A schedule needs locations, a travel zone, or both.",
                    "example": [
                      {
                        "locationId": "loc_01kv60qgnef2kt3pvqgwmkbzfr",
                        "locationType": "PHYSICAL"
                      }
                    ]
                  },
                  "travelZoneRef": {
                    "oneOf": [
                      {
                        "type": "object",
                        "properties": {
                          "travelZoneSource": {
                            "type": "string",
                            "enum": ["PROJECT_LOCATION"],
                            "description": "The zone is a TRAVEL_ZONE location defined by the project.",
                            "example": "PROJECT_LOCATION"
                          },
                          "travelZoneLocationId": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The project’s TRAVEL_ZONE location.",
                            "example": "loc_01kv60qgnef2kt3pvqgwmkbzfr"
                          }
                        },
                        "required": ["travelZoneSource", "travelZoneLocationId"]
                      },
                      {
                        "type": "object",
                        "properties": {
                          "travelZoneSource": {
                            "type": "string",
                            "enum": ["SUPPLIER_TRAVEL_ZONE"],
                            "description": "The zone is one the supplier drew or set themselves.",
                            "example": "SUPPLIER_TRAVEL_ZONE"
                          },
                          "supplierTravelZoneId": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The supplier’s own travel zone.",
                            "example": "stz_01kv60qgnef2kt3pvqgwmkbzfr"
                          }
                        },
                        "required": ["travelZoneSource", "supplierTravelZoneId"]
                      },
                      {
                        "nullable": true
                      }
                    ],
                    "description": "The area the supplier travels to under this schedule, if any. Send null to remove it.",
                    "example": {
                      "travelZoneSource": "PROJECT_LOCATION",
                      "travelZoneLocationId": "loc_01kv60qgnef2kt3pvqgwmkbzfr"
                    }
                  },
                  "startLocation": {
                    "type": "object",
                    "nullable": true,
                    "properties": {
                      "address": {
                        "type": "object",
                        "properties": {
                          "addressOneLine": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The whole address on one line, as a person would write it.",
                            "example": "10 Main St, Toronto, ON M5V 1A1, Canada"
                          },
                          "streetNumber": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The street number.",
                            "example": "10"
                          },
                          "streetName": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The street name.",
                            "example": "Main St"
                          },
                          "city": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The city or town.",
                            "example": "Toronto"
                          },
                          "state": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The state, province or region; an ISO 3166-2 code when one matches.",
                            "example": "ON"
                          },
                          "country": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The country; ISO 3166-1 alpha-2, alpha-3 or the English name.",
                            "example": "CA"
                          },
                          "zipCode": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The postal or ZIP code, in any national format.",
                            "example": "M5V 1A1"
                          },
                          "unitNumber": {
                            "type": "string",
                            "nullable": true,
                            "description": "The unit, suite or apartment, if any.",
                            "example": "4B"
                          }
                        },
                        "required": [
                          "addressOneLine",
                          "streetNumber",
                          "streetName",
                          "city",
                          "state",
                          "country",
                          "zipCode"
                        ],
                        "description": "The full street address. It needs a street number and a postal code.",
                        "example": {
                          "addressOneLine": "10 Main St, Toronto, ON M5V 1A1, Canada",
                          "streetNumber": "10",
                          "streetName": "Main St",
                          "city": "Toronto",
                          "state": "ON",
                          "country": "CA",
                          "zipCode": "M5V 1A1"
                        }
                      },
                      "latitude": {
                        "type": "number",
                        "minimum": -90,
                        "maximum": 90,
                        "description": "Latitude of the address, in decimal degrees.",
                        "example": 43.6426
                      },
                      "longitude": {
                        "type": "number",
                        "minimum": -180,
                        "maximum": 180,
                        "description": "Longitude of the address, in decimal degrees.",
                        "example": -79.3871
                      }
                    },
                    "required": ["address", "latitude", "longitude"],
                    "description": "Where the supplier starts each working day under this schedule, if set. Send null to remove it.",
                    "example": {
                      "address": {
                        "addressOneLine": "10 Main St, Toronto, ON M5V 1A1, Canada",
                        "streetNumber": "10",
                        "streetName": "Main St",
                        "city": "Toronto",
                        "state": "ON",
                        "country": "CA",
                        "zipCode": "M5V 1A1"
                      },
                      "latitude": 43.6426,
                      "longitude": -79.3871
                    }
                  },
                  "endLocation": {
                    "type": "object",
                    "nullable": true,
                    "properties": {
                      "address": {
                        "type": "object",
                        "properties": {
                          "addressOneLine": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The whole address on one line, as a person would write it.",
                            "example": "10 Main St, Toronto, ON M5V 1A1, Canada"
                          },
                          "streetNumber": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The street number.",
                            "example": "10"
                          },
                          "streetName": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The street name.",
                            "example": "Main St"
                          },
                          "city": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The city or town.",
                            "example": "Toronto"
                          },
                          "state": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The state, province or region; an ISO 3166-2 code when one matches.",
                            "example": "ON"
                          },
                          "country": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The country; ISO 3166-1 alpha-2, alpha-3 or the English name.",
                            "example": "CA"
                          },
                          "zipCode": {
                            "type": "string",
                            "minLength": 1,
                            "description": "The postal or ZIP code, in any national format.",
                            "example": "M5V 1A1"
                          },
                          "unitNumber": {
                            "type": "string",
                            "nullable": true,
                            "description": "The unit, suite or apartment, if any.",
                            "example": "4B"
                          }
                        },
                        "required": [
                          "addressOneLine",
                          "streetNumber",
                          "streetName",
                          "city",
                          "state",
                          "country",
                          "zipCode"
                        ],
                        "description": "The full street address. It needs a street number and a postal code.",
                        "example": {
                          "addressOneLine": "10 Main St, Toronto, ON M5V 1A1, Canada",
                          "streetNumber": "10",
                          "streetName": "Main St",
                          "city": "Toronto",
                          "state": "ON",
                          "country": "CA",
                          "zipCode": "M5V 1A1"
                        }
                      },
                      "latitude": {
                        "type": "number",
                        "minimum": -90,
                        "maximum": 90,
                        "description": "Latitude of the address, in decimal degrees.",
                        "example": 43.6426
                      },
                      "longitude": {
                        "type": "number",
                        "minimum": -180,
                        "maximum": 180,
                        "description": "Longitude of the address, in decimal degrees.",
                        "example": -79.3871
                      }
                    },
                    "required": ["address", "latitude", "longitude"],
                    "description": "Where the supplier ends each working day under this schedule, if set. Send null to remove it.",
                    "example": {
                      "address": {
                        "addressOneLine": "10 Main St, Toronto, ON M5V 1A1, Canada",
                        "streetNumber": "10",
                        "streetName": "Main St",
                        "city": "Toronto",
                        "state": "ON",
                        "country": "CA",
                        "zipCode": "M5V 1A1"
                      },
                      "latitude": 43.6426,
                      "longitude": -79.3871
                    }
                  },
                  "driveTiming": {
                    "type": "string",
                    "nullable": true,
                    "enum": ["INSIDE_HOURS", "OUTSIDE_HOURS", null],
                    "description": "Whether the drive to the first and from the last booking counts inside or outside working hours. Null uses the project default.",
                    "example": "OUTSIDE_HOURS"
                  },
                  "maxTravelOnStartDrive": {
                    "type": "boolean",
                    "nullable": true,
                    "description": "Whether the start drive is limited by the supplier’s maximum travel time. Null uses the project default.",
                    "example": true
                  },
                  "maxTravelOnEndDrive": {
                    "type": "boolean",
                    "nullable": true,
                    "description": "Whether the end drive is limited by the supplier’s maximum travel time. Null uses the project default.",
                    "example": true
                  },
                  "version": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "description": "The row’s current version, for optimistic concurrency; a stale value is a 409.",
                    "example": 3
                  }
                },
                "required": ["version"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Schedule updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "scheduleId": {
                          "type": "string"
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "supplierId": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": ["ACTIVE", "INACTIVE"]
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "timezone": {
                          "type": "string"
                        },
                        "startDate": {
                          "type": "string"
                        },
                        "endDate": {
                          "type": "string"
                        },
                        "rrule": {
                          "type": "string"
                        },
                        "exdates": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "weeklyTimeRanges": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "dayOfWeek": {
                                "type": "string",
                                "enum": [
                                  "MO",
                                  "TU",
                                  "WE",
                                  "TH",
                                  "FR",
                                  "SA",
                                  "SU"
                                ],
                                "description": "The weekday this range falls on, in the row’s zone.",
                                "example": "MO"
                              },
                              "startTime": {
                                "type": "string",
                                "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                "description": "Wall-clock start, HH:MM in the row’s zone.",
                                "example": "09:00"
                              },
                              "endTime": {
                                "type": "string",
                                "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                "description": "Wall-clock end, HH:MM in the row’s zone; must differ from startTime.",
                                "example": "17:00"
                              },
                              "crossesMidnight": {
                                "type": "boolean",
                                "description": "True exactly when endTime is earlier than startTime (the range ends next day).",
                                "example": false
                              },
                              "sortOrder": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Display order among the ranges of one day, from 0.",
                                "example": 0
                              }
                            },
                            "required": [
                              "dayOfWeek",
                              "startTime",
                              "endTime",
                              "crossesMidnight",
                              "sortOrder"
                            ]
                          }
                        },
                        "appliesToAllOfferings": {
                          "type": "boolean"
                        },
                        "serviceOfferingIds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "locationRefs": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "locationId": {
                                "type": "string",
                                "minLength": 1,
                                "description": "A location of the project the supplier works at under this schedule.",
                                "example": "loc_01kv60qgnef2kt3pvqgwmkbzfr"
                              },
                              "locationType": {
                                "type": "string",
                                "enum": ["PHYSICAL", "VIRTUAL"],
                                "description": "PHYSICAL (an address) or VIRTUAL (online); must match the location’s own type.",
                                "example": "PHYSICAL"
                              }
                            },
                            "required": ["locationId", "locationType"]
                          }
                        },
                        "travelZoneRef": {
                          "oneOf": [
                            {
                              "type": "object",
                              "properties": {
                                "travelZoneSource": {
                                  "type": "string",
                                  "enum": ["PROJECT_LOCATION"],
                                  "description": "The zone is a TRAVEL_ZONE location defined by the project.",
                                  "example": "PROJECT_LOCATION"
                                },
                                "travelZoneLocationId": {
                                  "type": "string",
                                  "minLength": 1,
                                  "description": "The project’s TRAVEL_ZONE location.",
                                  "example": "loc_01kv60qgnef2kt3pvqgwmkbzfr"
                                }
                              },
                              "required": [
                                "travelZoneSource",
                                "travelZoneLocationId"
                              ]
                            },
                            {
                              "type": "object",
                              "properties": {
                                "travelZoneSource": {
                                  "type": "string",
                                  "enum": ["SUPPLIER_TRAVEL_ZONE"],
                                  "description": "The zone is one the supplier drew or set themselves.",
                                  "example": "SUPPLIER_TRAVEL_ZONE"
                                },
                                "supplierTravelZoneId": {
                                  "type": "string",
                                  "minLength": 1,
                                  "description": "The supplier’s own travel zone.",
                                  "example": "stz_01kv60qgnef2kt3pvqgwmkbzfr"
                                }
                              },
                              "required": [
                                "travelZoneSource",
                                "supplierTravelZoneId"
                              ]
                            }
                          ]
                        },
                        "startLocation": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "address": {
                              "$ref": "#/components/schemas/Address"
                            },
                            "latitude": {
                              "type": "number",
                              "minimum": -90,
                              "maximum": 90,
                              "description": "Latitude of the address, in decimal degrees.",
                              "example": 43.6426
                            },
                            "longitude": {
                              "type": "number",
                              "minimum": -180,
                              "maximum": 180,
                              "description": "Longitude of the address, in decimal degrees.",
                              "example": -79.3871
                            }
                          },
                          "required": ["address", "latitude", "longitude"]
                        },
                        "endLocation": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "address": {
                              "$ref": "#/components/schemas/Address"
                            },
                            "latitude": {
                              "type": "number",
                              "minimum": -90,
                              "maximum": 90,
                              "description": "Latitude of the address, in decimal degrees.",
                              "example": 43.6426
                            },
                            "longitude": {
                              "type": "number",
                              "minimum": -180,
                              "maximum": 180,
                              "description": "Longitude of the address, in decimal degrees.",
                              "example": -79.3871
                            }
                          },
                          "required": ["address", "latitude", "longitude"]
                        },
                        "driveTiming": {
                          "type": "string",
                          "nullable": true,
                          "enum": ["INSIDE_HOURS", "OUTSIDE_HOURS", null]
                        },
                        "maxTravelOnStartDrive": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "maxTravelOnEndDrive": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "physicalLocationIdsInsideTravelZone": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "dateRangeLabel": {
                          "type": "string"
                        },
                        "timeRangeSummary": {
                          "type": "string"
                        },
                        "daysSummary": {
                          "type": "string"
                        },
                        "coverageAreaSummary": {
                          "type": "string"
                        },
                        "offeringsSummary": {
                          "type": "string"
                        },
                        "version": {
                          "type": "integer",
                          "minimum": 0,
                          "exclusiveMinimum": true
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "updatedAt": {
                          "type": "string"
                        },
                        "deletedAt": {
                          "type": "string"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        },
                        "deletedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "scheduleId",
                        "projectId",
                        "supplierId",
                        "status",
                        "deleted",
                        "timezone",
                        "startDate",
                        "endDate",
                        "rrule",
                        "exdates",
                        "weeklyTimeRanges",
                        "appliesToAllOfferings",
                        "serviceOfferingIds",
                        "locationRefs",
                        "dateRangeLabel",
                        "timeRangeSummary",
                        "daysSummary",
                        "coverageAreaSummary",
                        "offeringsSummary",
                        "version",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such schedule of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "VERSION_CONFLICT: the row changed since you read it; CONFLICT: it overlaps an active schedule",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "422": {
            "description": "START_END_LOCATIONS_DISABLED: the project has start and end locations off, so a value cannot be set; SETTING_NOT_DELEGATED: the project has not delegated that setting to suppliers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "delete": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Delete one of the signed-in supplier’s schedules",
        "description": "Soft-deletes the schedule (and its supplier travel zone, if no other schedule of the supplier still uses it), as the dashboard does. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The schedule — one recurring pattern of when and where the supplier works.",
              "example": "sch_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The schedule — one recurring pattern of when and where the supplier works.",
            "name": "scheduleId",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Schedule deleted"
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such schedule of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "VERSION_CONFLICT: the row changed since you read it",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/schedules/{scheduleId}/clone": {
      "post": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Clone one of the signed-in supplier’s schedules",
        "description": "A copy of the schedule, created INACTIVE so it can be edited before it offers anything. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The schedule — one recurring pattern of when and where the supplier works.",
              "example": "sch_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The schedule — one recurring pattern of when and where the supplier works.",
            "name": "scheduleId",
            "in": "path"
          }
        ],
        "responses": {
          "201": {
            "description": "Cloned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "scheduleId": {
                          "type": "string"
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "supplierId": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": ["ACTIVE", "INACTIVE"]
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "timezone": {
                          "type": "string"
                        },
                        "startDate": {
                          "type": "string"
                        },
                        "endDate": {
                          "type": "string"
                        },
                        "rrule": {
                          "type": "string"
                        },
                        "exdates": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "weeklyTimeRanges": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "dayOfWeek": {
                                "type": "string",
                                "enum": [
                                  "MO",
                                  "TU",
                                  "WE",
                                  "TH",
                                  "FR",
                                  "SA",
                                  "SU"
                                ],
                                "description": "The weekday this range falls on, in the row’s zone.",
                                "example": "MO"
                              },
                              "startTime": {
                                "type": "string",
                                "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                "description": "Wall-clock start, HH:MM in the row’s zone.",
                                "example": "09:00"
                              },
                              "endTime": {
                                "type": "string",
                                "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                "description": "Wall-clock end, HH:MM in the row’s zone; must differ from startTime.",
                                "example": "17:00"
                              },
                              "crossesMidnight": {
                                "type": "boolean",
                                "description": "True exactly when endTime is earlier than startTime (the range ends next day).",
                                "example": false
                              },
                              "sortOrder": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Display order among the ranges of one day, from 0.",
                                "example": 0
                              }
                            },
                            "required": [
                              "dayOfWeek",
                              "startTime",
                              "endTime",
                              "crossesMidnight",
                              "sortOrder"
                            ]
                          }
                        },
                        "appliesToAllOfferings": {
                          "type": "boolean"
                        },
                        "serviceOfferingIds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "locationRefs": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "locationId": {
                                "type": "string",
                                "minLength": 1,
                                "description": "A location of the project the supplier works at under this schedule.",
                                "example": "loc_01kv60qgnef2kt3pvqgwmkbzfr"
                              },
                              "locationType": {
                                "type": "string",
                                "enum": ["PHYSICAL", "VIRTUAL"],
                                "description": "PHYSICAL (an address) or VIRTUAL (online); must match the location’s own type.",
                                "example": "PHYSICAL"
                              }
                            },
                            "required": ["locationId", "locationType"]
                          }
                        },
                        "travelZoneRef": {
                          "oneOf": [
                            {
                              "type": "object",
                              "properties": {
                                "travelZoneSource": {
                                  "type": "string",
                                  "enum": ["PROJECT_LOCATION"],
                                  "description": "The zone is a TRAVEL_ZONE location defined by the project.",
                                  "example": "PROJECT_LOCATION"
                                },
                                "travelZoneLocationId": {
                                  "type": "string",
                                  "minLength": 1,
                                  "description": "The project’s TRAVEL_ZONE location.",
                                  "example": "loc_01kv60qgnef2kt3pvqgwmkbzfr"
                                }
                              },
                              "required": [
                                "travelZoneSource",
                                "travelZoneLocationId"
                              ]
                            },
                            {
                              "type": "object",
                              "properties": {
                                "travelZoneSource": {
                                  "type": "string",
                                  "enum": ["SUPPLIER_TRAVEL_ZONE"],
                                  "description": "The zone is one the supplier drew or set themselves.",
                                  "example": "SUPPLIER_TRAVEL_ZONE"
                                },
                                "supplierTravelZoneId": {
                                  "type": "string",
                                  "minLength": 1,
                                  "description": "The supplier’s own travel zone.",
                                  "example": "stz_01kv60qgnef2kt3pvqgwmkbzfr"
                                }
                              },
                              "required": [
                                "travelZoneSource",
                                "supplierTravelZoneId"
                              ]
                            }
                          ]
                        },
                        "startLocation": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "address": {
                              "$ref": "#/components/schemas/Address"
                            },
                            "latitude": {
                              "type": "number",
                              "minimum": -90,
                              "maximum": 90,
                              "description": "Latitude of the address, in decimal degrees.",
                              "example": 43.6426
                            },
                            "longitude": {
                              "type": "number",
                              "minimum": -180,
                              "maximum": 180,
                              "description": "Longitude of the address, in decimal degrees.",
                              "example": -79.3871
                            }
                          },
                          "required": ["address", "latitude", "longitude"]
                        },
                        "endLocation": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "address": {
                              "$ref": "#/components/schemas/Address"
                            },
                            "latitude": {
                              "type": "number",
                              "minimum": -90,
                              "maximum": 90,
                              "description": "Latitude of the address, in decimal degrees.",
                              "example": 43.6426
                            },
                            "longitude": {
                              "type": "number",
                              "minimum": -180,
                              "maximum": 180,
                              "description": "Longitude of the address, in decimal degrees.",
                              "example": -79.3871
                            }
                          },
                          "required": ["address", "latitude", "longitude"]
                        },
                        "driveTiming": {
                          "type": "string",
                          "nullable": true,
                          "enum": ["INSIDE_HOURS", "OUTSIDE_HOURS", null]
                        },
                        "maxTravelOnStartDrive": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "maxTravelOnEndDrive": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "physicalLocationIdsInsideTravelZone": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "dateRangeLabel": {
                          "type": "string"
                        },
                        "timeRangeSummary": {
                          "type": "string"
                        },
                        "daysSummary": {
                          "type": "string"
                        },
                        "coverageAreaSummary": {
                          "type": "string"
                        },
                        "offeringsSummary": {
                          "type": "string"
                        },
                        "version": {
                          "type": "integer",
                          "minimum": 0,
                          "exclusiveMinimum": true
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "updatedAt": {
                          "type": "string"
                        },
                        "deletedAt": {
                          "type": "string"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        },
                        "deletedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "scheduleId",
                        "projectId",
                        "supplierId",
                        "status",
                        "deleted",
                        "timezone",
                        "startDate",
                        "endDate",
                        "rrule",
                        "exdates",
                        "weeklyTimeRanges",
                        "appliesToAllOfferings",
                        "serviceOfferingIds",
                        "locationRefs",
                        "dateRangeLabel",
                        "timeRangeSummary",
                        "daysSummary",
                        "coverageAreaSummary",
                        "offeringsSummary",
                        "version",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such schedule of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/availability-timezone/apply-profile": {
      "post": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Move the signed-in supplier’s schedules and blocked times to their profile zone",
        "description": "Rewrites every schedule and blocked time of the supplier into the supplier’s profile timezone (the project default when the profile has none), keeping wall clocks; rows already in that zone are untouched. The direction is fixed: the caller never chooses a zone. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Rows moved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "timezone": {
                          "type": "string",
                          "description": "The zone the rows were moved to."
                        },
                        "schedules": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Schedules rewritten."
                        },
                        "blockedTimes": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Blocked times rewritten."
                        }
                      },
                      "required": ["timezone", "schedules", "blockedTimes"]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "No zone to move to",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such schedule of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/blocked-times": {
      "post": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Create a blocked time for the signed-in supplier",
        "description": "A period the supplier is unavailable — a holiday, a commitment of their own — as the dashboard creates one. Omit `timezone` to use the supplier’s profile zone, then the project default. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Blocked time data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": ["ACTIVE", "INACTIVE"],
                    "default": "ACTIVE",
                    "description": "ACTIVE rows are offered for booking; INACTIVE rows are kept but offer nothing.",
                    "example": "ACTIVE"
                  },
                  "timezone": {
                    "type": "string",
                    "minLength": 1,
                    "description": "IANA zone the wall-clock times are in. Omit to use the supplier’s profile zone, then the project default (R-11); never UTC by accident.",
                    "example": "America/Toronto"
                  },
                  "startDate": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                    "description": "First calendar day the row applies to, YYYY-MM-DD in its zone.",
                    "example": "2026-07-01"
                  },
                  "endDate": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                    "description": "Last calendar day the row applies to (inclusive), YYYY-MM-DD; on or after startDate.",
                    "example": "2026-07-14"
                  },
                  "rrule": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The recurrence (RFC 5545 RRULE, weekly), expanded per occurrence in the row’s zone.",
                    "example": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR"
                  },
                  "exdates": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                      "example": "2026-07-04"
                    },
                    "default": [],
                    "description": "Calendar days (YYYY-MM-DD) skipped from the recurrence.",
                    "example": []
                  },
                  "allDay": {
                    "type": "boolean",
                    "description": "True blocks the whole of each day; false blocks only timeRanges.",
                    "example": true
                  },
                  "timeRanges": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "dayOfWeek": {
                          "type": "string",
                          "enum": ["MO", "TU", "WE", "TH", "FR", "SA", "SU"],
                          "description": "The weekday this range falls on; omit for a range that applies to every day.",
                          "example": "MO"
                        },
                        "startTime": {
                          "type": "string",
                          "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                          "description": "Wall-clock start, HH:MM in the row’s zone.",
                          "example": "09:00"
                        },
                        "endTime": {
                          "type": "string",
                          "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                          "description": "Wall-clock end, HH:MM in the row’s zone; must differ from startTime.",
                          "example": "17:00"
                        },
                        "crossesMidnight": {
                          "type": "boolean",
                          "description": "True exactly when endTime is earlier than startTime (the range ends next day).",
                          "example": false
                        },
                        "sortOrder": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Display order among the ranges of one day, from 0.",
                          "example": 0
                        }
                      },
                      "required": [
                        "startTime",
                        "endTime",
                        "crossesMidnight",
                        "sortOrder"
                      ]
                    },
                    "default": [],
                    "description": "The blocked ranges when allDay is false; at least one.",
                    "example": [
                      {
                        "startTime": "12:00",
                        "endTime": "13:00",
                        "crossesMidnight": false,
                        "sortOrder": 0
                      }
                    ]
                  },
                  "notes": {
                    "type": "string",
                    "description": "A free-text note about the block, for the supplier and staff.",
                    "example": "Holiday"
                  }
                },
                "required": ["startDate", "endDate", "rrule", "allDay"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Blocked time created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "blockedTimeId": {
                          "type": "string"
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "supplierId": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": ["ACTIVE", "INACTIVE"]
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "timezone": {
                          "type": "string"
                        },
                        "startDate": {
                          "type": "string"
                        },
                        "endDate": {
                          "type": "string"
                        },
                        "rrule": {
                          "type": "string"
                        },
                        "exdates": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "allDay": {
                          "type": "boolean"
                        },
                        "timeRanges": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "dayOfWeek": {
                                "type": "string",
                                "enum": [
                                  "MO",
                                  "TU",
                                  "WE",
                                  "TH",
                                  "FR",
                                  "SA",
                                  "SU"
                                ],
                                "description": "The weekday this range falls on; omit for a range that applies to every day.",
                                "example": "MO"
                              },
                              "startTime": {
                                "type": "string",
                                "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                "description": "Wall-clock start, HH:MM in the row’s zone.",
                                "example": "09:00"
                              },
                              "endTime": {
                                "type": "string",
                                "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                "description": "Wall-clock end, HH:MM in the row’s zone; must differ from startTime.",
                                "example": "17:00"
                              },
                              "crossesMidnight": {
                                "type": "boolean",
                                "description": "True exactly when endTime is earlier than startTime (the range ends next day).",
                                "example": false
                              },
                              "sortOrder": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Display order among the ranges of one day, from 0.",
                                "example": 0
                              }
                            },
                            "required": [
                              "startTime",
                              "endTime",
                              "crossesMidnight",
                              "sortOrder"
                            ]
                          }
                        },
                        "notes": {
                          "type": "string"
                        },
                        "version": {
                          "type": "integer",
                          "minimum": 0,
                          "exclusiveMinimum": true
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "updatedAt": {
                          "type": "string"
                        },
                        "deletedAt": {
                          "type": "string"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        },
                        "deletedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "blockedTimeId",
                        "projectId",
                        "supplierId",
                        "status",
                        "deleted",
                        "timezone",
                        "startDate",
                        "endDate",
                        "rrule",
                        "exdates",
                        "allDay",
                        "timeRanges",
                        "version",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such blocked time of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "get": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "List the signed-in supplier’s blocked times",
        "description": "The supplier’s blocked times as the dashboard lists them: ACTIVE ones by default, INACTIVE and soft-deleted ones on request. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "enum": ["true", "false"],
              "description": "Also return INACTIVE blocked times.",
              "example": "false"
            },
            "required": false,
            "description": "Also return INACTIVE blocked times.",
            "name": "includeInactive",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": ["true", "false"],
              "description": "Also return soft-deleted blocked times.",
              "example": "false"
            },
            "required": false,
            "description": "Also return soft-deleted blocked times.",
            "name": "includeDeleted",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Blocked times list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "blockedTimeId": {
                            "type": "string"
                          },
                          "projectId": {
                            "type": "string"
                          },
                          "supplierId": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": ["ACTIVE", "INACTIVE"]
                          },
                          "deleted": {
                            "type": "boolean"
                          },
                          "timezone": {
                            "type": "string"
                          },
                          "startDate": {
                            "type": "string"
                          },
                          "endDate": {
                            "type": "string"
                          },
                          "rrule": {
                            "type": "string"
                          },
                          "exdates": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "allDay": {
                            "type": "boolean"
                          },
                          "timeRanges": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "dayOfWeek": {
                                  "type": "string",
                                  "enum": [
                                    "MO",
                                    "TU",
                                    "WE",
                                    "TH",
                                    "FR",
                                    "SA",
                                    "SU"
                                  ],
                                  "description": "The weekday this range falls on; omit for a range that applies to every day.",
                                  "example": "MO"
                                },
                                "startTime": {
                                  "type": "string",
                                  "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                  "description": "Wall-clock start, HH:MM in the row’s zone.",
                                  "example": "09:00"
                                },
                                "endTime": {
                                  "type": "string",
                                  "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                  "description": "Wall-clock end, HH:MM in the row’s zone; must differ from startTime.",
                                  "example": "17:00"
                                },
                                "crossesMidnight": {
                                  "type": "boolean",
                                  "description": "True exactly when endTime is earlier than startTime (the range ends next day).",
                                  "example": false
                                },
                                "sortOrder": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "Display order among the ranges of one day, from 0.",
                                  "example": 0
                                }
                              },
                              "required": [
                                "startTime",
                                "endTime",
                                "crossesMidnight",
                                "sortOrder"
                              ]
                            }
                          },
                          "notes": {
                            "type": "string"
                          },
                          "version": {
                            "type": "integer",
                            "minimum": 0,
                            "exclusiveMinimum": true
                          },
                          "createdAt": {
                            "type": "string"
                          },
                          "updatedAt": {
                            "type": "string"
                          },
                          "deletedAt": {
                            "type": "string"
                          },
                          "createdBy": {
                            "type": "string"
                          },
                          "updatedBy": {
                            "type": "string"
                          },
                          "deletedBy": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "blockedTimeId",
                          "projectId",
                          "supplierId",
                          "status",
                          "deleted",
                          "timezone",
                          "startDate",
                          "endDate",
                          "rrule",
                          "exdates",
                          "allDay",
                          "timeRanges",
                          "version",
                          "createdAt",
                          "updatedAt",
                          "createdBy",
                          "updatedBy"
                        ]
                      }
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such blocked time of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/blocked-times/{blockedTimeId}": {
      "get": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Get one of the signed-in supplier’s blocked times",
        "description": "One blocked time by id, if it belongs to the supplier the user token resolves to. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The blocked time — a one-off or recurring period the supplier is unavailable.",
              "example": "blk_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The blocked time — a one-off or recurring period the supplier is unavailable.",
            "name": "blockedTimeId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Blocked time",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "blockedTimeId": {
                          "type": "string"
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "supplierId": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": ["ACTIVE", "INACTIVE"]
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "timezone": {
                          "type": "string"
                        },
                        "startDate": {
                          "type": "string"
                        },
                        "endDate": {
                          "type": "string"
                        },
                        "rrule": {
                          "type": "string"
                        },
                        "exdates": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "allDay": {
                          "type": "boolean"
                        },
                        "timeRanges": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "dayOfWeek": {
                                "type": "string",
                                "enum": [
                                  "MO",
                                  "TU",
                                  "WE",
                                  "TH",
                                  "FR",
                                  "SA",
                                  "SU"
                                ],
                                "description": "The weekday this range falls on; omit for a range that applies to every day.",
                                "example": "MO"
                              },
                              "startTime": {
                                "type": "string",
                                "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                "description": "Wall-clock start, HH:MM in the row’s zone.",
                                "example": "09:00"
                              },
                              "endTime": {
                                "type": "string",
                                "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                "description": "Wall-clock end, HH:MM in the row’s zone; must differ from startTime.",
                                "example": "17:00"
                              },
                              "crossesMidnight": {
                                "type": "boolean",
                                "description": "True exactly when endTime is earlier than startTime (the range ends next day).",
                                "example": false
                              },
                              "sortOrder": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Display order among the ranges of one day, from 0.",
                                "example": 0
                              }
                            },
                            "required": [
                              "startTime",
                              "endTime",
                              "crossesMidnight",
                              "sortOrder"
                            ]
                          }
                        },
                        "notes": {
                          "type": "string"
                        },
                        "version": {
                          "type": "integer",
                          "minimum": 0,
                          "exclusiveMinimum": true
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "updatedAt": {
                          "type": "string"
                        },
                        "deletedAt": {
                          "type": "string"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        },
                        "deletedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "blockedTimeId",
                        "projectId",
                        "supplierId",
                        "status",
                        "deleted",
                        "timezone",
                        "startDate",
                        "endDate",
                        "rrule",
                        "exdates",
                        "allDay",
                        "timeRanges",
                        "version",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such blocked time of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "patch": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Update one of the signed-in supplier’s blocked times",
        "description": "Change any of the blocked time’s fields; send the row’s current `version` (optimistic concurrency — a stale one is a 409). Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The blocked time — a one-off or recurring period the supplier is unavailable.",
              "example": "blk_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The blocked time — a one-off or recurring period the supplier is unavailable.",
            "name": "blockedTimeId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Fields to update",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": ["ACTIVE", "INACTIVE"],
                    "description": "ACTIVE rows are offered for booking; INACTIVE rows are kept but offer nothing.",
                    "example": "ACTIVE"
                  },
                  "timezone": {
                    "type": "string",
                    "minLength": 1,
                    "description": "IANA zone the wall-clock times are in. Omit to use the supplier’s profile zone, then the project default (R-11); never UTC by accident.",
                    "example": "America/Toronto"
                  },
                  "startDate": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                    "description": "First calendar day the row applies to, YYYY-MM-DD in its zone.",
                    "example": "2026-07-01"
                  },
                  "endDate": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                    "description": "Last calendar day the row applies to (inclusive), YYYY-MM-DD; on or after startDate.",
                    "example": "2026-07-14"
                  },
                  "rrule": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The recurrence (RFC 5545 RRULE, weekly), expanded per occurrence in the row’s zone.",
                    "example": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR"
                  },
                  "exdates": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                      "example": "2026-07-04"
                    },
                    "description": "Calendar days (YYYY-MM-DD) skipped from the recurrence.",
                    "example": []
                  },
                  "allDay": {
                    "type": "boolean",
                    "description": "True blocks the whole of each day; false blocks only timeRanges.",
                    "example": true
                  },
                  "timeRanges": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "dayOfWeek": {
                          "type": "string",
                          "enum": ["MO", "TU", "WE", "TH", "FR", "SA", "SU"],
                          "description": "The weekday this range falls on; omit for a range that applies to every day.",
                          "example": "MO"
                        },
                        "startTime": {
                          "type": "string",
                          "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                          "description": "Wall-clock start, HH:MM in the row’s zone.",
                          "example": "09:00"
                        },
                        "endTime": {
                          "type": "string",
                          "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                          "description": "Wall-clock end, HH:MM in the row’s zone; must differ from startTime.",
                          "example": "17:00"
                        },
                        "crossesMidnight": {
                          "type": "boolean",
                          "description": "True exactly when endTime is earlier than startTime (the range ends next day).",
                          "example": false
                        },
                        "sortOrder": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Display order among the ranges of one day, from 0.",
                          "example": 0
                        }
                      },
                      "required": [
                        "startTime",
                        "endTime",
                        "crossesMidnight",
                        "sortOrder"
                      ]
                    },
                    "description": "The blocked ranges when allDay is false; at least one.",
                    "example": [
                      {
                        "startTime": "12:00",
                        "endTime": "13:00",
                        "crossesMidnight": false,
                        "sortOrder": 0
                      }
                    ]
                  },
                  "notes": {
                    "type": "string",
                    "nullable": true,
                    "description": "A free-text note about the block, for the supplier and staff. Send null to clear it.",
                    "example": "Holiday"
                  },
                  "version": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "description": "The row’s current version, for optimistic concurrency; a stale value is a 409.",
                    "example": 2
                  }
                },
                "required": ["version"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Blocked time updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "blockedTimeId": {
                          "type": "string"
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "supplierId": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": ["ACTIVE", "INACTIVE"]
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "timezone": {
                          "type": "string"
                        },
                        "startDate": {
                          "type": "string"
                        },
                        "endDate": {
                          "type": "string"
                        },
                        "rrule": {
                          "type": "string"
                        },
                        "exdates": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "allDay": {
                          "type": "boolean"
                        },
                        "timeRanges": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "dayOfWeek": {
                                "type": "string",
                                "enum": [
                                  "MO",
                                  "TU",
                                  "WE",
                                  "TH",
                                  "FR",
                                  "SA",
                                  "SU"
                                ],
                                "description": "The weekday this range falls on; omit for a range that applies to every day.",
                                "example": "MO"
                              },
                              "startTime": {
                                "type": "string",
                                "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                "description": "Wall-clock start, HH:MM in the row’s zone.",
                                "example": "09:00"
                              },
                              "endTime": {
                                "type": "string",
                                "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                "description": "Wall-clock end, HH:MM in the row’s zone; must differ from startTime.",
                                "example": "17:00"
                              },
                              "crossesMidnight": {
                                "type": "boolean",
                                "description": "True exactly when endTime is earlier than startTime (the range ends next day).",
                                "example": false
                              },
                              "sortOrder": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "Display order among the ranges of one day, from 0.",
                                "example": 0
                              }
                            },
                            "required": [
                              "startTime",
                              "endTime",
                              "crossesMidnight",
                              "sortOrder"
                            ]
                          }
                        },
                        "notes": {
                          "type": "string"
                        },
                        "version": {
                          "type": "integer",
                          "minimum": 0,
                          "exclusiveMinimum": true
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "updatedAt": {
                          "type": "string"
                        },
                        "deletedAt": {
                          "type": "string"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        },
                        "deletedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "blockedTimeId",
                        "projectId",
                        "supplierId",
                        "status",
                        "deleted",
                        "timezone",
                        "startDate",
                        "endDate",
                        "rrule",
                        "exdates",
                        "allDay",
                        "timeRanges",
                        "version",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such blocked time of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "VERSION_CONFLICT: the row changed since you read it",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "delete": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Delete one of the signed-in supplier’s blocked times",
        "description": "Soft-deletes the blocked time, as the dashboard does. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The blocked time — a one-off or recurring period the supplier is unavailable.",
              "example": "blk_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The blocked time — a one-off or recurring period the supplier is unavailable.",
            "name": "blockedTimeId",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Blocked time deleted"
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such blocked time of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "VERSION_CONFLICT: the row changed since you read it",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/demand": {
      "get": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "The signed-in supplier’s Week & demand view",
        "description": "Booked, searched and unfilled demand by hour of week over the supplier’s area, with their bookable hours, a glance and suggestions — the same view the MarketBox dashboard shows them. Hours are the supplier’s home zone, derived per instant from the rollup’s UTC buckets. Counts of 1–2 read \"few\"; fewer than 20 bookings in the window is `not_enough_data` with no grid. Requires the API key and the supplier’s user token. 403 `INSIGHTS_DISABLED` when the project’s Week & demand switch is off.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "enum": ["zone", "wider"],
              "default": "zone",
              "description": "Your travel zone, or the zone plus a 15-minute drive"
            },
            "required": false,
            "description": "Your travel zone, or the zone plus a 15-minute drive",
            "name": "area",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": ["30", "90", "180"],
              "default": "30",
              "description": "The trailing window, in whole UTC days ending today"
            },
            "required": false,
            "description": "The trailing window, in whole UTC days ending today",
            "name": "days",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "The demand view",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "state": {
                          "type": "string",
                          "enum": ["ok", "not_enough_data", "no_area"]
                        },
                        "window": {
                          "type": "object",
                          "properties": {
                            "days": {
                              "anyOf": [
                                {
                                  "type": "number",
                                  "enum": [30]
                                },
                                {
                                  "type": "number",
                                  "enum": [90]
                                },
                                {
                                  "type": "number",
                                  "enum": [180]
                                }
                              ]
                            },
                            "fromUtcDate": {
                              "type": "string"
                            },
                            "toUtcDate": {
                              "type": "string"
                            },
                            "area": {
                              "type": "string",
                              "enum": ["zone", "wider"]
                            },
                            "zone": {
                              "type": "string",
                              "minLength": 1
                            },
                            "weekStart": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "days",
                            "fromUtcDate",
                            "toUtcDate",
                            "area",
                            "zone",
                            "weekStart"
                          ],
                          "additionalProperties": false
                        },
                        "zoneLabel": {
                          "type": "string",
                          "minLength": 1
                        },
                        "area": {
                          "type": "object",
                          "properties": {
                            "source": {
                              "type": "string",
                              "enum": ["travel_zone", "locations", "none"],
                              "description": "travel_zone: the schedules travel-zone cells; locations: 30/45-minute drive circles around fixed locations; none: no_area"
                            },
                            "cells": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "complete": {
                              "type": "boolean"
                            },
                            "label": {
                              "type": "string",
                              "minLength": 1
                            }
                          },
                          "required": ["source", "cells", "complete", "label"],
                          "additionalProperties": false
                        },
                        "grid": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "booked": {
                              "type": "array",
                              "items": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "level": {
                                      "type": "integer",
                                      "minimum": 0,
                                      "maximum": 5
                                    },
                                    "count": {
                                      "anyOf": [
                                        {
                                          "type": "integer",
                                          "minimum": 0
                                        },
                                        {
                                          "type": "string",
                                          "enum": ["few"]
                                        }
                                      ]
                                    }
                                  },
                                  "required": ["level", "count"],
                                  "additionalProperties": false
                                }
                              },
                              "description": "[day MON…SUN][hour 6 AM…9 PM] in window.zone"
                            },
                            "searched": {
                              "type": "array",
                              "items": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "level": {
                                      "type": "integer",
                                      "minimum": 0,
                                      "maximum": 5
                                    },
                                    "count": {
                                      "anyOf": [
                                        {
                                          "type": "integer",
                                          "minimum": 0
                                        },
                                        {
                                          "type": "string",
                                          "enum": ["few"]
                                        }
                                      ]
                                    }
                                  },
                                  "required": ["level", "count"],
                                  "additionalProperties": false
                                }
                              },
                              "description": "[day MON…SUN][hour 6 AM…9 PM] in window.zone"
                            },
                            "unfilled": {
                              "type": "array",
                              "items": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "level": {
                                      "type": "integer",
                                      "minimum": 0,
                                      "maximum": 5
                                    },
                                    "count": {
                                      "anyOf": [
                                        {
                                          "type": "integer",
                                          "minimum": 0
                                        },
                                        {
                                          "type": "string",
                                          "enum": ["few"]
                                        }
                                      ]
                                    }
                                  },
                                  "required": ["level", "count"],
                                  "additionalProperties": false
                                }
                              },
                              "description": "[day MON…SUN][hour 6 AM…9 PM] in window.zone"
                            }
                          },
                          "required": ["booked", "searched", "unfilled"],
                          "additionalProperties": false
                        },
                        "bookableMask": {
                          "type": "array",
                          "items": {
                            "type": "array",
                            "items": {
                              "type": "boolean"
                            }
                          }
                        },
                        "glance": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "bookableHours": {
                              "type": "number",
                              "minimum": 0
                            },
                            "busyBookableHours": {
                              "type": "number",
                              "minimum": 0
                            },
                            "busyNotBookableHours": {
                              "type": "number",
                              "minimum": 0
                            },
                            "ranges": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "day": {
                                    "type": "string",
                                    "enum": [
                                      "MON",
                                      "TUE",
                                      "WED",
                                      "THU",
                                      "FRI",
                                      "SAT",
                                      "SUN"
                                    ]
                                  },
                                  "start": {
                                    "type": "string",
                                    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                    "description": "Local wall clock, HH:MM, in window.zone"
                                  },
                                  "end": {
                                    "type": "string",
                                    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                    "description": "Local wall clock, HH:MM, in window.zone"
                                  },
                                  "bookable": {
                                    "type": "boolean"
                                  },
                                  "level": {
                                    "type": "integer",
                                    "minimum": 1,
                                    "maximum": 5
                                  }
                                },
                                "required": [
                                  "day",
                                  "start",
                                  "end",
                                  "bookable",
                                  "level"
                                ],
                                "additionalProperties": false
                              }
                            }
                          },
                          "required": [
                            "bookableHours",
                            "busyBookableHours",
                            "busyNotBookableHours",
                            "ranges"
                          ],
                          "additionalProperties": false
                        },
                        "suggestions": {
                          "type": "array",
                          "items": {
                            "oneOf": [
                              {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "type": "string",
                                    "pattern": "^(open|quiet):(MON|TUE|WED|THU|FRI|SAT|SUN):([01]\\d|2[0-3]):[0-5]\\d-([01]\\d|2[0-3]):[0-5]\\d$"
                                  },
                                  "day": {
                                    "type": "string",
                                    "enum": [
                                      "MON",
                                      "TUE",
                                      "WED",
                                      "THU",
                                      "FRI",
                                      "SAT",
                                      "SUN"
                                    ]
                                  },
                                  "start": {
                                    "type": "string",
                                    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                    "description": "Local wall clock, HH:MM, in window.zone"
                                  },
                                  "end": {
                                    "type": "string",
                                    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                    "description": "Exclusive end, HH:MM local"
                                  },
                                  "booked": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "kind": {
                                    "type": "string",
                                    "enum": ["open"]
                                  },
                                  "unfilled": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "prefill": {
                                    "type": "object",
                                    "properties": {
                                      "weeklyTimeRanges": {
                                        "type": "array",
                                        "items": {
                                          "type": "object",
                                          "properties": {
                                            "dayOfWeek": {
                                              "type": "string",
                                              "enum": [
                                                "MO",
                                                "TU",
                                                "WE",
                                                "TH",
                                                "FR",
                                                "SA",
                                                "SU"
                                              ],
                                              "description": "The weekday this range falls on, in the row’s zone.",
                                              "example": "MO"
                                            },
                                            "startTime": {
                                              "type": "string",
                                              "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                              "description": "Wall-clock start, HH:MM in the row’s zone.",
                                              "example": "09:00"
                                            },
                                            "endTime": {
                                              "type": "string",
                                              "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                              "description": "Wall-clock end, HH:MM in the row’s zone; must differ from startTime.",
                                              "example": "17:00"
                                            },
                                            "crossesMidnight": {
                                              "type": "boolean",
                                              "description": "True exactly when endTime is earlier than startTime (the range ends next day).",
                                              "example": false
                                            },
                                            "sortOrder": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "description": "Display order among the ranges of one day, from 0.",
                                              "example": 0
                                            }
                                          },
                                          "required": [
                                            "dayOfWeek",
                                            "startTime",
                                            "endTime",
                                            "crossesMidnight",
                                            "sortOrder"
                                          ]
                                        },
                                        "minItems": 1
                                      }
                                    },
                                    "required": ["weeklyTimeRanges"],
                                    "additionalProperties": false
                                  }
                                },
                                "required": [
                                  "key",
                                  "day",
                                  "start",
                                  "end",
                                  "booked",
                                  "kind",
                                  "unfilled",
                                  "prefill"
                                ],
                                "additionalProperties": false
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "type": "string",
                                    "pattern": "^(open|quiet):(MON|TUE|WED|THU|FRI|SAT|SUN):([01]\\d|2[0-3]):[0-5]\\d-([01]\\d|2[0-3]):[0-5]\\d$"
                                  },
                                  "day": {
                                    "type": "string",
                                    "enum": [
                                      "MON",
                                      "TUE",
                                      "WED",
                                      "THU",
                                      "FRI",
                                      "SAT",
                                      "SUN"
                                    ]
                                  },
                                  "start": {
                                    "type": "string",
                                    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                    "description": "Local wall clock, HH:MM, in window.zone"
                                  },
                                  "end": {
                                    "type": "string",
                                    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                    "description": "Exclusive end, HH:MM local"
                                  },
                                  "booked": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "kind": {
                                    "type": "string",
                                    "enum": ["quiet"]
                                  },
                                  "scheduleId": {
                                    "type": "string",
                                    "minLength": 1
                                  }
                                },
                                "required": [
                                  "key",
                                  "day",
                                  "start",
                                  "end",
                                  "booked",
                                  "kind",
                                  "scheduleId"
                                ],
                                "additionalProperties": false
                              }
                            ]
                          }
                        },
                        "asOf": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "complete": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "state",
                        "window",
                        "zoneLabel",
                        "area",
                        "grid",
                        "bookableMask",
                        "glance",
                        "suggestions",
                        "asOf",
                        "complete"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD); or INSIGHTS_DISABLED (the project turned the feature off)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/demand/suggestions/{key}/dismiss": {
      "post": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Dismiss one of the signed-in supplier’s demand suggestions for 90 days",
        "description": "\"Keep these hours\": hides the suggestion with this key from the demand view (and from Search insights) for 90 days. Idempotent; the dashboard shows the same dismissal. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^(open|quiet):(MON|TUE|WED|THU|FRI|SAT|SUN):([01]\\d|2[0-3]):[0-5]\\d-([01]\\d|2[0-3]):[0-5]\\d$",
              "description": "The suggestion’s key as the demand response gives it, e.g. `open:WED:14:00-16:00`.",
              "example": "open:WED:14:00-16:00"
            },
            "required": true,
            "description": "The suggestion’s key as the demand response gives it, e.g. `open:WED:14:00-16:00`.",
            "name": "key",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Dismissed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "key": {
                          "type": "string",
                          "pattern": "^(open|quiet):(MON|TUE|WED|THU|FRI|SAT|SUN):([01]\\d|2[0-3]):[0-5]\\d-([01]\\d|2[0-3]):[0-5]\\d$"
                        },
                        "dismissed": {
                          "type": "boolean"
                        },
                        "until": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        }
                      },
                      "required": ["key", "dismissed", "until"],
                      "additionalProperties": false
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Not a suggestion key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD); or INSIGHTS_DISABLED (the project turned the feature off)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "delete": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Undo a dismissal: the suggestion shows again when the data still supports it",
        "description": "Removes the 90-day dismissal of this key. Idempotent: 200 with `dismissed: false` whether or not one was on file. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^(open|quiet):(MON|TUE|WED|THU|FRI|SAT|SUN):([01]\\d|2[0-3]):[0-5]\\d-([01]\\d|2[0-3]):[0-5]\\d$",
              "description": "The suggestion’s key as the demand response gives it, e.g. `open:WED:14:00-16:00`.",
              "example": "open:WED:14:00-16:00"
            },
            "required": true,
            "description": "The suggestion’s key as the demand response gives it, e.g. `open:WED:14:00-16:00`.",
            "name": "key",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Dismissal removed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "key": {
                          "type": "string",
                          "pattern": "^(open|quiet):(MON|TUE|WED|THU|FRI|SAT|SUN):([01]\\d|2[0-3]):[0-5]\\d-([01]\\d|2[0-3]):[0-5]\\d$"
                        },
                        "dismissed": {
                          "type": "boolean"
                        },
                        "until": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        }
                      },
                      "required": ["key", "dismissed", "until"],
                      "additionalProperties": false
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Not a suggestion key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD); or INSIGHTS_DISABLED (the project turned the feature off)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/search-insights": {
      "get": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "The signed-in supplier’s Search insights",
        "description": "Shown, Seen, profile opens, open rate, bookings from search, average position, missed searches by reason and the channel / service / area / time-asked breakdowns, each with the previous equal-length period and a daily series — the dashboard’s Search insights tab. `?days=7|28|90` (default 28) or `?from=YYYY-MM-DD&to=YYYY-MM-DD` (at most 365 days), dates in the supplier’s home zone. `nothing_yet` when no counted search involved the supplier in either window. Requires the API key and the supplier’s user token. 403 `INSIGHTS_DISABLED` when the project’s Search insights switch is off.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "enum": ["7", "28", "90"],
              "description": "A trailing window of whole days ending today in your home zone"
            },
            "required": false,
            "description": "A trailing window of whole days ending today in your home zone",
            "name": "days",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "First day of a custom range, YYYY-MM-DD in your home zone"
            },
            "required": false,
            "description": "First day of a custom range, YYYY-MM-DD in your home zone",
            "name": "from",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Last day of a custom range (inclusive), YYYY-MM-DD"
            },
            "required": false,
            "description": "Last day of a custom range (inclusive), YYYY-MM-DD",
            "name": "to",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "The search insights",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "state": {
                          "type": "string",
                          "enum": ["ok", "nothing_yet"]
                        },
                        "window": {
                          "type": "object",
                          "properties": {
                            "preset": {
                              "anyOf": [
                                {
                                  "type": "number",
                                  "enum": [7]
                                },
                                {
                                  "type": "number",
                                  "enum": [28]
                                },
                                {
                                  "type": "number",
                                  "enum": [90]
                                },
                                {
                                  "nullable": true
                                }
                              ]
                            },
                            "from": {
                              "type": "string"
                            },
                            "to": {
                              "type": "string"
                            },
                            "days": {
                              "type": "integer",
                              "minimum": 1,
                              "maximum": 365
                            },
                            "zone": {
                              "type": "string",
                              "minLength": 1
                            }
                          },
                          "required": ["preset", "from", "to", "days", "zone"],
                          "additionalProperties": false
                        },
                        "previous": {
                          "type": "object",
                          "properties": {
                            "from": {
                              "type": "string"
                            },
                            "to": {
                              "type": "string"
                            },
                            "days": {
                              "type": "integer",
                              "minimum": 1,
                              "maximum": 365
                            }
                          },
                          "required": ["from", "to", "days"],
                          "additionalProperties": false
                        },
                        "tiles": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "shown": {
                              "type": "object",
                              "properties": {
                                "value": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "previous": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "delta": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "series": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "date": {
                                        "type": "string"
                                      },
                                      "value": {
                                        "type": "number",
                                        "nullable": true
                                      }
                                    },
                                    "required": ["date", "value"],
                                    "additionalProperties": false
                                  }
                                },
                                "previousSeries": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "date": {
                                        "type": "string"
                                      },
                                      "value": {
                                        "type": "number",
                                        "nullable": true
                                      }
                                    },
                                    "required": ["date", "value"],
                                    "additionalProperties": false
                                  }
                                }
                              },
                              "required": [
                                "value",
                                "previous",
                                "delta",
                                "series",
                                "previousSeries"
                              ],
                              "additionalProperties": false
                            },
                            "seen": {
                              "type": "object",
                              "properties": {
                                "value": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "previous": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "delta": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "series": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "date": {
                                        "type": "string"
                                      },
                                      "value": {
                                        "type": "number",
                                        "nullable": true
                                      }
                                    },
                                    "required": ["date", "value"],
                                    "additionalProperties": false
                                  }
                                },
                                "previousSeries": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "date": {
                                        "type": "string"
                                      },
                                      "value": {
                                        "type": "number",
                                        "nullable": true
                                      }
                                    },
                                    "required": ["date", "value"],
                                    "additionalProperties": false
                                  }
                                }
                              },
                              "required": [
                                "value",
                                "previous",
                                "delta",
                                "series",
                                "previousSeries"
                              ],
                              "additionalProperties": false
                            },
                            "opens": {
                              "type": "object",
                              "properties": {
                                "value": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "previous": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "delta": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "series": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "date": {
                                        "type": "string"
                                      },
                                      "value": {
                                        "type": "number",
                                        "nullable": true
                                      }
                                    },
                                    "required": ["date", "value"],
                                    "additionalProperties": false
                                  }
                                },
                                "previousSeries": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "date": {
                                        "type": "string"
                                      },
                                      "value": {
                                        "type": "number",
                                        "nullable": true
                                      }
                                    },
                                    "required": ["date", "value"],
                                    "additionalProperties": false
                                  }
                                }
                              },
                              "required": [
                                "value",
                                "previous",
                                "delta",
                                "series",
                                "previousSeries"
                              ],
                              "additionalProperties": false
                            },
                            "openRate": {
                              "type": "object",
                              "properties": {
                                "value": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "previous": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "delta": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "series": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "date": {
                                        "type": "string"
                                      },
                                      "value": {
                                        "type": "number",
                                        "nullable": true
                                      }
                                    },
                                    "required": ["date", "value"],
                                    "additionalProperties": false
                                  }
                                },
                                "previousSeries": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "date": {
                                        "type": "string"
                                      },
                                      "value": {
                                        "type": "number",
                                        "nullable": true
                                      }
                                    },
                                    "required": ["date", "value"],
                                    "additionalProperties": false
                                  }
                                }
                              },
                              "required": [
                                "value",
                                "previous",
                                "delta",
                                "series",
                                "previousSeries"
                              ],
                              "additionalProperties": false
                            },
                            "bookings": {
                              "type": "object",
                              "properties": {
                                "value": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "previous": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "delta": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "series": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "date": {
                                        "type": "string"
                                      },
                                      "value": {
                                        "type": "number",
                                        "nullable": true
                                      }
                                    },
                                    "required": ["date", "value"],
                                    "additionalProperties": false
                                  }
                                },
                                "previousSeries": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "date": {
                                        "type": "string"
                                      },
                                      "value": {
                                        "type": "number",
                                        "nullable": true
                                      }
                                    },
                                    "required": ["date", "value"],
                                    "additionalProperties": false
                                  }
                                }
                              },
                              "required": [
                                "value",
                                "previous",
                                "delta",
                                "series",
                                "previousSeries"
                              ],
                              "additionalProperties": false
                            },
                            "position": {
                              "type": "object",
                              "properties": {
                                "value": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "previous": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "delta": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "series": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "date": {
                                        "type": "string"
                                      },
                                      "value": {
                                        "type": "number",
                                        "nullable": true
                                      }
                                    },
                                    "required": ["date", "value"],
                                    "additionalProperties": false
                                  }
                                },
                                "previousSeries": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "date": {
                                        "type": "string"
                                      },
                                      "value": {
                                        "type": "number",
                                        "nullable": true
                                      }
                                    },
                                    "required": ["date", "value"],
                                    "additionalProperties": false
                                  }
                                }
                              },
                              "required": [
                                "value",
                                "previous",
                                "delta",
                                "series",
                                "previousSeries"
                              ],
                              "additionalProperties": false
                            }
                          },
                          "required": [
                            "shown",
                            "seen",
                            "opens",
                            "openRate",
                            "bookings",
                            "position"
                          ],
                          "additionalProperties": false
                        },
                        "seenReporting": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "reporting": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "total": {
                              "type": "integer",
                              "minimum": 0
                            }
                          },
                          "required": ["reporting", "total"],
                          "additionalProperties": false
                        },
                        "missed": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "total": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "byReason": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "reason": {
                                    "type": "string",
                                    "enum": [
                                      "NOT_FREE",
                                      "NO_SERVICE",
                                      "OUTSIDE_TRAVEL"
                                    ]
                                  },
                                  "count": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "share": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1
                                  },
                                  "detail": {
                                    "oneOf": [
                                      {
                                        "type": "object",
                                        "properties": {
                                          "kind": {
                                            "type": "string",
                                            "enum": ["asked_time"]
                                          },
                                          "grid": {
                                            "type": "array",
                                            "items": {
                                              "type": "array",
                                              "items": {
                                                "type": "object",
                                                "properties": {
                                                  "level": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 5
                                                  },
                                                  "count": {
                                                    "anyOf": [
                                                      {
                                                        "type": "integer",
                                                        "minimum": 0
                                                      },
                                                      {
                                                        "type": "string",
                                                        "enum": ["few"]
                                                      }
                                                    ]
                                                  }
                                                },
                                                "required": ["level", "count"],
                                                "additionalProperties": false
                                              }
                                            },
                                            "description": "[day MON…SUN][hour 6 AM…9 PM] in window.zone"
                                          },
                                          "ranges": {
                                            "type": "array",
                                            "items": {
                                              "type": "object",
                                              "properties": {
                                                "day": {
                                                  "type": "string",
                                                  "enum": [
                                                    "MON",
                                                    "TUE",
                                                    "WED",
                                                    "THU",
                                                    "FRI",
                                                    "SAT",
                                                    "SUN"
                                                  ]
                                                },
                                                "start": {
                                                  "type": "string",
                                                  "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
                                                },
                                                "end": {
                                                  "type": "string",
                                                  "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                                  "description": "Exclusive end, HH:MM local"
                                                },
                                                "count": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "level": {
                                                  "type": "integer",
                                                  "minimum": 1,
                                                  "maximum": 5
                                                }
                                              },
                                              "required": [
                                                "day",
                                                "start",
                                                "end",
                                                "count",
                                                "level"
                                              ],
                                              "additionalProperties": false
                                            }
                                          }
                                        },
                                        "required": ["kind", "grid", "ranges"],
                                        "additionalProperties": false
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "kind": {
                                            "type": "string",
                                            "enum": ["services"]
                                          },
                                          "items": {
                                            "type": "array",
                                            "items": {
                                              "type": "object",
                                              "properties": {
                                                "key": {
                                                  "type": "string",
                                                  "minLength": 1
                                                },
                                                "label": {
                                                  "type": "string",
                                                  "minLength": 1
                                                },
                                                "count": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                }
                                              },
                                              "required": [
                                                "key",
                                                "label",
                                                "count"
                                              ],
                                              "additionalProperties": false
                                            }
                                          }
                                        },
                                        "required": ["kind", "items"],
                                        "additionalProperties": false
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "kind": {
                                            "type": "string",
                                            "enum": ["distance"]
                                          },
                                          "bands": {
                                            "type": "array",
                                            "items": {
                                              "type": "object",
                                              "properties": {
                                                "fromKm": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "toKm": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "count": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                }
                                              },
                                              "required": [
                                                "fromKm",
                                                "toKm",
                                                "count"
                                              ],
                                              "additionalProperties": false
                                            }
                                          }
                                        },
                                        "required": ["kind", "bands"],
                                        "additionalProperties": false
                                      }
                                    ]
                                  }
                                },
                                "required": [
                                  "reason",
                                  "count",
                                  "share",
                                  "detail"
                                ],
                                "additionalProperties": false
                              }
                            }
                          },
                          "required": ["total", "byReason"],
                          "additionalProperties": false
                        },
                        "breakdowns": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "channel": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "type": "string",
                                    "minLength": 1
                                  },
                                  "label": {
                                    "type": "string",
                                    "minLength": 1
                                  },
                                  "shown": {
                                    "type": "integer",
                                    "nullable": true,
                                    "minimum": 0
                                  },
                                  "seen": {
                                    "type": "integer",
                                    "nullable": true,
                                    "minimum": 0
                                  },
                                  "opens": {
                                    "type": "integer",
                                    "nullable": true,
                                    "minimum": 0
                                  },
                                  "openRate": {
                                    "type": "number",
                                    "nullable": true,
                                    "minimum": 0,
                                    "maximum": 1
                                  },
                                  "missed": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "note": {
                                    "type": "string",
                                    "minLength": 1
                                  }
                                },
                                "required": [
                                  "key",
                                  "label",
                                  "shown",
                                  "seen",
                                  "opens",
                                  "openRate"
                                ],
                                "additionalProperties": false
                              }
                            },
                            "service": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "type": "string",
                                    "minLength": 1
                                  },
                                  "label": {
                                    "type": "string",
                                    "minLength": 1
                                  },
                                  "shown": {
                                    "type": "integer",
                                    "nullable": true,
                                    "minimum": 0
                                  },
                                  "seen": {
                                    "type": "integer",
                                    "nullable": true,
                                    "minimum": 0
                                  },
                                  "opens": {
                                    "type": "integer",
                                    "nullable": true,
                                    "minimum": 0
                                  },
                                  "openRate": {
                                    "type": "number",
                                    "nullable": true,
                                    "minimum": 0,
                                    "maximum": 1
                                  },
                                  "missed": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "note": {
                                    "type": "string",
                                    "minLength": 1
                                  }
                                },
                                "required": [
                                  "key",
                                  "label",
                                  "shown",
                                  "seen",
                                  "opens",
                                  "openRate"
                                ],
                                "additionalProperties": false
                              }
                            },
                            "area": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "type": "string",
                                    "minLength": 1
                                  },
                                  "label": {
                                    "type": "string",
                                    "minLength": 1
                                  },
                                  "shown": {
                                    "type": "integer",
                                    "nullable": true,
                                    "minimum": 0
                                  },
                                  "seen": {
                                    "type": "integer",
                                    "nullable": true,
                                    "minimum": 0
                                  },
                                  "opens": {
                                    "type": "integer",
                                    "nullable": true,
                                    "minimum": 0
                                  },
                                  "openRate": {
                                    "type": "number",
                                    "nullable": true,
                                    "minimum": 0,
                                    "maximum": 1
                                  },
                                  "missed": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "note": {
                                    "type": "string",
                                    "minLength": 1
                                  }
                                },
                                "required": [
                                  "key",
                                  "label",
                                  "shown",
                                  "seen",
                                  "opens",
                                  "openRate"
                                ],
                                "additionalProperties": false
                              }
                            },
                            "timeAsked": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "type": "string",
                                    "minLength": 1
                                  },
                                  "label": {
                                    "type": "string",
                                    "minLength": 1
                                  },
                                  "shown": {
                                    "type": "integer",
                                    "nullable": true,
                                    "minimum": 0
                                  },
                                  "seen": {
                                    "type": "integer",
                                    "nullable": true,
                                    "minimum": 0
                                  },
                                  "opens": {
                                    "type": "integer",
                                    "nullable": true,
                                    "minimum": 0
                                  },
                                  "openRate": {
                                    "type": "number",
                                    "nullable": true,
                                    "minimum": 0,
                                    "maximum": 1
                                  },
                                  "missed": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "note": {
                                    "type": "string",
                                    "minLength": 1
                                  }
                                },
                                "required": [
                                  "key",
                                  "label",
                                  "shown",
                                  "seen",
                                  "opens",
                                  "openRate"
                                ],
                                "additionalProperties": false
                              }
                            }
                          },
                          "required": [
                            "channel",
                            "service",
                            "area",
                            "timeAsked"
                          ],
                          "additionalProperties": false
                        },
                        "suggestions": {
                          "type": "array",
                          "items": {
                            "oneOf": [
                              {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "type": "string",
                                    "pattern": "^(open|quiet):(MON|TUE|WED|THU|FRI|SAT|SUN):([01]\\d|2[0-3]):[0-5]\\d-([01]\\d|2[0-3]):[0-5]\\d$"
                                  },
                                  "day": {
                                    "type": "string",
                                    "enum": [
                                      "MON",
                                      "TUE",
                                      "WED",
                                      "THU",
                                      "FRI",
                                      "SAT",
                                      "SUN"
                                    ]
                                  },
                                  "start": {
                                    "type": "string",
                                    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                    "description": "Local wall clock, HH:MM, in window.zone"
                                  },
                                  "end": {
                                    "type": "string",
                                    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                    "description": "Exclusive end, HH:MM local"
                                  },
                                  "booked": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "kind": {
                                    "type": "string",
                                    "enum": ["open"]
                                  },
                                  "unfilled": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "prefill": {
                                    "type": "object",
                                    "properties": {
                                      "weeklyTimeRanges": {
                                        "type": "array",
                                        "items": {
                                          "type": "object",
                                          "properties": {
                                            "dayOfWeek": {
                                              "type": "string",
                                              "enum": [
                                                "MO",
                                                "TU",
                                                "WE",
                                                "TH",
                                                "FR",
                                                "SA",
                                                "SU"
                                              ],
                                              "description": "The weekday this range falls on, in the row’s zone.",
                                              "example": "MO"
                                            },
                                            "startTime": {
                                              "type": "string",
                                              "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                              "description": "Wall-clock start, HH:MM in the row’s zone.",
                                              "example": "09:00"
                                            },
                                            "endTime": {
                                              "type": "string",
                                              "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                              "description": "Wall-clock end, HH:MM in the row’s zone; must differ from startTime.",
                                              "example": "17:00"
                                            },
                                            "crossesMidnight": {
                                              "type": "boolean",
                                              "description": "True exactly when endTime is earlier than startTime (the range ends next day).",
                                              "example": false
                                            },
                                            "sortOrder": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "description": "Display order among the ranges of one day, from 0.",
                                              "example": 0
                                            }
                                          },
                                          "required": [
                                            "dayOfWeek",
                                            "startTime",
                                            "endTime",
                                            "crossesMidnight",
                                            "sortOrder"
                                          ]
                                        },
                                        "minItems": 1
                                      }
                                    },
                                    "required": ["weeklyTimeRanges"],
                                    "additionalProperties": false
                                  }
                                },
                                "required": [
                                  "key",
                                  "day",
                                  "start",
                                  "end",
                                  "booked",
                                  "kind",
                                  "unfilled",
                                  "prefill"
                                ],
                                "additionalProperties": false
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "key": {
                                    "type": "string",
                                    "pattern": "^(open|quiet):(MON|TUE|WED|THU|FRI|SAT|SUN):([01]\\d|2[0-3]):[0-5]\\d-([01]\\d|2[0-3]):[0-5]\\d$"
                                  },
                                  "day": {
                                    "type": "string",
                                    "enum": [
                                      "MON",
                                      "TUE",
                                      "WED",
                                      "THU",
                                      "FRI",
                                      "SAT",
                                      "SUN"
                                    ]
                                  },
                                  "start": {
                                    "type": "string",
                                    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                    "description": "Local wall clock, HH:MM, in window.zone"
                                  },
                                  "end": {
                                    "type": "string",
                                    "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
                                    "description": "Exclusive end, HH:MM local"
                                  },
                                  "booked": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "kind": {
                                    "type": "string",
                                    "enum": ["quiet"]
                                  },
                                  "scheduleId": {
                                    "type": "string",
                                    "minLength": 1
                                  }
                                },
                                "required": [
                                  "key",
                                  "day",
                                  "start",
                                  "end",
                                  "booked",
                                  "kind",
                                  "scheduleId"
                                ],
                                "additionalProperties": false
                              }
                            ]
                          }
                        },
                        "asOf": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "complete": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "state",
                        "window",
                        "previous",
                        "tiles",
                        "seenReporting",
                        "missed",
                        "breakdowns",
                        "suggestions",
                        "asOf",
                        "complete"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD); or INSIGHTS_DISABLED (the project turned the feature off)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me": {
      "get": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "The signed-in supplier’s own profile",
        "description": "The supplier record the user token resolves to in this project, as the MarketBox dashboard shows it under My Profile, built by the same code. It is the supplier’s own record, resolved from the user token: phone, email, address, `active`, time zone, service and skill ids, languages and locales. `GET /suppliers/{supplierId}` is an API-key route that also returns contact fields, so do not proxy it to browsers unfiltered. `avatarUrl` is the display-size photo, or null when none is set. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "The supplier",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "supplierId": {
                          "type": "string"
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "firstName": {
                          "type": "string"
                        },
                        "lastName": {
                          "type": "string"
                        },
                        "fullName": {
                          "type": "string"
                        },
                        "email": {
                          "type": "string"
                        },
                        "phone": {
                          "type": "string"
                        },
                        "addressoneline": {
                          "type": "string"
                        },
                        "street": {
                          "type": "string"
                        },
                        "city": {
                          "type": "string"
                        },
                        "state": {
                          "type": "string"
                        },
                        "country": {
                          "type": "string"
                        },
                        "postalcode": {
                          "type": "string"
                        },
                        "longitude": {
                          "type": "number"
                        },
                        "latitude": {
                          "type": "number"
                        },
                        "timezone": {
                          "type": "string"
                        },
                        "bio": {
                          "type": "string"
                        },
                        "maxTravelTime": {
                          "type": "number"
                        },
                        "externalId": {
                          "type": "string"
                        },
                        "externalData": {
                          "type": "object",
                          "additionalProperties": {
                            "nullable": true
                          }
                        },
                        "languages": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "locales": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "defaultLocale": {
                          "type": "string"
                        },
                        "userId": {
                          "type": "string"
                        },
                        "invitationStatus": {
                          "type": "string",
                          "enum": ["NONE", "INVITED", "LINKED"]
                        },
                        "avatar": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "variantId": {
                              "type": "string",
                              "minLength": 1
                            },
                            "updatedAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          },
                          "required": ["variantId", "updatedAt"]
                        },
                        "avatarUrl": {
                          "type": "string",
                          "nullable": true,
                          "format": "uri"
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "updatedAt": {
                          "type": "string"
                        },
                        "serviceIds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "skillIds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "supplierId",
                        "projectId",
                        "firstName",
                        "lastName",
                        "fullName",
                        "email",
                        "languages",
                        "locales",
                        "active",
                        "deleted",
                        "createdAt",
                        "updatedAt",
                        "serviceIds",
                        "skillIds"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "patch": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Update the signed-in supplier’s own profile",
        "description": "Changes the supplier record the user token resolves to, as the MarketBox dashboard does when a supplier edits My Profile, built by the same code. Only the fields in the body schema can be changed; any field left out is unchanged. `serviceIds` and `skillIds` replace the whole set when sent. A body naming a field only staff may change — `active`, `email`, `externalId`, `externalData`, `maxTravelTime` or `defaultLocale` — is refused whole with 403 `FIELD_NOT_SELF_EDITABLE`, whatever its value. Returns the updated profile, in the shape `GET /suppliers/me` answers. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "The fields to change",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "firstName": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The supplier’s first name. Omit to leave it unchanged.",
                    "example": "Ada"
                  },
                  "lastName": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The supplier’s last name. Omit to leave it unchanged.",
                    "example": "Lovelace"
                  },
                  "phone": {
                    "type": "string",
                    "nullable": true,
                    "description": "Phone number, stored in E.164 form. Omit to leave it unchanged; pass null or an empty string to clear it.",
                    "example": "+14165550134"
                  },
                  "addressoneline": {
                    "type": "string",
                    "description": "The full address on one line. Omit to leave it unchanged.",
                    "example": "120 Front St W, Toronto, ON M5J 2M2"
                  },
                  "street": {
                    "type": "string",
                    "description": "Street address. Omit to leave it unchanged.",
                    "example": "120 Front St W"
                  },
                  "city": {
                    "type": "string",
                    "description": "City. Omit to leave it unchanged.",
                    "example": "Toronto"
                  },
                  "state": {
                    "type": "string",
                    "description": "State or province, e.g. an ISO 3166-2 subdivision. Omit to leave it unchanged.",
                    "example": "CA-ON"
                  },
                  "country": {
                    "type": "string",
                    "description": "Country, e.g. an ISO 3166-1 alpha-2 code. Omit to leave it unchanged.",
                    "example": "CA"
                  },
                  "postalcode": {
                    "type": "string",
                    "description": "Postal or ZIP code. Omit to leave it unchanged.",
                    "example": "M5J 2M2"
                  },
                  "longitude": {
                    "type": "number",
                    "description": "Longitude of the supplier’s address. Omit to leave it unchanged.",
                    "example": -79.3832
                  },
                  "latitude": {
                    "type": "number",
                    "description": "Latitude of the supplier’s address. Omit to leave it unchanged.",
                    "example": 43.6532
                  },
                  "timezone": {
                    "type": "string",
                    "description": "IANA time zone the supplier works in; their daily agenda email fires at 07:00 in it, and changing it moves that schedule. Omit to leave it unchanged.",
                    "example": "America/Toronto"
                  },
                  "bio": {
                    "type": "string",
                    "nullable": true,
                    "description": "A short biography. Omit to leave it unchanged; pass null to clear it.",
                    "example": "Certified swim instructor with ten years of experience."
                  },
                  "serviceIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The complete set of service ids the supplier offers: it replaces the current set. Omit to leave the services unchanged.",
                    "example": ["srv_01k2example"]
                  },
                  "skillIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The complete set of skill ids the supplier holds: it replaces the current set. Omit to leave the skills unchanged.",
                    "example": ["skl_01k2example"]
                  },
                  "languages": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "en",
                        "fr",
                        "es",
                        "de",
                        "it",
                        "pt",
                        "nl",
                        "zh",
                        "ja",
                        "ko",
                        "ar",
                        "hi",
                        "ru",
                        "pl",
                        "tr",
                        "vi"
                      ]
                    },
                    "description": "The languages the supplier speaks (ISO 639-1 codes): replaces the current list. Omit to leave it unchanged.",
                    "example": ["en", "fr"]
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated supplier",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "supplierId": {
                          "type": "string"
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "firstName": {
                          "type": "string"
                        },
                        "lastName": {
                          "type": "string"
                        },
                        "fullName": {
                          "type": "string"
                        },
                        "email": {
                          "type": "string"
                        },
                        "phone": {
                          "type": "string"
                        },
                        "addressoneline": {
                          "type": "string"
                        },
                        "street": {
                          "type": "string"
                        },
                        "city": {
                          "type": "string"
                        },
                        "state": {
                          "type": "string"
                        },
                        "country": {
                          "type": "string"
                        },
                        "postalcode": {
                          "type": "string"
                        },
                        "longitude": {
                          "type": "number"
                        },
                        "latitude": {
                          "type": "number"
                        },
                        "timezone": {
                          "type": "string"
                        },
                        "bio": {
                          "type": "string"
                        },
                        "maxTravelTime": {
                          "type": "number"
                        },
                        "externalId": {
                          "type": "string"
                        },
                        "externalData": {
                          "type": "object",
                          "additionalProperties": {
                            "nullable": true
                          }
                        },
                        "languages": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "locales": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "defaultLocale": {
                          "type": "string"
                        },
                        "userId": {
                          "type": "string"
                        },
                        "invitationStatus": {
                          "type": "string",
                          "enum": ["NONE", "INVITED", "LINKED"]
                        },
                        "avatar": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "variantId": {
                              "type": "string",
                              "minLength": 1
                            },
                            "updatedAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          },
                          "required": ["variantId", "updatedAt"]
                        },
                        "avatarUrl": {
                          "type": "string",
                          "nullable": true,
                          "format": "uri"
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "updatedAt": {
                          "type": "string"
                        },
                        "serviceIds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "skillIds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "supplierId",
                        "projectId",
                        "firstName",
                        "lastName",
                        "fullName",
                        "email",
                        "languages",
                        "locales",
                        "active",
                        "deleted",
                        "createdAt",
                        "updatedAt",
                        "serviceIds",
                        "skillIds"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "An invalid value or a field the body schema does not list (VALIDATION_ERROR), or a body that is not valid JSON (HTTP_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD); or the body names a field only staff may change (FIELD_NOT_SELF_EDITABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "Another supplier in the project already uses this email (CONFLICT)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/avatar/upload-url": {
      "post": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Get a presigned URL to upload the signed-in supplier’s photo",
        "description": "Step 1 of 2 of changing the photo of the supplier the user token resolves to. The image never passes through this API: you get back a short-lived URL and PUT the bytes straight to storage, then call PUT /suppliers/me/avatar with the `variantId` returned here.\n\nSend exactly the `headers` map you get back and nothing else: the routing metadata is signed into the URL, so extra `x-amz-meta-*` headers make the upload fail with a 403. The URL expires in 5 minutes. `contentType` must be image/jpeg, image/png or image/webp, and `contentLength` the real byte length, at most 5 MB. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Upload metadata",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "contentType": {
                    "type": "string",
                    "enum": ["image/jpeg", "image/png", "image/webp"],
                    "description": "The image’s MIME type: image/jpeg, image/png or image/webp.",
                    "example": "image/png"
                  },
                  "contentLength": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "maximum": 5242880,
                    "description": "The image’s exact size in bytes: above zero and at most 5 MB (5242880).",
                    "example": 184320
                  }
                },
                "required": ["contentType", "contentLength"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Presigned upload",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "uploadId": {
                          "type": "string"
                        },
                        "variantId": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string",
                          "format": "uri"
                        },
                        "method": {
                          "type": "string",
                          "enum": ["PUT"]
                        },
                        "headers": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "expiresIn": {
                          "type": "integer",
                          "minimum": 0,
                          "exclusiveMinimum": true
                        }
                      },
                      "required": [
                        "uploadId",
                        "variantId",
                        "url",
                        "method",
                        "headers",
                        "expiresIn"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "An unsupported content type or a size out of range (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/avatar": {
      "put": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Attach the uploaded photo to the signed-in supplier",
        "description": "Step 2 of 2: attaches the uploaded image to the supplier the user token resolves to and returns their profile, in the shape `GET /suppliers/me` answers, with the new `avatarUrl`. Pass the `variantId` from the upload-url call.\n\nResizing happens after your upload lands, so calling this straight away often returns 400 \"Avatar variant not ready yet. Retry shortly.\" That is a retry signal: wait a second or two and call again. Confirming a different `variantId` replaces the current photo and deletes the old images for good; re-confirming the same one is harmless. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "The uploaded image",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "uploadId": {
                    "type": "string",
                    "description": "The `uploadId` the upload-url call returned.",
                    "example": "upl_01k2example"
                  },
                  "variantId": {
                    "type": "string",
                    "description": "The `variantId` the upload-url call returned: the image to attach.",
                    "example": "var_01k2example"
                  }
                },
                "required": ["uploadId", "variantId"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The supplier with the new photo",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "supplierId": {
                          "type": "string"
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "firstName": {
                          "type": "string"
                        },
                        "lastName": {
                          "type": "string"
                        },
                        "fullName": {
                          "type": "string"
                        },
                        "email": {
                          "type": "string"
                        },
                        "phone": {
                          "type": "string"
                        },
                        "addressoneline": {
                          "type": "string"
                        },
                        "street": {
                          "type": "string"
                        },
                        "city": {
                          "type": "string"
                        },
                        "state": {
                          "type": "string"
                        },
                        "country": {
                          "type": "string"
                        },
                        "postalcode": {
                          "type": "string"
                        },
                        "longitude": {
                          "type": "number"
                        },
                        "latitude": {
                          "type": "number"
                        },
                        "timezone": {
                          "type": "string"
                        },
                        "bio": {
                          "type": "string"
                        },
                        "maxTravelTime": {
                          "type": "number"
                        },
                        "externalId": {
                          "type": "string"
                        },
                        "externalData": {
                          "type": "object",
                          "additionalProperties": {
                            "nullable": true
                          }
                        },
                        "languages": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "locales": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "defaultLocale": {
                          "type": "string"
                        },
                        "userId": {
                          "type": "string"
                        },
                        "invitationStatus": {
                          "type": "string",
                          "enum": ["NONE", "INVITED", "LINKED"]
                        },
                        "avatar": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "variantId": {
                              "type": "string",
                              "minLength": 1
                            },
                            "updatedAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          },
                          "required": ["variantId", "updatedAt"]
                        },
                        "avatarUrl": {
                          "type": "string",
                          "nullable": true,
                          "format": "uri"
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "updatedAt": {
                          "type": "string"
                        },
                        "serviceIds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "skillIds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "supplierId",
                        "projectId",
                        "firstName",
                        "lastName",
                        "fullName",
                        "email",
                        "languages",
                        "locales",
                        "active",
                        "deleted",
                        "createdAt",
                        "updatedAt",
                        "serviceIds",
                        "skillIds"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "The image is not ready yet, retry shortly (BAD_REQUEST); or an invalid body (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "The photo changed while this request was being saved, by another confirm or remove (CONFLICT): read the supplier again and retry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "delete": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Remove the signed-in supplier’s photo",
        "description": "Clears the photo of the supplier the user token resolves to and deletes the stored images for good. Returns 204 whether or not they had one. To swap a photo, confirm the new one instead: that replaces the old image in one step. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Photo removed (or there was none)"
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "The photo changed while this request was being saved, by another confirm or remove (CONFLICT): read the supplier again and retry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/travel-zones": {
      "post": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Create a travel zone for the signed-in supplier",
        "description": "An area the supplier travels to, as the dashboard creates one: a CIRCULAR zone (a radius around a centre) or a DRAWN one (GeoJSON polygons). The zone is always the signed-in supplier’s. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Travel zone data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The zone’s display name, as the supplier and staff see it.",
                    "example": "Downtown Toronto"
                  },
                  "defaultLanguage": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The language `name` is written in (BCP 47).",
                    "example": "en"
                  },
                  "nameI18n": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string",
                      "minLength": 1
                    },
                    "description": "The name in other languages, keyed by BCP 47 language tag.",
                    "example": {
                      "fr": "Centre-ville de Toronto"
                    }
                  },
                  "addressOneLine": {
                    "type": "string",
                    "nullable": true,
                    "description": "The address of the zone’s centre, on one line.",
                    "example": "100 Queen St W, Toronto, ON M5H 2N2"
                  },
                  "street": {
                    "type": "string",
                    "nullable": true,
                    "description": "Street address of the zone’s centre.",
                    "example": "100 Queen St W"
                  },
                  "city": {
                    "type": "string",
                    "nullable": true,
                    "description": "City of the zone’s centre.",
                    "example": "Toronto"
                  },
                  "state": {
                    "type": "string",
                    "nullable": true,
                    "description": "State or province of the zone’s centre.",
                    "example": "ON"
                  },
                  "country": {
                    "type": "string",
                    "nullable": true,
                    "description": "Country of the zone’s centre.",
                    "example": "CA"
                  },
                  "postalCode": {
                    "type": "string",
                    "nullable": true,
                    "description": "Postal or ZIP code of the zone’s centre.",
                    "example": "M5H 2N2"
                  },
                  "longitude": {
                    "type": "number",
                    "description": "Longitude of the zone’s centre (for a CIRCULAR zone, the centre of the circle).",
                    "example": -79.3832
                  },
                  "latitude": {
                    "type": "number",
                    "description": "Latitude of the zone’s centre (for a CIRCULAR zone, the centre of the circle).",
                    "example": 43.6532
                  },
                  "timezone": {
                    "type": "string",
                    "nullable": true,
                    "minLength": 1,
                    "description": "IANA time zone of the zone’s area. Omit or null to leave it unset.",
                    "example": "America/Toronto"
                  },
                  "travelZoneType": {
                    "type": "string",
                    "enum": ["CIRCULAR", "DRAWN"],
                    "description": "CIRCULAR = a radius around the centre (travelDistance and travelDistanceUnit); DRAWN = the polygons in travelRegions.",
                    "example": "CIRCULAR"
                  },
                  "travelDistance": {
                    "type": "number",
                    "nullable": true,
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "description": "The radius of a CIRCULAR zone, in travelDistanceUnit. Required for CIRCULAR, null for DRAWN.",
                    "example": 10
                  },
                  "travelDistanceUnit": {
                    "type": "string",
                    "nullable": true,
                    "enum": ["KM", "MILES", null],
                    "description": "The unit of travelDistance. Required for CIRCULAR, null for DRAWN.",
                    "example": "KM"
                  },
                  "travelRegions": {
                    "type": "object",
                    "nullable": true,
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": ["Polygon", "MultiPolygon"],
                        "description": "The GeoJSON geometry type.",
                        "example": "Polygon"
                      },
                      "coordinates": {
                        "nullable": true,
                        "description": "The GeoJSON coordinates: rings of [longitude, latitude] positions, each ring closed (its last position equals its first).",
                        "example": [
                          [
                            [-79.42, 43.63],
                            [-79.33, 43.63],
                            [-79.33, 43.69],
                            [-79.42, 43.69],
                            [-79.42, 43.63]
                          ]
                        ]
                      }
                    },
                    "required": ["type"],
                    "description": "The area of a DRAWN zone, a GeoJSON Polygon or MultiPolygon. Required for DRAWN, null for CIRCULAR.",
                    "example": {
                      "type": "Polygon",
                      "coordinates": [
                        [
                          [-79.42, 43.63],
                          [-79.33, 43.63],
                          [-79.33, 43.69],
                          [-79.42, 43.69],
                          [-79.42, 43.63]
                        ]
                      ]
                    }
                  },
                  "active": {
                    "type": "boolean",
                    "default": true,
                    "description": "Active zones can be used by schedules; an inactive zone is kept but offers nothing. Defaults to true.",
                    "example": true
                  }
                },
                "required": ["name", "longitude", "latitude", "travelZoneType"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Travel zone created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "supplierTravelZoneId": {
                          "type": "string",
                          "description": "The travel zone’s id.",
                          "example": "stz_01kv60qgnef2kt3pvqgwmkbzfr"
                        },
                        "projectId": {
                          "type": "string",
                          "description": "The project the zone belongs to.",
                          "example": "prj_01kv60qge5eh59ap0gw0pqrrys"
                        },
                        "supplierId": {
                          "type": "string",
                          "description": "The supplier whose zone this is — always the supplier it was created for.",
                          "example": "sup_01kv60qgnef2kt3pvqgwmkbzfr"
                        },
                        "name": {
                          "type": "string",
                          "description": "The zone’s display name, as the supplier and staff see it.",
                          "example": "Downtown Toronto"
                        },
                        "nameNormalized": {
                          "type": "string",
                          "description": "The name trimmed, lower-cased and with runs of spaces collapsed; what `namePrefix` matches.",
                          "example": "downtown toronto"
                        },
                        "defaultLanguage": {
                          "type": "string",
                          "description": "The language `name` is written in (BCP 47).",
                          "example": "en"
                        },
                        "nameI18n": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          },
                          "description": "The name in other languages, keyed by BCP 47 language tag.",
                          "example": {
                            "fr": "Centre-ville de Toronto"
                          }
                        },
                        "addressOneLine": {
                          "type": "string",
                          "nullable": true,
                          "description": "The address of the zone’s centre, on one line.",
                          "example": "100 Queen St W, Toronto, ON M5H 2N2"
                        },
                        "street": {
                          "type": "string",
                          "nullable": true,
                          "description": "Street address of the zone’s centre.",
                          "example": "100 Queen St W"
                        },
                        "city": {
                          "type": "string",
                          "nullable": true,
                          "description": "City of the zone’s centre.",
                          "example": "Toronto"
                        },
                        "state": {
                          "type": "string",
                          "nullable": true,
                          "description": "State or province of the zone’s centre.",
                          "example": "ON"
                        },
                        "country": {
                          "type": "string",
                          "nullable": true,
                          "description": "Country of the zone’s centre.",
                          "example": "CA"
                        },
                        "postalCode": {
                          "type": "string",
                          "nullable": true,
                          "description": "Postal or ZIP code of the zone’s centre.",
                          "example": "M5H 2N2"
                        },
                        "longitude": {
                          "type": "number",
                          "description": "Longitude of the zone’s centre (for a CIRCULAR zone, the centre of the circle).",
                          "example": -79.3832
                        },
                        "latitude": {
                          "type": "number",
                          "description": "Latitude of the zone’s centre (for a CIRCULAR zone, the centre of the circle).",
                          "example": 43.6532
                        },
                        "timezone": {
                          "type": "string",
                          "nullable": true,
                          "description": "IANA time zone of the zone’s area.",
                          "example": "America/Toronto"
                        },
                        "travelZoneType": {
                          "type": "string",
                          "enum": ["CIRCULAR", "DRAWN"],
                          "description": "CIRCULAR = a radius around the centre (travelDistance and travelDistanceUnit); DRAWN = the polygons in travelRegions.",
                          "example": "CIRCULAR"
                        },
                        "travelDistance": {
                          "type": "number",
                          "nullable": true,
                          "description": "The radius of a CIRCULAR zone, in travelDistanceUnit. Required for CIRCULAR, null for DRAWN.",
                          "example": 10
                        },
                        "travelDistanceUnit": {
                          "type": "string",
                          "nullable": true,
                          "enum": ["KM", "MILES", null],
                          "description": "The unit of travelDistance. Required for CIRCULAR, null for DRAWN.",
                          "example": "KM"
                        },
                        "travelRegions": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "type": {
                              "type": "string",
                              "enum": ["Polygon", "MultiPolygon"],
                              "description": "The GeoJSON geometry type.",
                              "example": "Polygon"
                            },
                            "coordinates": {
                              "nullable": true,
                              "description": "The GeoJSON coordinates: rings of [longitude, latitude] positions, each ring closed (its last position equals its first).",
                              "example": [
                                [
                                  [-79.42, 43.63],
                                  [-79.33, 43.63],
                                  [-79.33, 43.69],
                                  [-79.42, 43.69],
                                  [-79.42, 43.63]
                                ]
                              ]
                            }
                          },
                          "required": ["type"],
                          "description": "The area of a DRAWN zone, a GeoJSON Polygon or MultiPolygon. Required for DRAWN, null for CIRCULAR.",
                          "example": null
                        },
                        "active": {
                          "type": "boolean",
                          "description": "Active zones can be used by schedules; an inactive zone is kept but offers nothing.",
                          "example": true
                        },
                        "deleted": {
                          "type": "boolean",
                          "description": "True once the zone is soft-deleted.",
                          "example": false
                        },
                        "version": {
                          "type": "integer",
                          "minimum": 0,
                          "exclusiveMinimum": true,
                          "description": "The row’s current version, for optimistic concurrency; a stale value is a 409.",
                          "example": 1
                        },
                        "createdAt": {
                          "type": "string",
                          "description": "When the zone was created (ISO 8601, UTC).",
                          "example": "2026-10-01T14:00:00.000Z"
                        },
                        "updatedAt": {
                          "type": "string",
                          "description": "When the zone was last changed (ISO 8601, UTC).",
                          "example": "2026-10-01T14:00:00.000Z"
                        }
                      },
                      "required": [
                        "supplierTravelZoneId",
                        "projectId",
                        "supplierId",
                        "name",
                        "nameNormalized",
                        "longitude",
                        "latitude",
                        "travelZoneType",
                        "active",
                        "deleted",
                        "version",
                        "createdAt",
                        "updatedAt"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "get": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "List the signed-in supplier’s travel zones",
        "description": "The supplier’s travel zones as the dashboard lists them: active ones by default, inactive and soft-deleted ones on request, optionally by name prefix. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "description": "Also return inactive travel zones when `true`.",
              "example": "false"
            },
            "required": false,
            "description": "Also return inactive travel zones when `true`.",
            "name": "includeInactive",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Also return soft-deleted travel zones when `true`.",
              "example": "false"
            },
            "required": false,
            "description": "Also return soft-deleted travel zones when `true`.",
            "name": "includeDeleted",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Only the zones whose name starts with this text, ignoring case.",
              "example": "down"
            },
            "required": false,
            "description": "Only the zones whose name starts with this text, ignoring case.",
            "name": "namePrefix",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Travel zones list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "supplierTravelZoneId": {
                            "type": "string",
                            "description": "The travel zone’s id.",
                            "example": "stz_01kv60qgnef2kt3pvqgwmkbzfr"
                          },
                          "projectId": {
                            "type": "string",
                            "description": "The project the zone belongs to.",
                            "example": "prj_01kv60qge5eh59ap0gw0pqrrys"
                          },
                          "supplierId": {
                            "type": "string",
                            "description": "The supplier whose zone this is — always the supplier it was created for.",
                            "example": "sup_01kv60qgnef2kt3pvqgwmkbzfr"
                          },
                          "name": {
                            "type": "string",
                            "description": "The zone’s display name, as the supplier and staff see it.",
                            "example": "Downtown Toronto"
                          },
                          "nameNormalized": {
                            "type": "string",
                            "description": "The name trimmed, lower-cased and with runs of spaces collapsed; what `namePrefix` matches.",
                            "example": "downtown toronto"
                          },
                          "defaultLanguage": {
                            "type": "string",
                            "description": "The language `name` is written in (BCP 47).",
                            "example": "en"
                          },
                          "nameI18n": {
                            "type": "object",
                            "additionalProperties": {
                              "type": "string"
                            },
                            "description": "The name in other languages, keyed by BCP 47 language tag.",
                            "example": {
                              "fr": "Centre-ville de Toronto"
                            }
                          },
                          "addressOneLine": {
                            "type": "string",
                            "nullable": true,
                            "description": "The address of the zone’s centre, on one line.",
                            "example": "100 Queen St W, Toronto, ON M5H 2N2"
                          },
                          "street": {
                            "type": "string",
                            "nullable": true,
                            "description": "Street address of the zone’s centre.",
                            "example": "100 Queen St W"
                          },
                          "city": {
                            "type": "string",
                            "nullable": true,
                            "description": "City of the zone’s centre.",
                            "example": "Toronto"
                          },
                          "state": {
                            "type": "string",
                            "nullable": true,
                            "description": "State or province of the zone’s centre.",
                            "example": "ON"
                          },
                          "country": {
                            "type": "string",
                            "nullable": true,
                            "description": "Country of the zone’s centre.",
                            "example": "CA"
                          },
                          "postalCode": {
                            "type": "string",
                            "nullable": true,
                            "description": "Postal or ZIP code of the zone’s centre.",
                            "example": "M5H 2N2"
                          },
                          "longitude": {
                            "type": "number",
                            "description": "Longitude of the zone’s centre (for a CIRCULAR zone, the centre of the circle).",
                            "example": -79.3832
                          },
                          "latitude": {
                            "type": "number",
                            "description": "Latitude of the zone’s centre (for a CIRCULAR zone, the centre of the circle).",
                            "example": 43.6532
                          },
                          "timezone": {
                            "type": "string",
                            "nullable": true,
                            "description": "IANA time zone of the zone’s area.",
                            "example": "America/Toronto"
                          },
                          "travelZoneType": {
                            "type": "string",
                            "enum": ["CIRCULAR", "DRAWN"],
                            "description": "CIRCULAR = a radius around the centre (travelDistance and travelDistanceUnit); DRAWN = the polygons in travelRegions.",
                            "example": "CIRCULAR"
                          },
                          "travelDistance": {
                            "type": "number",
                            "nullable": true,
                            "description": "The radius of a CIRCULAR zone, in travelDistanceUnit. Required for CIRCULAR, null for DRAWN.",
                            "example": 10
                          },
                          "travelDistanceUnit": {
                            "type": "string",
                            "nullable": true,
                            "enum": ["KM", "MILES", null],
                            "description": "The unit of travelDistance. Required for CIRCULAR, null for DRAWN.",
                            "example": "KM"
                          },
                          "travelRegions": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "type": {
                                "type": "string",
                                "enum": ["Polygon", "MultiPolygon"],
                                "description": "The GeoJSON geometry type.",
                                "example": "Polygon"
                              },
                              "coordinates": {
                                "nullable": true,
                                "description": "The GeoJSON coordinates: rings of [longitude, latitude] positions, each ring closed (its last position equals its first).",
                                "example": [
                                  [
                                    [-79.42, 43.63],
                                    [-79.33, 43.63],
                                    [-79.33, 43.69],
                                    [-79.42, 43.69],
                                    [-79.42, 43.63]
                                  ]
                                ]
                              }
                            },
                            "required": ["type"],
                            "description": "The area of a DRAWN zone, a GeoJSON Polygon or MultiPolygon. Required for DRAWN, null for CIRCULAR.",
                            "example": null
                          },
                          "active": {
                            "type": "boolean",
                            "description": "Active zones can be used by schedules; an inactive zone is kept but offers nothing.",
                            "example": true
                          },
                          "deleted": {
                            "type": "boolean",
                            "description": "True once the zone is soft-deleted.",
                            "example": false
                          },
                          "version": {
                            "type": "integer",
                            "minimum": 0,
                            "exclusiveMinimum": true,
                            "description": "The row’s current version, for optimistic concurrency; a stale value is a 409.",
                            "example": 1
                          },
                          "createdAt": {
                            "type": "string",
                            "description": "When the zone was created (ISO 8601, UTC).",
                            "example": "2026-10-01T14:00:00.000Z"
                          },
                          "updatedAt": {
                            "type": "string",
                            "description": "When the zone was last changed (ISO 8601, UTC).",
                            "example": "2026-10-01T14:00:00.000Z"
                          }
                        },
                        "required": [
                          "supplierTravelZoneId",
                          "projectId",
                          "supplierId",
                          "name",
                          "nameNormalized",
                          "longitude",
                          "latitude",
                          "travelZoneType",
                          "active",
                          "deleted",
                          "version",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/travel-zones/{travelZoneId}": {
      "get": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Get one of the signed-in supplier’s travel zones",
        "description": "One travel zone by id, if it belongs to the supplier the user token resolves to; another supplier’s zone is a 404 like a missing one. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The travel zone — an area the supplier travels to, a circle or a drawn polygon.",
              "example": "stz_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The travel zone — an area the supplier travels to, a circle or a drawn polygon.",
            "name": "travelZoneId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Travel zone",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "supplierTravelZoneId": {
                          "type": "string",
                          "description": "The travel zone’s id.",
                          "example": "stz_01kv60qgnef2kt3pvqgwmkbzfr"
                        },
                        "projectId": {
                          "type": "string",
                          "description": "The project the zone belongs to.",
                          "example": "prj_01kv60qge5eh59ap0gw0pqrrys"
                        },
                        "supplierId": {
                          "type": "string",
                          "description": "The supplier whose zone this is — always the supplier it was created for.",
                          "example": "sup_01kv60qgnef2kt3pvqgwmkbzfr"
                        },
                        "name": {
                          "type": "string",
                          "description": "The zone’s display name, as the supplier and staff see it.",
                          "example": "Downtown Toronto"
                        },
                        "nameNormalized": {
                          "type": "string",
                          "description": "The name trimmed, lower-cased and with runs of spaces collapsed; what `namePrefix` matches.",
                          "example": "downtown toronto"
                        },
                        "defaultLanguage": {
                          "type": "string",
                          "description": "The language `name` is written in (BCP 47).",
                          "example": "en"
                        },
                        "nameI18n": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          },
                          "description": "The name in other languages, keyed by BCP 47 language tag.",
                          "example": {
                            "fr": "Centre-ville de Toronto"
                          }
                        },
                        "addressOneLine": {
                          "type": "string",
                          "nullable": true,
                          "description": "The address of the zone’s centre, on one line.",
                          "example": "100 Queen St W, Toronto, ON M5H 2N2"
                        },
                        "street": {
                          "type": "string",
                          "nullable": true,
                          "description": "Street address of the zone’s centre.",
                          "example": "100 Queen St W"
                        },
                        "city": {
                          "type": "string",
                          "nullable": true,
                          "description": "City of the zone’s centre.",
                          "example": "Toronto"
                        },
                        "state": {
                          "type": "string",
                          "nullable": true,
                          "description": "State or province of the zone’s centre.",
                          "example": "ON"
                        },
                        "country": {
                          "type": "string",
                          "nullable": true,
                          "description": "Country of the zone’s centre.",
                          "example": "CA"
                        },
                        "postalCode": {
                          "type": "string",
                          "nullable": true,
                          "description": "Postal or ZIP code of the zone’s centre.",
                          "example": "M5H 2N2"
                        },
                        "longitude": {
                          "type": "number",
                          "description": "Longitude of the zone’s centre (for a CIRCULAR zone, the centre of the circle).",
                          "example": -79.3832
                        },
                        "latitude": {
                          "type": "number",
                          "description": "Latitude of the zone’s centre (for a CIRCULAR zone, the centre of the circle).",
                          "example": 43.6532
                        },
                        "timezone": {
                          "type": "string",
                          "nullable": true,
                          "description": "IANA time zone of the zone’s area.",
                          "example": "America/Toronto"
                        },
                        "travelZoneType": {
                          "type": "string",
                          "enum": ["CIRCULAR", "DRAWN"],
                          "description": "CIRCULAR = a radius around the centre (travelDistance and travelDistanceUnit); DRAWN = the polygons in travelRegions.",
                          "example": "CIRCULAR"
                        },
                        "travelDistance": {
                          "type": "number",
                          "nullable": true,
                          "description": "The radius of a CIRCULAR zone, in travelDistanceUnit. Required for CIRCULAR, null for DRAWN.",
                          "example": 10
                        },
                        "travelDistanceUnit": {
                          "type": "string",
                          "nullable": true,
                          "enum": ["KM", "MILES", null],
                          "description": "The unit of travelDistance. Required for CIRCULAR, null for DRAWN.",
                          "example": "KM"
                        },
                        "travelRegions": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "type": {
                              "type": "string",
                              "enum": ["Polygon", "MultiPolygon"],
                              "description": "The GeoJSON geometry type.",
                              "example": "Polygon"
                            },
                            "coordinates": {
                              "nullable": true,
                              "description": "The GeoJSON coordinates: rings of [longitude, latitude] positions, each ring closed (its last position equals its first).",
                              "example": [
                                [
                                  [-79.42, 43.63],
                                  [-79.33, 43.63],
                                  [-79.33, 43.69],
                                  [-79.42, 43.69],
                                  [-79.42, 43.63]
                                ]
                              ]
                            }
                          },
                          "required": ["type"],
                          "description": "The area of a DRAWN zone, a GeoJSON Polygon or MultiPolygon. Required for DRAWN, null for CIRCULAR.",
                          "example": null
                        },
                        "active": {
                          "type": "boolean",
                          "description": "Active zones can be used by schedules; an inactive zone is kept but offers nothing.",
                          "example": true
                        },
                        "deleted": {
                          "type": "boolean",
                          "description": "True once the zone is soft-deleted.",
                          "example": false
                        },
                        "version": {
                          "type": "integer",
                          "minimum": 0,
                          "exclusiveMinimum": true,
                          "description": "The row’s current version, for optimistic concurrency; a stale value is a 409.",
                          "example": 1
                        },
                        "createdAt": {
                          "type": "string",
                          "description": "When the zone was created (ISO 8601, UTC).",
                          "example": "2026-10-01T14:00:00.000Z"
                        },
                        "updatedAt": {
                          "type": "string",
                          "description": "When the zone was last changed (ISO 8601, UTC).",
                          "example": "2026-10-01T14:00:00.000Z"
                        }
                      },
                      "required": [
                        "supplierTravelZoneId",
                        "projectId",
                        "supplierId",
                        "name",
                        "nameNormalized",
                        "longitude",
                        "latitude",
                        "travelZoneType",
                        "active",
                        "deleted",
                        "version",
                        "createdAt",
                        "updatedAt"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such travel zone of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "patch": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Update one of the signed-in supplier’s travel zones",
        "description": "Change any of the zone’s fields; send the row’s current `version` (optimistic concurrency — a stale one is a 409). A geometry change re-computes the coverage of every schedule that uses the zone; `coverageRecompute` reports how many and how many failed. A rename or other non-geometry edit leaves the schedules alone and the response has no `coverageRecompute`. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The travel zone — an area the supplier travels to, a circle or a drawn polygon.",
              "example": "stz_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The travel zone — an area the supplier travels to, a circle or a drawn polygon.",
            "name": "travelZoneId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Fields to update",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The zone’s display name, as the supplier and staff see it. Omit to leave it unchanged.",
                    "example": "Downtown Toronto"
                  },
                  "defaultLanguage": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The language `name` is written in (BCP 47). Omit to leave it unchanged.",
                    "example": "en"
                  },
                  "nameI18n": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string",
                      "minLength": 1
                    },
                    "description": "The name in other languages, keyed by BCP 47 language tag. Omit to leave it unchanged.",
                    "example": {
                      "fr": "Centre-ville de Toronto"
                    }
                  },
                  "addressOneLine": {
                    "type": "string",
                    "nullable": true,
                    "description": "The address of the zone’s centre, on one line. Omit to leave it unchanged; pass null to clear it.",
                    "example": "100 Queen St W, Toronto, ON M5H 2N2"
                  },
                  "street": {
                    "type": "string",
                    "nullable": true,
                    "description": "Street address of the zone’s centre. Omit to leave it unchanged; pass null to clear it.",
                    "example": "100 Queen St W"
                  },
                  "city": {
                    "type": "string",
                    "nullable": true,
                    "description": "City of the zone’s centre. Omit to leave it unchanged; pass null to clear it.",
                    "example": "Toronto"
                  },
                  "state": {
                    "type": "string",
                    "nullable": true,
                    "description": "State or province of the zone’s centre. Omit to leave it unchanged; pass null to clear it.",
                    "example": "ON"
                  },
                  "country": {
                    "type": "string",
                    "nullable": true,
                    "description": "Country of the zone’s centre. Omit to leave it unchanged; pass null to clear it.",
                    "example": "CA"
                  },
                  "postalCode": {
                    "type": "string",
                    "nullable": true,
                    "description": "Postal or ZIP code of the zone’s centre. Omit to leave it unchanged; pass null to clear it.",
                    "example": "M5H 2N2"
                  },
                  "longitude": {
                    "type": "number",
                    "description": "Longitude of the zone’s centre (for a CIRCULAR zone, the centre of the circle). Omit to leave it unchanged.",
                    "example": -79.3832
                  },
                  "latitude": {
                    "type": "number",
                    "description": "Latitude of the zone’s centre (for a CIRCULAR zone, the centre of the circle). Omit to leave it unchanged.",
                    "example": 43.6532
                  },
                  "timezone": {
                    "type": "string",
                    "nullable": true,
                    "minLength": 1,
                    "description": "IANA time zone of the zone’s area. Omit to leave it unchanged; pass null to clear it.",
                    "example": "America/Toronto"
                  },
                  "travelZoneType": {
                    "type": "string",
                    "enum": ["CIRCULAR", "DRAWN"],
                    "description": "CIRCULAR = a radius around the centre (travelDistance and travelDistanceUnit); DRAWN = the polygons in travelRegions. Omit to keep the zone’s type; switching it requires the new type’s geometry fields.",
                    "example": "CIRCULAR"
                  },
                  "travelDistance": {
                    "type": "number",
                    "nullable": true,
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "description": "The radius of a CIRCULAR zone, in travelDistanceUnit. Required for CIRCULAR, null for DRAWN. Omit to leave it unchanged.",
                    "example": 15
                  },
                  "travelDistanceUnit": {
                    "type": "string",
                    "nullable": true,
                    "enum": ["KM", "MILES", null],
                    "description": "The unit of travelDistance. Required for CIRCULAR, null for DRAWN. Omit to leave it unchanged.",
                    "example": "KM"
                  },
                  "travelRegions": {
                    "type": "object",
                    "nullable": true,
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": ["Polygon", "MultiPolygon"],
                        "description": "The GeoJSON geometry type.",
                        "example": "Polygon"
                      },
                      "coordinates": {
                        "nullable": true,
                        "description": "The GeoJSON coordinates: rings of [longitude, latitude] positions, each ring closed (its last position equals its first).",
                        "example": [
                          [
                            [-79.42, 43.63],
                            [-79.33, 43.63],
                            [-79.33, 43.69],
                            [-79.42, 43.69],
                            [-79.42, 43.63]
                          ]
                        ]
                      }
                    },
                    "required": ["type"],
                    "description": "The area of a DRAWN zone, a GeoJSON Polygon or MultiPolygon. Required for DRAWN, null for CIRCULAR. Omit to leave it unchanged.",
                    "example": {
                      "type": "Polygon",
                      "coordinates": [
                        [
                          [-79.42, 43.63],
                          [-79.33, 43.63],
                          [-79.33, 43.69],
                          [-79.42, 43.69],
                          [-79.42, 43.63]
                        ]
                      ]
                    }
                  },
                  "active": {
                    "type": "boolean",
                    "description": "Active zones can be used by schedules; an inactive zone is kept but offers nothing. Omit to leave it unchanged.",
                    "example": true
                  },
                  "version": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "description": "The row’s current version, for optimistic concurrency; a stale value is a 409. Send the version you read.",
                    "example": 1
                  }
                },
                "required": ["version"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Travel zone updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "supplierTravelZoneId": {
                          "type": "string",
                          "description": "The travel zone’s id.",
                          "example": "stz_01kv60qgnef2kt3pvqgwmkbzfr"
                        },
                        "projectId": {
                          "type": "string",
                          "description": "The project the zone belongs to.",
                          "example": "prj_01kv60qge5eh59ap0gw0pqrrys"
                        },
                        "supplierId": {
                          "type": "string",
                          "description": "The supplier whose zone this is — always the supplier it was created for.",
                          "example": "sup_01kv60qgnef2kt3pvqgwmkbzfr"
                        },
                        "name": {
                          "type": "string",
                          "description": "The zone’s display name, as the supplier and staff see it.",
                          "example": "Downtown Toronto"
                        },
                        "nameNormalized": {
                          "type": "string",
                          "description": "The name trimmed, lower-cased and with runs of spaces collapsed; what `namePrefix` matches.",
                          "example": "downtown toronto"
                        },
                        "defaultLanguage": {
                          "type": "string",
                          "description": "The language `name` is written in (BCP 47).",
                          "example": "en"
                        },
                        "nameI18n": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          },
                          "description": "The name in other languages, keyed by BCP 47 language tag.",
                          "example": {
                            "fr": "Centre-ville de Toronto"
                          }
                        },
                        "addressOneLine": {
                          "type": "string",
                          "nullable": true,
                          "description": "The address of the zone’s centre, on one line.",
                          "example": "100 Queen St W, Toronto, ON M5H 2N2"
                        },
                        "street": {
                          "type": "string",
                          "nullable": true,
                          "description": "Street address of the zone’s centre.",
                          "example": "100 Queen St W"
                        },
                        "city": {
                          "type": "string",
                          "nullable": true,
                          "description": "City of the zone’s centre.",
                          "example": "Toronto"
                        },
                        "state": {
                          "type": "string",
                          "nullable": true,
                          "description": "State or province of the zone’s centre.",
                          "example": "ON"
                        },
                        "country": {
                          "type": "string",
                          "nullable": true,
                          "description": "Country of the zone’s centre.",
                          "example": "CA"
                        },
                        "postalCode": {
                          "type": "string",
                          "nullable": true,
                          "description": "Postal or ZIP code of the zone’s centre.",
                          "example": "M5H 2N2"
                        },
                        "longitude": {
                          "type": "number",
                          "description": "Longitude of the zone’s centre (for a CIRCULAR zone, the centre of the circle).",
                          "example": -79.3832
                        },
                        "latitude": {
                          "type": "number",
                          "description": "Latitude of the zone’s centre (for a CIRCULAR zone, the centre of the circle).",
                          "example": 43.6532
                        },
                        "timezone": {
                          "type": "string",
                          "nullable": true,
                          "description": "IANA time zone of the zone’s area.",
                          "example": "America/Toronto"
                        },
                        "travelZoneType": {
                          "type": "string",
                          "enum": ["CIRCULAR", "DRAWN"],
                          "description": "CIRCULAR = a radius around the centre (travelDistance and travelDistanceUnit); DRAWN = the polygons in travelRegions.",
                          "example": "CIRCULAR"
                        },
                        "travelDistance": {
                          "type": "number",
                          "nullable": true,
                          "description": "The radius of a CIRCULAR zone, in travelDistanceUnit. Required for CIRCULAR, null for DRAWN.",
                          "example": 10
                        },
                        "travelDistanceUnit": {
                          "type": "string",
                          "nullable": true,
                          "enum": ["KM", "MILES", null],
                          "description": "The unit of travelDistance. Required for CIRCULAR, null for DRAWN.",
                          "example": "KM"
                        },
                        "travelRegions": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "type": {
                              "type": "string",
                              "enum": ["Polygon", "MultiPolygon"],
                              "description": "The GeoJSON geometry type.",
                              "example": "Polygon"
                            },
                            "coordinates": {
                              "nullable": true,
                              "description": "The GeoJSON coordinates: rings of [longitude, latitude] positions, each ring closed (its last position equals its first).",
                              "example": [
                                [
                                  [-79.42, 43.63],
                                  [-79.33, 43.63],
                                  [-79.33, 43.69],
                                  [-79.42, 43.69],
                                  [-79.42, 43.63]
                                ]
                              ]
                            }
                          },
                          "required": ["type"],
                          "description": "The area of a DRAWN zone, a GeoJSON Polygon or MultiPolygon. Required for DRAWN, null for CIRCULAR.",
                          "example": null
                        },
                        "active": {
                          "type": "boolean",
                          "description": "Active zones can be used by schedules; an inactive zone is kept but offers nothing.",
                          "example": true
                        },
                        "deleted": {
                          "type": "boolean",
                          "description": "True once the zone is soft-deleted.",
                          "example": false
                        },
                        "version": {
                          "type": "integer",
                          "minimum": 0,
                          "exclusiveMinimum": true,
                          "description": "The row’s current version, for optimistic concurrency; a stale value is a 409.",
                          "example": 1
                        },
                        "createdAt": {
                          "type": "string",
                          "description": "When the zone was created (ISO 8601, UTC).",
                          "example": "2026-10-01T14:00:00.000Z"
                        },
                        "updatedAt": {
                          "type": "string",
                          "description": "When the zone was last changed (ISO 8601, UTC).",
                          "example": "2026-10-01T14:00:00.000Z"
                        }
                      },
                      "required": [
                        "supplierTravelZoneId",
                        "projectId",
                        "supplierId",
                        "name",
                        "nameNormalized",
                        "longitude",
                        "latitude",
                        "travelZoneType",
                        "active",
                        "deleted",
                        "version",
                        "createdAt",
                        "updatedAt"
                      ]
                    },
                    "coverageRecompute": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "How many schedules use the zone and were re-computed.",
                          "example": 3
                        },
                        "failed": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "How many of them could not be re-computed; those keep their previous coverage until they are next saved.",
                          "example": 0
                        }
                      },
                      "required": ["total", "failed"],
                      "description": "Present only when the change moved the zone’s geometry."
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such travel zone of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "VERSION_CONFLICT: the row changed since you read it",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "delete": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Delete one of the signed-in supplier’s travel zones",
        "description": "Soft-deletes the travel zone, as the dashboard does. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The travel zone — an area the supplier travels to, a circle or a drawn polygon.",
              "example": "stz_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The travel zone — an area the supplier travels to, a circle or a drawn polygon.",
            "name": "travelZoneId",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Travel zone deleted"
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such travel zone of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "VERSION_CONFLICT: the row changed since you read it",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/locations": {
      "get": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "List the venues the signed-in supplier may be scheduled at",
        "description": "The project's active PHYSICAL and VIRTUAL locations (deleted ones never appear), sorted by name: the venues a supplier can name in a schedule, as the MarketBox dashboard lists them, built by the same code. Each is the supplier view of a location, with no travel settings and no status or audit fields. The list is the whole set, not paginated. To list every location, inactive ones and travel zones included, call `GET /locations?includeInactive=true` with the API key alone. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "The venues",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "locationId": {
                            "type": "string",
                            "description": "The location id.",
                            "example": "loc_01kv60qh7rf3d9mn2ptxwa5zbc"
                          },
                          "projectId": {
                            "type": "string",
                            "description": "The project the location belongs to.",
                            "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
                          },
                          "locationType": {
                            "type": "string",
                            "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"],
                            "description": "PHYSICAL: a venue with an address and coordinates, where the service is delivered. VIRTUAL: delivered online; usually no address. A venue is always one of the two.",
                            "example": "PHYSICAL"
                          },
                          "name": {
                            "type": "string",
                            "description": "The display name, unique within the project among locations of the same type.",
                            "example": "Bondi Pool"
                          },
                          "defaultLanguage": {
                            "type": "string",
                            "description": "The language of `name`. Absent unless the location carries translations in `nameI18n`.",
                            "example": "en"
                          },
                          "nameI18n": {
                            "type": "object",
                            "additionalProperties": {
                              "type": "string"
                            },
                            "description": "The name by language code, when translations are set. Absent otherwise: display `name`.",
                            "example": {
                              "en": "Bondi Pool",
                              "fr": "Piscine de Bondi"
                            }
                          },
                          "addressOneLine": {
                            "type": "string",
                            "nullable": true,
                            "description": "The full address on one line. Usually null for a VIRTUAL location.",
                            "example": "1 Beach Rd, Bondi NSW 2026, AU"
                          },
                          "street": {
                            "type": "string",
                            "nullable": true,
                            "description": "Street line of the address.",
                            "example": "1 Beach Rd"
                          },
                          "city": {
                            "type": "string",
                            "nullable": true,
                            "description": "City.",
                            "example": "Bondi"
                          },
                          "state": {
                            "type": "string",
                            "nullable": true,
                            "description": "State, province or region.",
                            "example": "NSW"
                          },
                          "country": {
                            "type": "string",
                            "nullable": true,
                            "description": "Country.",
                            "example": "AU"
                          },
                          "postalCode": {
                            "type": "string",
                            "nullable": true,
                            "description": "Postal or ZIP code.",
                            "example": "2026"
                          },
                          "longitude": {
                            "type": "number",
                            "nullable": true,
                            "description": "Longitude (WGS 84) of a PHYSICAL venue's position. Usually null for VIRTUAL.",
                            "example": 151.2743
                          },
                          "latitude": {
                            "type": "number",
                            "nullable": true,
                            "description": "Latitude (WGS 84) of a PHYSICAL venue's position. Usually null for VIRTUAL.",
                            "example": -33.8915
                          },
                          "timezone": {
                            "type": "string",
                            "nullable": true,
                            "description": "The location's IANA time zone; a booking at this location is shown in it. Null when not set, in which case the supplier's or the project's zone applies.",
                            "example": "Australia/Sydney"
                          }
                        },
                        "required": [
                          "locationId",
                          "projectId",
                          "locationType",
                          "name"
                        ],
                        "description": "A venue as a supplier sees it: where it is and when it is. No travel settings, no audit fields."
                      }
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/alerts": {
      "get": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "List the signed-in supplier’s alerts",
        "description": "The supplier’s alerts — new, moved and cancelled bookings — newest first, as the bell in the MarketBox dashboard lists them, read by the same code from the same inbox. Each row carries a `target` naming what it is about (`{ kind: \"booking\", bookingId }`); map it to your own page, since alerts hold no URL. `readAt` is absent while unread. Alerts are kept 90 days. Paginated with `limit` (1–100, default 20) and an opaque `cursor`; a cursor from another `filter` is 400 `INVALID_CURSOR`. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "enum": ["unread", "all"],
              "default": "all",
              "description": "`unread` for the unread alerts only; `all` (the default) for every alert.",
              "example": "unread"
            },
            "required": false,
            "description": "`unread` for the unread alerts only; `all` (the default) for every alert.",
            "name": "filter",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "description": "Maximum alerts to return in `data`, 1–100. Defaults to 20. Values outside the range return 400. Treat `nextCursor: null` as the only end-of-results signal.",
              "example": 20
            },
            "required": false,
            "description": "Maximum alerts to return in `data`, 1–100. Defaults to 20. Values outside the range return 400. Treat `nextCursor: null` as the only end-of-results signal.",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Opaque token from a previous response’s `nextCursor`. Valid only for the same `filter` that produced it; any other cursor is 400 `INVALID_CURSOR` — request the first page again without it.",
              "example": "eyJwayI6InByal8wMSJ9"
            },
            "required": false,
            "description": "Opaque token from a previous response’s `nextCursor`. Valid only for the same `filter` that produced it; any other cursor is 400 `INVALID_CURSOR` — request the first page again without it.",
            "name": "cursor",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of alerts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "alertId": {
                            "type": "string",
                            "description": "Unique id of this alert.",
                            "example": "alr_01kv60qge5eh59ap0gw0pqrrys"
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "ORDER_PAID",
                              "REVIEW_RECEIVED",
                              "INVITATION_ACCEPTED",
                              "EMAIL_FAILED",
                              "LESSON_ASSIGNED",
                              "LESSON_MOVED",
                              "LESSON_CANCELLED",
                              "LESSON_REMINDER",
                              "REVIEW_REQUESTED",
                              "PAYMENT_NEEDS_REVIEW"
                            ],
                            "description": "What happened. The `LESSON_*` names are stored identifiers; each concerns a booking. A supplier receives `LESSON_ASSIGNED` (a booking assigned to them), `LESSON_MOVED` (one of their bookings moved) and `LESSON_CANCELLED` (one of their bookings cancelled). Clients receive `LESSON_REMINDER` (a booking is coming up) and `REVIEW_REQUESTED`; staff receive `ORDER_PAID`, `REVIEW_RECEIVED`, `INVITATION_ACCEPTED` and `EMAIL_FAILED`.",
                            "example": "LESSON_MOVED"
                          },
                          "audience": {
                            "type": "string",
                            "enum": ["STAFF", "SUPPLIER", "CLIENT"],
                            "description": "Which of the caller's inboxes this alert is in.",
                            "example": "SUPPLIER"
                          },
                          "createdAt": {
                            "type": "string",
                            "description": "ISO 8601 time the alert was written.",
                            "example": "2026-09-26T14:05:00.000Z"
                          },
                          "occurredAt": {
                            "type": "string",
                            "description": "ISO 8601 time the event itself happened. Shown in the panel.",
                            "example": "2026-09-26T14:04:58.000Z"
                          },
                          "readAt": {
                            "type": "string",
                            "description": "ISO 8601 time the caller read it. Absent while unread.",
                            "example": "2026-09-26T15:00:00.000Z"
                          },
                          "resolvedAt": {
                            "type": "string",
                            "description": "ISO 8601 time the underlying item was dealt with elsewhere.",
                            "example": "2026-09-27T09:12:00.000Z"
                          },
                          "target": {
                            "oneOf": [
                              {
                                "type": "object",
                                "properties": {
                                  "kind": {
                                    "type": "string",
                                    "enum": ["booking"]
                                  },
                                  "bookingId": {
                                    "type": "string",
                                    "minLength": 1
                                  }
                                },
                                "required": ["kind", "bookingId"],
                                "description": "One booking: its detail page."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "kind": {
                                    "type": "string",
                                    "enum": ["order"]
                                  },
                                  "orderId": {
                                    "type": "string",
                                    "minLength": 1
                                  }
                                },
                                "required": ["kind", "orderId"],
                                "description": "One order: its detail page."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "kind": {
                                    "type": "string",
                                    "enum": ["email"]
                                  },
                                  "emailId": {
                                    "type": "string",
                                    "minLength": 1
                                  },
                                  "bookingId": {
                                    "type": "string",
                                    "minLength": 1
                                  }
                                },
                                "required": ["kind", "emailId"],
                                "description": "One sent email, and the booking it was about when known."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "kind": {
                                    "type": "string",
                                    "enum": ["review"]
                                  },
                                  "supplierId": {
                                    "type": "string",
                                    "minLength": 1
                                  }
                                },
                                "required": ["kind"],
                                "description": "The review list, filtered to one supplier when known."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "kind": {
                                    "type": "string",
                                    "enum": ["team"]
                                  }
                                },
                                "required": ["kind"],
                                "description": "The team: the project’s suppliers and staff."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "kind": {
                                    "type": "string",
                                    "enum": ["settings"]
                                  },
                                  "area": {
                                    "type": "string",
                                    "enum": ["payments"]
                                  }
                                },
                                "required": ["kind", "area"],
                                "description": "The project’s payment settings."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "kind": {
                                    "type": "string",
                                    "enum": ["bookings"]
                                  },
                                  "filter": {
                                    "type": "string",
                                    "enum": ["awaiting", "disputed"]
                                  }
                                },
                                "required": ["kind", "filter"],
                                "description": "The project’s bookings list, filtered to those awaiting a report or disputed."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "kind": {
                                    "type": "string",
                                    "enum": ["myAppointments"]
                                  },
                                  "filter": {
                                    "type": "string",
                                    "enum": ["awaiting"]
                                  }
                                },
                                "required": ["kind", "filter"],
                                "description": "The supplier’s own bookings list, filtered to those awaiting their report."
                              }
                            ],
                            "description": "What the alert links to, as data rather than a URL: map it to your own page. `kind` names the page.",
                            "example": {
                              "kind": "booking",
                              "bookingId": "bk_01kv60qge5eh59ap0gw0pqrrys"
                            }
                          },
                          "payload": {
                            "type": "object",
                            "properties": {
                              "clientName": {
                                "type": "string",
                                "description": "Display name of the client the alert is about.",
                                "example": "Jordan Lee"
                              },
                              "supplierName": {
                                "type": "string",
                                "description": "Display name of the supplier the alert is about.",
                                "example": "Sam Rivera"
                              },
                              "serviceName": {
                                "type": "string",
                                "description": "Name of the service booked.",
                                "example": "Private swim lesson"
                              },
                              "startUtc": {
                                "type": "string",
                                "format": "date-time",
                                "description": "Booking start as a UTC instant. Render it in `zone`.",
                                "example": "2026-10-02T14:00:00.000Z"
                              },
                              "zone": {
                                "type": "string",
                                "minLength": 1,
                                "description": "The booking's home IANA zone, which `startUtc` is displayed in.",
                                "example": "America/Toronto"
                              },
                              "count": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "A quantity the copy needs — e.g. the number of bookings on a new order.",
                                "example": 4
                              },
                              "emailType": {
                                "type": "string",
                                "enum": [
                                  "BOOKING_CONFIRMATION",
                                  "BOOKING_REMINDER",
                                  "LEAVE_RATING",
                                  "LEAVE_RATING_FOLLOWUP",
                                  "SUPPLIER_LEAVE_RATING",
                                  "SUPPLIER_LEAVE_RATING_FOLLOWUP",
                                  "SUPPLIER_AGENDA",
                                  "BOOKING_CANCELLED",
                                  "SUPPLIER_BOOKING_CANCELLED",
                                  "BOOKING_UPDATED",
                                  "BOOKING_TIME_OFFER",
                                  "SUPPLIER_NEW_BOOKING",
                                  "ORDER_CANCELLED",
                                  "SUPPLIER_ORDER_CANCELLED",
                                  "INVITATION"
                                ],
                                "description": "Which email failed, on EMAIL_FAILED.",
                                "example": "BOOKING_CONFIRMATION"
                              },
                              "ratingStars": {
                                "type": "integer",
                                "minimum": 1,
                                "maximum": 5,
                                "description": "Stars on REVIEW_RECEIVED.",
                                "example": 5
                              },
                              "inviteeName": {
                                "type": "string",
                                "description": "Display name of the person who accepted, on INVITATION_ACCEPTED.",
                                "example": "Sam Rivera"
                              },
                              "paymentReason": {
                                "type": "string",
                                "enum": [
                                  "DISPUTE_OPENED",
                                  "DISPUTE_WON",
                                  "DISPUTE_LOST",
                                  "PAID_ON_CANCELLED_ORDER",
                                  "ORDER_OVERPAID",
                                  "REFUND_FAILED"
                                ],
                                "description": "Why the payment needs review, on PAYMENT_NEEDS_REVIEW.",
                                "example": "DISPUTE_OPENED"
                              }
                            },
                            "description": "Display fields snapshotted when the alert was written. All optional."
                          }
                        },
                        "required": [
                          "alertId",
                          "kind",
                          "audience",
                          "createdAt",
                          "occurredAt",
                          "target",
                          "payload"
                        ]
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true,
                      "description": "Cursor for the next page; `null` on the last page.",
                      "example": null
                    }
                  },
                  "required": ["data", "nextCursor"]
                }
              }
            }
          },
          "400": {
            "description": "An invalid `filter` or `limit`, or a cursor that is not valid for this list (INVALID_CURSOR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/alerts/summary": {
      "get": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "The signed-in supplier’s unread count and open conditions",
        "description": "What a bell badge needs, in one cheap call: the unread alert count (capped at 100, `unreadCapped` when there may be more) and the open conditions — states computed on every read, such as `MY_REPORTS_OVERDUE` (\"N bookings need your report\"). Conditions have no read state and leave when resolved; their counts may lag up to 5 minutes. Poll it no more often than every 60 seconds; the response is `Cache-Control: no-store`. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "The unread count and conditions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "unreadCount": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Unread alerts for the acting audience, capped at 100.",
                          "example": 4
                        },
                        "unreadCapped": {
                          "type": "boolean",
                          "description": "True when the count hit the cap and there may be more.",
                          "example": false
                        },
                        "conditions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "REPORTS_OVERDUE",
                                  "DISPUTED",
                                  "PAYMENTS_SETUP_INCOMPLETE",
                                  "MY_REPORTS_OVERDUE"
                                ],
                                "description": "Which open condition this is. A supplier sees `MY_REPORTS_OVERDUE` (their bookings awaiting their report). Staff see `REPORTS_OVERDUE` (bookings awaiting a report), `DISPUTED` (disputed bookings) and `PAYMENTS_SETUP_INCOMPLETE`.",
                                "example": "REPORTS_OVERDUE"
                              },
                              "count": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "How many, for the counted conditions. Capped at 100.",
                                "example": 3
                              },
                              "target": {
                                "oneOf": [
                                  {
                                    "type": "object",
                                    "properties": {
                                      "kind": {
                                        "type": "string",
                                        "enum": ["booking"]
                                      },
                                      "bookingId": {
                                        "type": "string",
                                        "minLength": 1
                                      }
                                    },
                                    "required": ["kind", "bookingId"],
                                    "description": "One booking: its detail page."
                                  },
                                  {
                                    "type": "object",
                                    "properties": {
                                      "kind": {
                                        "type": "string",
                                        "enum": ["order"]
                                      },
                                      "orderId": {
                                        "type": "string",
                                        "minLength": 1
                                      }
                                    },
                                    "required": ["kind", "orderId"],
                                    "description": "One order: its detail page."
                                  },
                                  {
                                    "type": "object",
                                    "properties": {
                                      "kind": {
                                        "type": "string",
                                        "enum": ["email"]
                                      },
                                      "emailId": {
                                        "type": "string",
                                        "minLength": 1
                                      },
                                      "bookingId": {
                                        "type": "string",
                                        "minLength": 1
                                      }
                                    },
                                    "required": ["kind", "emailId"],
                                    "description": "One sent email, and the booking it was about when known."
                                  },
                                  {
                                    "type": "object",
                                    "properties": {
                                      "kind": {
                                        "type": "string",
                                        "enum": ["review"]
                                      },
                                      "supplierId": {
                                        "type": "string",
                                        "minLength": 1
                                      }
                                    },
                                    "required": ["kind"],
                                    "description": "The review list, filtered to one supplier when known."
                                  },
                                  {
                                    "type": "object",
                                    "properties": {
                                      "kind": {
                                        "type": "string",
                                        "enum": ["team"]
                                      }
                                    },
                                    "required": ["kind"],
                                    "description": "The team: the project’s suppliers and staff."
                                  },
                                  {
                                    "type": "object",
                                    "properties": {
                                      "kind": {
                                        "type": "string",
                                        "enum": ["settings"]
                                      },
                                      "area": {
                                        "type": "string",
                                        "enum": ["payments"]
                                      }
                                    },
                                    "required": ["kind", "area"],
                                    "description": "The project’s payment settings."
                                  },
                                  {
                                    "type": "object",
                                    "properties": {
                                      "kind": {
                                        "type": "string",
                                        "enum": ["bookings"]
                                      },
                                      "filter": {
                                        "type": "string",
                                        "enum": ["awaiting", "disputed"]
                                      }
                                    },
                                    "required": ["kind", "filter"],
                                    "description": "The project’s bookings list, filtered to those awaiting a report or disputed."
                                  },
                                  {
                                    "type": "object",
                                    "properties": {
                                      "kind": {
                                        "type": "string",
                                        "enum": ["myAppointments"]
                                      },
                                      "filter": {
                                        "type": "string",
                                        "enum": ["awaiting"]
                                      }
                                    },
                                    "required": ["kind", "filter"],
                                    "description": "The supplier’s own bookings list, filtered to those awaiting their report."
                                  }
                                ],
                                "description": "What the alert links to, as data rather than a URL: map it to your own page. `kind` names the page.",
                                "example": {
                                  "kind": "booking",
                                  "bookingId": "bk_01kv60qge5eh59ap0gw0pqrrys"
                                }
                              }
                            },
                            "required": ["kind", "target"]
                          }
                        }
                      },
                      "required": ["unreadCount", "unreadCapped", "conditions"]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/alerts/read-all": {
      "post": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Mark all of the signed-in supplier’s alerts read",
        "description": "Marks up to 1,000 unread alerts read in one call and reports how many (`updated`). When `more` is true, unread alerts remain past the cap: call again until it is false. Conditions are not alerts and are not cleared. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "How many were marked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "updated": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "How many alerts were marked read by this call.",
                          "example": 12
                        },
                        "more": {
                          "type": "boolean",
                          "description": "True when unread alerts remain beyond this call's cap.",
                          "example": false
                        }
                      },
                      "required": ["updated", "more"]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/me/alerts/{alertId}/read": {
      "post": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Supplier plane"],
        "summary": "Mark one of the signed-in supplier’s alerts read",
        "description": "Marks the alert read, typically when the supplier opens it. Answers 204 whether or not it was already read. An id that is not in this supplier’s inbox — missing, another user’s, or in another inbox of theirs — is the same 404. Requires the API key and the supplier’s user token.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "pattern": "^alr_[0-7][0-9a-hjkmnp-tv-z]{25}$",
              "description": "The alert’s id, from the list.",
              "example": "alr_01kv60qge5eh59ap0gw0pqrrys"
            },
            "required": true,
            "description": "The alert’s id, from the list.",
            "name": "alertId",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Marked read (or already read)"
          },
          "400": {
            "description": "A malformed `alertId`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "The API key cannot access this project (FORBIDDEN) or lacks standard API access (CAPABILITY_NOT_GRANTED); or the signed-in user has no MarketBox account record (FORBIDDEN, \"User account not found. Complete registration first.\"); or the signed-in user is not a member of the project (NOT_A_MEMBER), their membership has ended (MEMBERSHIP_INACTIVE), or the roles they act under lack the route’s permission (NO_SUPPLIER_ROLE); or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The signed-in user has no supplier record here: no SUPPLIER among the roles they act under (NO_SUPPLIER_ROLE), or no single supplier record linked to them (SUPPLIER_NOT_LINKED); or no such alert of theirs (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/bookings": {
      "post": {
        "tags": ["Bookings"],
        "summary": "Create a new booking",
        "description": "Creates a single booking. Each service line must reference an existing order + order item (orderId + orderItemId) to draw down — create and pay for an order first. Location fields depend on locationType: TRAVEL_ZONE requires locationId, latitude, longitude, and a structured address; PHYSICAL requires only locationId; VIRTUAL requires none. Local-time fields are derived server-side from bookingTz and must not be sent. The order need not be paid (credits exist from order creation), but a CANCELLED order books nothing (409 ORDER_CANCELLED): its cascade has already released its credits.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Booking data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "supplierId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Assigned supplier. Omit to create an unassigned booking.",
                    "example": "sup_01kv60qgnef2kt3pvqgwmkbzfr"
                  },
                  "clientId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The client this booking is for.",
                    "example": "cli_01kv8p20m1gnqvxl92xln6awk8"
                  },
                  "bookingStartUtc": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Start time in UTC (ISO 8601).",
                    "example": "2026-07-09T13:30:00.000Z"
                  },
                  "bookingEndUtc": {
                    "type": "string",
                    "format": "date-time",
                    "description": "End time in UTC (ISO 8601). Must be after start.",
                    "example": "2026-07-09T14:00:00.000Z"
                  },
                  "bookingTz": {
                    "type": "string",
                    "minLength": 1,
                    "description": "IANA timezone the booking occurs in; local-time fields are derived from this.",
                    "example": "America/Toronto"
                  },
                  "locationType": {
                    "type": "string",
                    "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"],
                    "description": "VIRTUAL, PHYSICAL, or TRAVEL_ZONE. Determines which location fields are required.",
                    "example": "TRAVEL_ZONE"
                  },
                  "locationId": {
                    "type": "string",
                    "nullable": true,
                    "minLength": 1,
                    "description": "For PHYSICAL: the Location id. For TRAVEL_ZONE: the supplierTravelZoneId. Null for VIRTUAL.",
                    "example": "stz_01kv60qgs4e4nbjhzradnqtj0h"
                  },
                  "latitude": {
                    "type": "number",
                    "nullable": true,
                    "description": "Client latitude. Required for TRAVEL_ZONE; must be omitted for PHYSICAL/VIRTUAL.",
                    "example": 43.6532
                  },
                  "longitude": {
                    "type": "number",
                    "nullable": true,
                    "description": "Client longitude. Required for TRAVEL_ZONE; must be omitted for PHYSICAL/VIRTUAL.",
                    "example": -79.3832
                  },
                  "address": {
                    "type": "object",
                    "nullable": true,
                    "properties": {
                      "addressOneLine": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The whole address on one line, as a person would write it.",
                        "example": "10 Main St, Toronto, ON M5V 1A1, Canada"
                      },
                      "streetNumber": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The street number.",
                        "example": "10"
                      },
                      "streetName": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The street name.",
                        "example": "Main St"
                      },
                      "city": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The city or town.",
                        "example": "Toronto"
                      },
                      "state": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The state, province or region; an ISO 3166-2 code when one matches.",
                        "example": "ON"
                      },
                      "country": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The country; ISO 3166-1 alpha-2, alpha-3 or the English name.",
                        "example": "CA"
                      },
                      "zipCode": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The postal or ZIP code, in any national format.",
                        "example": "M5V 1A1"
                      },
                      "unitNumber": {
                        "type": "string",
                        "nullable": true,
                        "description": "The unit, suite or apartment, if any.",
                        "example": "4B"
                      }
                    },
                    "required": [
                      "addressOneLine",
                      "streetNumber",
                      "streetName",
                      "city",
                      "state",
                      "country",
                      "zipCode"
                    ],
                    "description": "Structured client address. Required for TRAVEL_ZONE bookings."
                  },
                  "capacity": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "default": 1,
                    "description": "Max participants for this booking.",
                    "example": 1
                  },
                  "services": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "serviceId": {
                          "type": "string",
                          "minLength": 1,
                          "description": "The service being booked.",
                          "example": "srv_01kv60qg12e82acr78edfnjhvv"
                        },
                        "offeringId": {
                          "type": "string",
                          "minLength": 1,
                          "description": "The specific offering (variant) of the service.",
                          "example": "off_01kv60qge5eh59ap0gw0pqrrys"
                        },
                        "businessModelType": {
                          "type": "string",
                          "enum": [
                            "SINGLE_BOOKING",
                            "PACKAGE",
                            "SCHEDULED_PACKAGE",
                            "SCHEDULED_SUBSCRIPTION",
                            "FLEXIBLE_SUBSCRIPTION"
                          ],
                          "description": "How the service is sold (e.g. SINGLE_BOOKING).",
                          "example": "SINGLE_BOOKING"
                        },
                        "quantity": {
                          "type": "integer",
                          "minimum": 0,
                          "exclusiveMinimum": true,
                          "default": 1,
                          "description": "How many units of the order item this line draws down.",
                          "example": 1
                        },
                        "orderId": {
                          "type": "string",
                          "minLength": 1,
                          "description": "The order that paid for this line.",
                          "example": "ord_01kx16ek2jf4r9da74adf6m4h0"
                        },
                        "orderItemId": {
                          "type": "string",
                          "minLength": 1,
                          "description": "The specific order item (SINGLE_SESSION) to draw down.",
                          "example": "oi_01kx16ek2kf2fsc9x7b2n1dfc9"
                        }
                      },
                      "required": [
                        "serviceId",
                        "offeringId",
                        "businessModelType",
                        "orderId",
                        "orderItemId"
                      ]
                    },
                    "minItems": 1,
                    "description": "One line per service booked; each draws down an order item."
                  },
                  "notes": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "scope": {
                          "type": "string",
                          "enum": ["BOOKING", "BOOKING_SERVICE"]
                        },
                        "bookingServiceId": {
                          "type": "string",
                          "minLength": 1
                        },
                        "noteText": {
                          "type": "string",
                          "minLength": 1
                        }
                      },
                      "required": ["scope", "noteText"]
                    },
                    "default": [],
                    "description": "Optional notes attached to the booking."
                  }
                },
                "required": [
                  "clientId",
                  "bookingStartUtc",
                  "bookingEndUtc",
                  "bookingTz",
                  "locationType",
                  "services"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Booking created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Booking"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error, or an order-item pre-check failed: INVALID_ORDER_REFERENCE, INVALID_ORDER_ITEM_REFERENCE, ORDER_ITEM_SERVICE_MISMATCH, ORDER_ITEM_BUSINESS_MODEL_MISMATCH (the line names a businessModelType the sku of the order item is not sold as), ORDER_ITEM_QUANTITY_UNAVAILABLE. Also 400 when the location is of the wrong type or another supplier’s, or its fields are invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Client, supplier, offering, location or project not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "Supplier time is held or already booked (SLOT_HELD / SLOT_BOOKED), the calendar is under contention (OCCUPANCY_CONTENTION), or the order is cancelled (code: ORDER_CANCELLED)",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/ErrorMessage"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": ["SLOT_HELD", "SLOT_BOOKED"],
                          "description": "Which kind of claim is blocking the requested time.",
                          "example": "SLOT_HELD"
                        },
                        "message": {
                          "type": "string",
                          "description": "Human-readable summary of the conflict.",
                          "example": "Supplier time is not available: HOLD resv_01kv8p20m1gnqvxl92xln6awk8 (2026-08-01T10:00:00Z–2026-08-01T11:00:00Z)"
                        },
                        "statusCode": {
                          "type": "number",
                          "enum": [409],
                          "description": "The HTTP status, repeated in the body — every MarketBox error carries it, so you can branch on the body alone.",
                          "example": 409
                        },
                        "requestId": {
                          "type": "string",
                          "description": "The id of this request (also returned as the X-Request-Id header). Quote it in a support ticket.",
                          "example": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
                        },
                        "conflicts": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "claimType": {
                                "type": "string",
                                "enum": ["BOOKING", "HOLD"],
                                "description": "Whether the blocking claim is a HOLD or a confirmed BOOKING."
                              },
                              "supplierId": {
                                "type": "string",
                                "nullable": true,
                                "description": "The supplier whose calendar is blocked, when known."
                              },
                              "startUtc": {
                                "type": "string",
                                "format": "date-time",
                                "description": "Start of the blocking claim, UTC ISO 8601.",
                                "example": "2026-08-01T10:00:00Z"
                              },
                              "endUtc": {
                                "type": "string",
                                "format": "date-time",
                                "description": "End of the blocking claim, UTC ISO 8601.",
                                "example": "2026-08-01T11:00:00Z"
                              },
                              "reservationId": {
                                "type": "string",
                                "nullable": true,
                                "description": "Present when claimType is HOLD — the reservationId to convert or release. Null for a BOOKING conflict.",
                                "example": "resv_01kv8p20m1gnqvxl92xln6awk8"
                              },
                              "bookingId": {
                                "type": "string",
                                "nullable": true,
                                "description": "Present when claimType is BOOKING — the id of the confirmed booking occupying this time. Null for a HOLD conflict.",
                                "example": null
                              },
                              "heldUntil": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time",
                                "description": "HOLD only: when the blocking hold lazily expires. Null for a BOOKING conflict.",
                                "example": "2026-08-01T10:05:00Z"
                              }
                            },
                            "required": ["claimType", "startUtc", "endUtc"]
                          },
                          "description": "Every live claim that overlaps the requested time — usually one, but can be more."
                        },
                        "hint": {
                          "type": "string",
                          "description": "What to do next: for SLOT_HELD, convert or release the named reservationId (POST .../holds/{reservationId}/convert or /release); for SLOT_BOOKED, search availability again.",
                          "example": "This time is held (reservation resv_01kv8p20m1gnqvxl92xln6awk8). Convert the hold via POST /v1/projects/{projectId}/holds/{reservationId}/convert, or release it with POST /v1/projects/{projectId}/holds/{reservationId}/release. Direct booking routes will not consume a hold — if you hold, you convert."
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "statusCode",
                        "requestId",
                        "conflicts",
                        "hint"
                      ]
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "The booking location is a PHYSICAL Location without coordinates (UNPROCESSABLE_ENTITY): the business’s location data needs fixing; or a line names an offering that is not ACTIVE (NOT_SELLABLE): the line draws down an order item already bought, so only the offering is checked, and a service retired since stays bookable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": ["Bookings"],
        "summary": "List bookings for a project",
        "description": "Bookings across the whole project, filtered by the supported query fields and paginated with `limit`/`cursor` (`nextCursor: null` is the last page). For one supplier's diary or one client's history, prefer the dedicated `/suppliers/{supplierId}/bookings` and `/clients/{clientId}/bookings` lists — they are indexed for exactly that and avoid paging the project.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "required": false,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "required": false,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "SCHEDULED",
                "STARTED",
                "AWAITING_CONFIRMATION",
                "DISPUTED",
                "COMPLETED",
                "CANCELLED",
                "CLIENT_NO_SHOW",
                "SUPPLIER_NO_SHOW",
                "NO_SHOW"
              ]
            },
            "required": false,
            "name": "status",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50,
              "description": "Maximum rows to return in `data`, 1–200. Defaults to 50. Values outside the range return 400. A page can still hold fewer rows than requested, so treat `nextCursor: null` as the only end-of-results signal and never stop on a page that merely looks short.",
              "example": 50
            },
            "required": false,
            "description": "Maximum rows to return in `data`, 1–200. Defaults to 50. Values outside the range return 400. A page can still hold fewer rows than requested, so treat `nextCursor: null` as the only end-of-results signal and never stop on a page that merely looks short.",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Opaque pagination token from a previous response's `nextCursor`. Treat it as a magic string — never parse or construct one. A cursor is only valid for the same filters that produced it, and `nextCursor: null` means the last page."
            },
            "required": false,
            "description": "Opaque pagination token from a previous response's `nextCursor`. Treat it as a magic string — never parse or construct one. A cursor is only valid for the same filters that produced it, and `nextCursor: null` means the last page.",
            "name": "cursor",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Bookings list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Booking"
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": ["data", "nextCursor"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid cursor or limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/bookings/{bookingId}": {
      "get": {
        "tags": ["Bookings"],
        "summary": "Get a booking by ID",
        "description": "The booking record on its own — times, supplier, client, location and status. Local-time fields (`bookingLocalDate`, `bookingLocalStartTime`, …) are derived server-side from the UTC times and the booking timezone, so render those rather than converting the UTC values yourself. Use the `/aggregate` variant when you also need services, participants or notes.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Booking",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Booking"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": ["Bookings"],
        "summary": "Reschedule or update a booking",
        "description": "Moves a booking in time, or edits its details. Send UTC times (`bookingStartUtc`, `bookingEndUtc`) with `bookingTz`; the four local-time fields are computed from those and are deliberately NOT accepted here — passing local times directly is how a booking ends up disagreeing with itself across timezones. Rescheduling re-checks supplier availability, so a slot taken in the meantime is rejected rather than double-booked. Returns 409 if the booking changed underneath you. Only a `SCHEDULED` or `STARTED` booking can have its time or supplier changed: moving one that has been reported on, settled or cancelled is 422 `BOOKING_NOT_AMENDABLE` (its other fields can still be edited).",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Booking patch",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "supplierId": {
                    "type": "string",
                    "minLength": 1
                  },
                  "bookingStartUtc": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "bookingEndUtc": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "bookingTz": {
                    "type": "string",
                    "minLength": 1
                  },
                  "latitude": {
                    "type": "number",
                    "nullable": true
                  },
                  "longitude": {
                    "type": "number",
                    "nullable": true
                  },
                  "address": {
                    "$ref": "#/components/schemas/Address"
                  },
                  "capacity": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated booking",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Booking"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error, or a location change the booking cannot take",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Booking, supplier or location not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "The booking changed underneath you (VERSION_CONFLICT), or the new time or supplier is taken (SLOT_HELD / SLOT_BOOKED), or the calendar is under contention (OCCUPANCY_CONTENTION)",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/ErrorMessage"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": ["SLOT_HELD", "SLOT_BOOKED"],
                          "description": "Which kind of claim is blocking the requested time.",
                          "example": "SLOT_HELD"
                        },
                        "message": {
                          "type": "string",
                          "description": "Human-readable summary of the conflict.",
                          "example": "Supplier time is not available: HOLD resv_01kv8p20m1gnqvxl92xln6awk8 (2026-08-01T10:00:00Z–2026-08-01T11:00:00Z)"
                        },
                        "statusCode": {
                          "type": "number",
                          "enum": [409],
                          "description": "The HTTP status, repeated in the body — every MarketBox error carries it, so you can branch on the body alone.",
                          "example": 409
                        },
                        "requestId": {
                          "type": "string",
                          "description": "The id of this request (also returned as the X-Request-Id header). Quote it in a support ticket.",
                          "example": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
                        },
                        "conflicts": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "claimType": {
                                "type": "string",
                                "enum": ["BOOKING", "HOLD"],
                                "description": "Whether the blocking claim is a HOLD or a confirmed BOOKING."
                              },
                              "supplierId": {
                                "type": "string",
                                "nullable": true,
                                "description": "The supplier whose calendar is blocked, when known."
                              },
                              "startUtc": {
                                "type": "string",
                                "format": "date-time",
                                "description": "Start of the blocking claim, UTC ISO 8601.",
                                "example": "2026-08-01T10:00:00Z"
                              },
                              "endUtc": {
                                "type": "string",
                                "format": "date-time",
                                "description": "End of the blocking claim, UTC ISO 8601.",
                                "example": "2026-08-01T11:00:00Z"
                              },
                              "reservationId": {
                                "type": "string",
                                "nullable": true,
                                "description": "Present when claimType is HOLD — the reservationId to convert or release. Null for a BOOKING conflict.",
                                "example": "resv_01kv8p20m1gnqvxl92xln6awk8"
                              },
                              "bookingId": {
                                "type": "string",
                                "nullable": true,
                                "description": "Present when claimType is BOOKING — the id of the confirmed booking occupying this time. Null for a HOLD conflict.",
                                "example": null
                              },
                              "heldUntil": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time",
                                "description": "HOLD only: when the blocking hold lazily expires. Null for a BOOKING conflict.",
                                "example": "2026-08-01T10:05:00Z"
                              }
                            },
                            "required": ["claimType", "startUtc", "endUtc"]
                          },
                          "description": "Every live claim that overlaps the requested time — usually one, but can be more."
                        },
                        "hint": {
                          "type": "string",
                          "description": "What to do next: for SLOT_HELD, convert or release the named reservationId (POST .../holds/{reservationId}/convert or /release); for SLOT_BOOKED, search availability again.",
                          "example": "This time is held (reservation resv_01kv8p20m1gnqvxl92xln6awk8). Convert the hold via POST /v1/projects/{projectId}/holds/{reservationId}/convert, or release it with POST /v1/projects/{projectId}/holds/{reservationId}/release. Direct booking routes will not consume a hold — if you hold, you convert."
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "statusCode",
                        "requestId",
                        "conflicts",
                        "hint"
                      ]
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "The booking is no longer scheduled or started, so its time and supplier cannot change (BOOKING_NOT_AMENDABLE), or its location is a PHYSICAL Location without coordinates (UNPROCESSABLE_ENTITY): the business’s location data needs fixing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Bookings"],
        "summary": "Soft-delete a booking",
        "description": "Marks the booking deleted and hides it from lists, retaining the record so history stays auditable. This is not how you cancel: use `POST /status` with `CANCELLED` for a booking that genuinely was called off — it keeps the booking visible, records a reason and lets you choose the credit treatment. Reserve delete for bookings created in error. A delete still releases the supplier time and settles the order item exactly as a default cancel does: a package session goes back to its order item, a single-session allocation is closed. A delete IS a cancel first: only a booking this key could cancel through `POST /status` can be deleted, so one that took place or was settled (AWAITING_CONFIRMATION, COMPLETED, a no-show) is 422 `BOOKING_NOT_DELETABLE`. Deleting a booking that is already cancelled leaves the settlement of that cancel as it stands, and sends no second cancellation email. Returns 204 with no body.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Booking not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "Version conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "422": {
            "description": "The booking cannot be cancelled now, so it cannot be deleted (BOOKING_NOT_DELETABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/bookings/{bookingId}/aggregate": {
      "get": {
        "tags": ["Bookings"],
        "summary": "Get a booking with its services, participants, notes, reports and party names",
        "description": "The booking plus everything hanging off it — service lines, participants, notes and attendance reports — in one call. This is the shape for a booking detail screen; assembling it from five separate endpoints is slower and can tear if something changes mid-sequence. `reports` holds at most two rows, one per side; see POST /bookings/{bookingId}/reports for what a report asserts.\n\n`parties` carries both sides with their display names resolved, so a page can render \"How was your booking with Javier?\" without a second call — and there is no public endpoint that turns a `clientId` into a name, so this is the only way to get one. It is available immediately, before any review exists. `parties.supplier` is `null` when no supplier is assigned, and each `fullName` is best-effort: a party whose profile cannot be resolved keeps its bare id rather than failing the call. Names only — no email address is returned for either party.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Booking aggregate",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "booking": {
                          "$ref": "#/components/schemas/Booking"
                        },
                        "services": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "projectId": {
                                "type": "string"
                              },
                              "bookingId": {
                                "type": "string"
                              },
                              "bookingServiceId": {
                                "type": "string"
                              },
                              "businessModelType": {
                                "type": "string",
                                "enum": [
                                  "SINGLE_BOOKING",
                                  "PACKAGE",
                                  "SCHEDULED_PACKAGE",
                                  "SCHEDULED_SUBSCRIPTION",
                                  "FLEXIBLE_SUBSCRIPTION"
                                ],
                                "description": "How the service is sold. SINGLE_BOOKING is one booking at a time; PACKAGE sells prepaid credits drawn down by later bookings; the SCHEDULED_* and FLEXIBLE_* variants add recurrence and subscription billing. This drives which order item skuType applies."
                              },
                              "offeringSnapshot": {
                                "type": "object",
                                "properties": {
                                  "serviceId": {
                                    "type": "string",
                                    "minLength": 1
                                  },
                                  "offeringId": {
                                    "type": "string",
                                    "minLength": 1
                                  },
                                  "name": {
                                    "type": "object",
                                    "additionalProperties": {
                                      "type": "string"
                                    }
                                  },
                                  "price": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "duration": {
                                    "oneOf": [
                                      {
                                        "type": "object",
                                        "properties": {
                                          "type": {
                                            "type": "string",
                                            "enum": ["FIXED"]
                                          },
                                          "minutes": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "exclusiveMinimum": true
                                          }
                                        },
                                        "required": ["type", "minutes"]
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "type": {
                                            "type": "string",
                                            "enum": ["FLEXIBLE"]
                                          },
                                          "defaultMinutes": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "exclusiveMinimum": true
                                          },
                                          "minMinutes": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "exclusiveMinimum": true
                                          },
                                          "stepMinutes": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "exclusiveMinimum": true
                                          },
                                          "pricePerStep": {
                                            "$ref": "#/components/schemas/Money"
                                          }
                                        },
                                        "required": [
                                          "type",
                                          "defaultMinutes",
                                          "minMinutes",
                                          "stepMinutes"
                                        ]
                                      }
                                    ]
                                  },
                                  "attributeValues": {
                                    "type": "array",
                                    "items": {
                                      "type": "object",
                                      "properties": {
                                        "attributeId": {
                                          "type": "string",
                                          "minLength": 1
                                        },
                                        "attributeNameSnapshot": {
                                          "type": "object",
                                          "additionalProperties": {
                                            "type": "string"
                                          }
                                        },
                                        "attributeType": {
                                          "type": "string",
                                          "enum": ["STRING", "NUMBER", "ENUM"],
                                          "description": "Value type of a service attribute. ENUM attributes carry an allowed-values list."
                                        },
                                        "value": {
                                          "anyOf": [
                                            {
                                              "type": "object",
                                              "additionalProperties": {
                                                "type": "string"
                                              }
                                            },
                                            {
                                              "type": "number"
                                            },
                                            {
                                              "type": "string"
                                            }
                                          ]
                                        },
                                        "valueId": {
                                          "type": "string"
                                        }
                                      },
                                      "required": [
                                        "attributeId",
                                        "attributeNameSnapshot",
                                        "attributeType"
                                      ]
                                    }
                                  }
                                },
                                "required": [
                                  "serviceId",
                                  "offeringId",
                                  "price",
                                  "duration",
                                  "attributeValues"
                                ]
                              },
                              "quantity": {
                                "type": "integer",
                                "minimum": 0,
                                "exclusiveMinimum": true
                              },
                              "durationMinutes": {
                                "type": "integer",
                                "minimum": 0,
                                "exclusiveMinimum": true
                              },
                              "unitPrice": {
                                "$ref": "#/components/schemas/Money"
                              },
                              "lineAmount": {
                                "$ref": "#/components/schemas/Money"
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "SCHEDULED",
                                  "IN_PROGRESS",
                                  "COMPLETED",
                                  "CANCELLED",
                                  "NO_SHOW"
                                ]
                              },
                              "deleted": {
                                "type": "boolean"
                              },
                              "createdAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "updatedAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "createdBy": {
                                "type": "string"
                              },
                              "updatedBy": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "projectId",
                              "bookingId",
                              "bookingServiceId",
                              "businessModelType",
                              "offeringSnapshot",
                              "quantity",
                              "durationMinutes",
                              "unitPrice",
                              "lineAmount",
                              "status",
                              "deleted",
                              "createdAt",
                              "updatedAt",
                              "createdBy",
                              "updatedBy"
                            ]
                          }
                        },
                        "participants": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "projectId": {
                                "type": "string"
                              },
                              "bookingId": {
                                "type": "string"
                              },
                              "clientId": {
                                "type": "string"
                              },
                              "participantStatus": {
                                "type": "string",
                                "enum": [
                                  "REGISTERED",
                                  "WAITLISTED",
                                  "CANCELLED",
                                  "NO_SHOW",
                                  "ATTENDED"
                                ]
                              },
                              "checkInStatus": {
                                "type": "string",
                                "enum": ["PENDING", "CHECKED_IN", "NO_SHOW"]
                              },
                              "checkInAt": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time"
                              },
                              "registeredAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "waitlistPosition": {
                                "type": "integer",
                                "nullable": true,
                                "minimum": 0
                              },
                              "deleted": {
                                "type": "boolean"
                              },
                              "createdAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "updatedAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "createdBy": {
                                "type": "string"
                              },
                              "updatedBy": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "projectId",
                              "bookingId",
                              "clientId",
                              "participantStatus",
                              "checkInStatus",
                              "registeredAt",
                              "deleted",
                              "createdAt",
                              "updatedAt",
                              "createdBy",
                              "updatedBy"
                            ]
                          }
                        },
                        "notes": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "projectId": {
                                "type": "string"
                              },
                              "bookingId": {
                                "type": "string"
                              },
                              "noteId": {
                                "type": "string"
                              },
                              "scope": {
                                "type": "string",
                                "enum": ["BOOKING", "BOOKING_SERVICE"]
                              },
                              "bookingServiceId": {
                                "type": "string",
                                "nullable": true
                              },
                              "noteText": {
                                "type": "string",
                                "minLength": 1
                              },
                              "deleted": {
                                "type": "boolean"
                              },
                              "createdAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "updatedAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "createdBy": {
                                "type": "string"
                              },
                              "updatedBy": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "projectId",
                              "bookingId",
                              "noteId",
                              "scope",
                              "noteText",
                              "deleted",
                              "createdAt",
                              "updatedAt",
                              "createdBy",
                              "updatedBy"
                            ]
                          }
                        },
                        "reports": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/BookingReport"
                          }
                        },
                        "parties": {
                          "type": "object",
                          "properties": {
                            "client": {
                              "type": "object",
                              "properties": {
                                "clientId": {
                                  "type": "string",
                                  "description": "The client on this booking.",
                                  "example": "cli_01kv60qge5eh59ap0gw0pqrrys"
                                },
                                "fullName": {
                                  "type": "string",
                                  "description": "Display name, resolved from the client profile. Best-effort: absent when the profile cannot be resolved, which is not an error — render the id instead.",
                                  "example": "Cara Client"
                                }
                              },
                              "required": ["clientId"],
                              "description": "The client. Always present — every booking has one."
                            },
                            "supplier": {
                              "type": "object",
                              "nullable": true,
                              "properties": {
                                "supplierId": {
                                  "type": "string",
                                  "description": "The supplier assigned to this booking.",
                                  "example": "sup_01kv60qge5eh59ap0gw0pqrrys"
                                },
                                "fullName": {
                                  "type": "string",
                                  "description": "Display name, resolved from the supplier profile. Best-effort: absent when the profile cannot be resolved, which is not an error — render the id instead.",
                                  "example": "Javier Supplier"
                                }
                              },
                              "required": ["supplierId"],
                              "description": "`null` when no supplier is assigned yet — a legal state for a booking, not an error."
                            }
                          },
                          "required": ["client", "supplier"]
                        }
                      },
                      "required": [
                        "booking",
                        "services",
                        "participants",
                        "notes",
                        "reports",
                        "parties"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/bookings/{bookingId}/status": {
      "post": {
        "tags": ["Bookings"],
        "summary": "Change a booking status",
        "description": "Moves the booking through its lifecycle. The `status` enum on the request body is the authoritative list of what a caller may ASK for — it is narrower than the `status` on the response, because `SCHEDULED` and `DISPUTED` are states a booking is put into by the platform and can only be observed, never requested.\n\nWhich of the settable statuses your key may actually use also depends on where the booking is now and on the capacity of the caller. An API key cannot resolve a dispute, and cannot reverse a settled booking back to `AWAITING_CONFIRMATION`: both decide between two accounts of what happened, and are reserved for an operator in the MarketBox console. Nor can it cancel a booking that is `AWAITING_CONFIRMATION`: the session has taken place, and cancelling it would void the supplier's claim to be paid. Settle it instead (`COMPLETED` or a no-show).\n\n`NO_SHOW` can no longer be SET. Use `CLIENT_NO_SHOW` or `SUPPLIER_NO_SHOW`, which record which side was absent; sending `NO_SHOW` returns a 400 naming the value. It remains a status a booking can CARRY and is still returned by every read: bookings recorded before the split keep it indefinitely and are not being migrated, because nobody ever recorded which party failed to show and we will not guess. A consumer switching exhaustively on booking status must keep handling it.\n\nA transition the booking cannot make from where it currently stands is a 400 naming that current status, so a rejection tells you what to retry from. Returns 409 if the booking changed underneath you.\n\nCancelling releases the supplier time and settles the order item the booking drew on, atomically with the status change. For a PACKAGE session the credit goes back to the order item by default (`quantityRemaining` rises by the quantity the session used, and a `CREDIT_REVERSAL` transaction is recorded against the original `CREDIT_REDEMPTION`). Send `creditTreatment: \"FORFEIT\"` to keep the session spent instead — a late cancellation, say; `\"RETURN\"` states the default explicitly. A booking made against a single-session order item holds no reusable credit: cancelling it closes its allocation and returns no quantity, and sending `creditTreatment` for one is a 422 `NO_SESSION_CREDIT` with nothing cancelled. `creditTreatment` is only valid with `CANCELLED`. This route never moves money.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "New status",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "STARTED",
                      "AWAITING_CONFIRMATION",
                      "COMPLETED",
                      "CANCELLED",
                      "CLIENT_NO_SHOW",
                      "SUPPLIER_NO_SHOW"
                    ]
                  },
                  "cancellationReason": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Required when status is CANCELLED; omitting it then is a 400. Why the booking was cancelled."
                  },
                  "creditTreatment": {
                    "type": "string",
                    "enum": ["RETURN", "FORFEIT"],
                    "description": "CANCELLED only. What happens to a package session credit: RETURN (the default when omitted) puts the session back on the order item; FORFEIT keeps it spent. Sending it for a booking that is not a package session is a 422 NO_SESSION_CREDIT.",
                    "example": "FORFEIT"
                  }
                },
                "required": ["status"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated booking",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Booking"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid transition or validation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Booking not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "Version conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "422": {
            "description": "`creditTreatment` was sent for a booking with no session credit; nothing was cancelled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/{supplierId}/bookings": {
      "get": {
        "tags": ["Bookings"],
        "summary": "List bookings for a supplier",
        "description": "One supplier's diary, ordered by date and paginated. This is the indexed path for a supplier-facing schedule — use it rather than listing the project and filtering client-side.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The supplier — the person or resource delivering the service.",
              "example": "sup_01kv60qh1k5xylm7r0c1qj8zpa"
            },
            "required": true,
            "description": "The supplier — the person or resource delivering the service.",
            "name": "supplierId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "required": false,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "required": false,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "SCHEDULED",
                "STARTED",
                "AWAITING_CONFIRMATION",
                "DISPUTED",
                "COMPLETED",
                "CANCELLED",
                "CLIENT_NO_SHOW",
                "SUPPLIER_NO_SHOW",
                "NO_SHOW"
              ]
            },
            "required": false,
            "name": "status",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50,
              "description": "Maximum rows to return in `data`, 1–200. Defaults to 50. Values outside the range return 400. A page can still hold fewer rows than requested, so treat `nextCursor: null` as the only end-of-results signal and never stop on a page that merely looks short.",
              "example": 50
            },
            "required": false,
            "description": "Maximum rows to return in `data`, 1–200. Defaults to 50. Values outside the range return 400. A page can still hold fewer rows than requested, so treat `nextCursor: null` as the only end-of-results signal and never stop on a page that merely looks short.",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Opaque pagination token from a previous response's `nextCursor`. Treat it as a magic string — never parse or construct one. A cursor is only valid for the same filters that produced it, and `nextCursor: null` means the last page."
            },
            "required": false,
            "description": "Opaque pagination token from a previous response's `nextCursor`. Treat it as a magic string — never parse or construct one. A cursor is only valid for the same filters that produced it, and `nextCursor: null` means the last page.",
            "name": "cursor",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Bookings list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Booking"
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": ["data", "nextCursor"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid cursor or limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/clients/{clientId}/bookings": {
      "get": {
        "tags": ["Bookings"],
        "summary": "List bookings for a client",
        "description": "One client's bookings, past and upcoming, ordered by date and paginated. This is the call behind a client-facing \"my bookings\" view.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The client — the person the booking is for.",
              "example": "cli_01kv6r83j9fmquwl81xkm5bwj6"
            },
            "required": true,
            "description": "The client — the person the booking is for.",
            "name": "clientId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "required": false,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "required": false,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "SCHEDULED",
                "STARTED",
                "AWAITING_CONFIRMATION",
                "DISPUTED",
                "COMPLETED",
                "CANCELLED",
                "CLIENT_NO_SHOW",
                "SUPPLIER_NO_SHOW",
                "NO_SHOW"
              ]
            },
            "required": false,
            "name": "status",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50,
              "description": "Maximum rows to return in `data`, 1–200. Defaults to 50. Values outside the range return 400. A page can still hold fewer rows than requested, so treat `nextCursor: null` as the only end-of-results signal and never stop on a page that merely looks short.",
              "example": 50
            },
            "required": false,
            "description": "Maximum rows to return in `data`, 1–200. Defaults to 50. Values outside the range return 400. A page can still hold fewer rows than requested, so treat `nextCursor: null` as the only end-of-results signal and never stop on a page that merely looks short.",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Opaque pagination token from a previous response's `nextCursor`. Treat it as a magic string — never parse or construct one. A cursor is only valid for the same filters that produced it, and `nextCursor: null` means the last page."
            },
            "required": false,
            "description": "Opaque pagination token from a previous response's `nextCursor`. Treat it as a magic string — never parse or construct one. A cursor is only valid for the same filters that produced it, and `nextCursor: null` means the last page.",
            "name": "cursor",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Bookings list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Booking"
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": ["data", "nextCursor"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid cursor or limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/bookings/{bookingId}/participants": {
      "post": {
        "tags": ["Bookings"],
        "summary": "Register a participant on a booking",
        "description": "Adds a client to a booking that seats more than one person, such as a class or a group session. Capacity is enforced, so registering past the capacity set on the booking is rejected rather than silently overbooking. Registering the same client twice is a conflict, not a duplicate row; a participant who was removed can be registered again. Only a booking that is `SCHEDULED` or `STARTED` takes a registration: any other status is 422 `BOOKING_NOT_OPEN_FOR_PARTICIPANTS`.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Participant data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "clientId": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "required": ["clientId"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Participant registered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "projectId": {
                          "type": "string"
                        },
                        "bookingId": {
                          "type": "string"
                        },
                        "clientId": {
                          "type": "string"
                        },
                        "participantStatus": {
                          "type": "string",
                          "enum": [
                            "REGISTERED",
                            "WAITLISTED",
                            "CANCELLED",
                            "NO_SHOW",
                            "ATTENDED"
                          ]
                        },
                        "checkInStatus": {
                          "type": "string",
                          "enum": ["PENDING", "CHECKED_IN", "NO_SHOW"]
                        },
                        "checkInAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "registeredAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "waitlistPosition": {
                          "type": "integer",
                          "nullable": true,
                          "minimum": 0
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "projectId",
                        "bookingId",
                        "clientId",
                        "participantStatus",
                        "checkInStatus",
                        "registeredAt",
                        "deleted",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Booking or client not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "Capacity exceeded or already registered",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "422": {
            "description": "The booking is no longer scheduled or started (BOOKING_NOT_OPEN_FOR_PARTICIPANTS)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": ["Bookings"],
        "summary": "List participants on a booking",
        "description": "Everyone registered on the booking, with their check-in state. This is the roster a supplier works from at the door.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Participants",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "projectId": {
                            "type": "string"
                          },
                          "bookingId": {
                            "type": "string"
                          },
                          "clientId": {
                            "type": "string"
                          },
                          "participantStatus": {
                            "type": "string",
                            "enum": [
                              "REGISTERED",
                              "WAITLISTED",
                              "CANCELLED",
                              "NO_SHOW",
                              "ATTENDED"
                            ]
                          },
                          "checkInStatus": {
                            "type": "string",
                            "enum": ["PENDING", "CHECKED_IN", "NO_SHOW"]
                          },
                          "checkInAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "registeredAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "waitlistPosition": {
                            "type": "integer",
                            "nullable": true,
                            "minimum": 0
                          },
                          "deleted": {
                            "type": "boolean"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "createdBy": {
                            "type": "string"
                          },
                          "updatedBy": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "projectId",
                          "bookingId",
                          "clientId",
                          "participantStatus",
                          "checkInStatus",
                          "registeredAt",
                          "deleted",
                          "createdAt",
                          "updatedAt",
                          "createdBy",
                          "updatedBy"
                        ]
                      }
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/bookings/{bookingId}/participants/{clientId}": {
      "get": {
        "tags": ["Bookings"],
        "summary": "Get a single booking participant",
        "description": "One participant's registration on this booking, including whether they have checked in. Returns 404 when the client is not registered on it.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The client — the person the booking is for.",
              "example": "cli_01kv6r83j9fmquwl81xkm5bwj6"
            },
            "required": true,
            "description": "The client — the person the booking is for.",
            "name": "clientId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Participant",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "projectId": {
                          "type": "string"
                        },
                        "bookingId": {
                          "type": "string"
                        },
                        "clientId": {
                          "type": "string"
                        },
                        "participantStatus": {
                          "type": "string",
                          "enum": [
                            "REGISTERED",
                            "WAITLISTED",
                            "CANCELLED",
                            "NO_SHOW",
                            "ATTENDED"
                          ]
                        },
                        "checkInStatus": {
                          "type": "string",
                          "enum": ["PENDING", "CHECKED_IN", "NO_SHOW"]
                        },
                        "checkInAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "registeredAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "waitlistPosition": {
                          "type": "integer",
                          "nullable": true,
                          "minimum": 0
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "projectId",
                        "bookingId",
                        "clientId",
                        "participantStatus",
                        "checkInStatus",
                        "registeredAt",
                        "deleted",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Participant not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Bookings"],
        "summary": "Cancel a booking participant",
        "description": "Removes one participant from the booking, freeing their seat for someone else. The booking itself stays scheduled for everyone else — to call off the whole booking, change its status to CANCELLED instead. Returns 204 with no body.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The client — the person the booking is for.",
              "example": "cli_01kv6r83j9fmquwl81xkm5bwj6"
            },
            "required": true,
            "description": "The client — the person the booking is for.",
            "name": "clientId",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Cancelled"
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Participant or booking not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/bookings/{bookingId}/participants/{clientId}/check-in": {
      "post": {
        "tags": ["Bookings"],
        "summary": "Check in a participant",
        "description": "Records that the participant physically arrived. Idempotent in effect — checking in someone already checked in leaves them checked in — so it is safe to retry from a door-scanning client with unreliable connectivity, and a retry keeps the first `checkInAt`. This tracks attendance only; it does not change the booking status. A booking that is settled, disputed or cancelled no longer takes a check-in (422 `BOOKING_NOT_OPEN_FOR_PARTICIPANTS`); one that has just ended and is `AWAITING_CONFIRMATION` still does.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The client — the person the booking is for.",
              "example": "cli_01kv6r83j9fmquwl81xkm5bwj6"
            },
            "required": true,
            "description": "The client — the person the booking is for.",
            "name": "clientId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Checked in",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "projectId": {
                          "type": "string"
                        },
                        "bookingId": {
                          "type": "string"
                        },
                        "clientId": {
                          "type": "string"
                        },
                        "participantStatus": {
                          "type": "string",
                          "enum": [
                            "REGISTERED",
                            "WAITLISTED",
                            "CANCELLED",
                            "NO_SHOW",
                            "ATTENDED"
                          ]
                        },
                        "checkInStatus": {
                          "type": "string",
                          "enum": ["PENDING", "CHECKED_IN", "NO_SHOW"]
                        },
                        "checkInAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "registeredAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "waitlistPosition": {
                          "type": "integer",
                          "nullable": true,
                          "minimum": 0
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "projectId",
                        "bookingId",
                        "clientId",
                        "participantStatus",
                        "checkInStatus",
                        "registeredAt",
                        "deleted",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Booking or participant not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "422": {
            "description": "The booking is settled, disputed or cancelled (BOOKING_NOT_OPEN_FOR_PARTICIPANTS)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/bookings/{bookingId}/notes": {
      "post": {
        "tags": ["Bookings"],
        "summary": "Create a booking note",
        "description": "Attaches a free-text note to the booking — preparation details, access instructions, what happened on the day. Notes are operational context for staff, not a channel to the client, and nothing here is shown to the client automatically.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Note data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scope": {
                    "type": "string",
                    "enum": ["BOOKING", "BOOKING_SERVICE"]
                  },
                  "bookingServiceId": {
                    "type": "string",
                    "minLength": 1
                  },
                  "noteText": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "required": ["scope", "noteText"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Note created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "projectId": {
                          "type": "string"
                        },
                        "bookingId": {
                          "type": "string"
                        },
                        "noteId": {
                          "type": "string"
                        },
                        "scope": {
                          "type": "string",
                          "enum": ["BOOKING", "BOOKING_SERVICE"]
                        },
                        "bookingServiceId": {
                          "type": "string",
                          "nullable": true
                        },
                        "noteText": {
                          "type": "string",
                          "minLength": 1
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "projectId",
                        "bookingId",
                        "noteId",
                        "scope",
                        "noteText",
                        "deleted",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": ["Bookings"],
        "summary": "List booking notes",
        "description": "Every note on the booking, newest first. Also available inside GET /bookings/{bookingId}/aggregate, so prefer that when you need the booking and its notes together.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Notes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "projectId": {
                            "type": "string"
                          },
                          "bookingId": {
                            "type": "string"
                          },
                          "noteId": {
                            "type": "string"
                          },
                          "scope": {
                            "type": "string",
                            "enum": ["BOOKING", "BOOKING_SERVICE"]
                          },
                          "bookingServiceId": {
                            "type": "string",
                            "nullable": true
                          },
                          "noteText": {
                            "type": "string",
                            "minLength": 1
                          },
                          "deleted": {
                            "type": "boolean"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "createdBy": {
                            "type": "string"
                          },
                          "updatedBy": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "projectId",
                          "bookingId",
                          "noteId",
                          "scope",
                          "noteText",
                          "deleted",
                          "createdAt",
                          "updatedAt",
                          "createdBy",
                          "updatedBy"
                        ]
                      }
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/bookings/{bookingId}/notes/{noteId}": {
      "patch": {
        "tags": ["Bookings"],
        "summary": "Update a booking note",
        "description": "Edits the body of an existing note in place. The note keeps its id and position in the list, so an edit does not resurface it as new.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "A note attached to the booking.",
              "example": "note_01kv9c15r7mfuzyq36bps0eap2"
            },
            "required": true,
            "description": "A note attached to the booking.",
            "name": "noteId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Note update",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "noteText": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "required": ["noteText"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated note",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "projectId": {
                          "type": "string"
                        },
                        "bookingId": {
                          "type": "string"
                        },
                        "noteId": {
                          "type": "string"
                        },
                        "scope": {
                          "type": "string",
                          "enum": ["BOOKING", "BOOKING_SERVICE"]
                        },
                        "bookingServiceId": {
                          "type": "string",
                          "nullable": true
                        },
                        "noteText": {
                          "type": "string",
                          "minLength": 1
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "projectId",
                        "bookingId",
                        "noteId",
                        "scope",
                        "noteText",
                        "deleted",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Note not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Bookings"],
        "summary": "Delete a booking note",
        "description": "Permanently removes the note. Unlike bookings and orders, notes are not soft-deleted — there is no audit reason to retain one, and nothing else references it. Returns 204 with no body.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "A note attached to the booking.",
              "example": "note_01kv9c15r7mfuzyq36bps0eap2"
            },
            "required": true,
            "description": "A note attached to the booking.",
            "name": "noteId",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Note or booking not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/bookings/{bookingId}/reviews": {
      "post": {
        "tags": ["Reviews"],
        "summary": "Review a booking, in either direction",
        "description": "Records one side of a booking rating the other, and folds the rating into the rated party's running average in the same atomic write. Both parties are read off the booking in the URL — the body carries **no ids at all**, so a review can only ever be attributed to the supplier and client who were actually on that booking.\n\n`direction` picks who is rating whom. `CLIENT_TO_SUPPLIER` is the client rating the supplier; `SUPPLIER_TO_CLIENT` is the supplier rating the client. The response tells you which party the review is *about* without re-deriving it: `subjectType` is `SUPPLIER` or `CLIENT`, and `subjectId` is that party's id.\n\n**The booking does not have to be COMPLETED.** Nothing in MarketBox moves a booking to COMPLETED automatically — the status is only ever set deliberately — so requiring it would make this endpoint unusable for most tenants. Any booking is reviewable except a CANCELLED one, which returns 422. A booking with no supplier assigned is a legal state, but there is no supplier to rate or to rate from, so it also returns 422.\n\nAt most **one review per booking per direction**, enforced by a uniqueness item written inside the same transaction rather than by a read beforehand — two simultaneous submits cannot both win. A second review in the same direction returns 409 `REVIEW_ALREADY_EXISTS`. Reviews posted through the older project-level `POST /reviews` route carry no such guard, so this endpoint also runs a best-effort index lookup first and will report 409 for one it can see; that lookup reads an eventually-consistent index, so treat it as a courtesy rather than the guarantee.\n\nTreat a review as permanent — there is no update or delete route, and the average it moved stays moved.\n\nThe response carries best-effort display names (`supplierName`, `clientName`) resolved from the two profiles, so a hosted review page can render a name without a second call. A counterparty whose profile cannot be resolved keeps its bare id and the corresponding name is absent. No email address is returned for either party.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Review data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "direction": {
                    "type": "string",
                    "enum": ["CLIENT_TO_SUPPLIER", "SUPPLIER_TO_CLIENT"],
                    "description": "Which way the review points. CLIENT_TO_SUPPLIER is the client rating the supplier; SUPPLIER_TO_CLIENT is the supplier rating the client.",
                    "example": "CLIENT_TO_SUPPLIER"
                  },
                  "ratingStars": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 5,
                    "description": "Whole-star rating from 1 to 5.",
                    "example": 5
                  },
                  "reviewText": {
                    "type": "string",
                    "maxLength": 5000,
                    "description": "Optional free-text comment, up to 5000 characters.",
                    "example": "Turned up on time and was a pleasure to work with."
                  }
                },
                "required": ["direction", "ratingStars"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Review created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "reviewId": {
                          "type": "string"
                        },
                        "supplierId": {
                          "type": "string"
                        },
                        "clientId": {
                          "type": "string"
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "ratingStars": {
                          "type": "integer"
                        },
                        "reviewText": {
                          "type": "string"
                        },
                        "reviewerId": {
                          "type": "string"
                        },
                        "bookingId": {
                          "type": "string"
                        },
                        "direction": {
                          "type": "string",
                          "enum": ["CLIENT_TO_SUPPLIER", "SUPPLIER_TO_CLIENT"]
                        },
                        "subjectType": {
                          "type": "string",
                          "enum": ["SUPPLIER", "CLIENT"]
                        },
                        "subjectId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "supplierName": {
                          "type": "string"
                        },
                        "clientName": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "reviewId",
                        "supplierId",
                        "projectId",
                        "ratingStars",
                        "direction",
                        "subjectType",
                        "subjectId",
                        "createdAt"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Booking not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "This side has already reviewed this booking",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "422": {
            "description": "Booking is cancelled, or has no supplier to review",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": ["Reviews"],
        "summary": "List every review linked to a booking",
        "description": "Every review linked to this booking, newest first, in both directions and unpaginated.\n\nDo not assume at most two. The strict `POST /bookings/{bookingId}/reviews` route allows one review per direction, but the older project-level `POST /reviews` accepts a `bookingId` without deduplicating, so a booking created through that path can carry several client→supplier reviews. Read the list, do not index into it.\n\nEach review carries best-effort `supplierName` / `clientName` resolved from the two profiles, so a hosted review page renders without further calls; a counterparty that cannot be resolved keeps its bare id and those fields are absent. No email address is returned for either party. An unknown booking returns 404, matching the POST.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Reviews for the booking",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "reviewId": {
                            "type": "string"
                          },
                          "supplierId": {
                            "type": "string"
                          },
                          "clientId": {
                            "type": "string"
                          },
                          "projectId": {
                            "type": "string"
                          },
                          "ratingStars": {
                            "type": "integer"
                          },
                          "reviewText": {
                            "type": "string"
                          },
                          "reviewerId": {
                            "type": "string"
                          },
                          "bookingId": {
                            "type": "string"
                          },
                          "direction": {
                            "type": "string",
                            "enum": ["CLIENT_TO_SUPPLIER", "SUPPLIER_TO_CLIENT"]
                          },
                          "subjectType": {
                            "type": "string",
                            "enum": ["SUPPLIER", "CLIENT"]
                          },
                          "subjectId": {
                            "type": "string"
                          },
                          "createdAt": {
                            "type": "string"
                          },
                          "supplierName": {
                            "type": "string"
                          },
                          "clientName": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "reviewId",
                          "supplierId",
                          "projectId",
                          "ratingStars",
                          "direction",
                          "subjectType",
                          "subjectId",
                          "createdAt"
                        ]
                      }
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Booking not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/bookings/{bookingId}/reports": {
      "post": {
        "tags": ["Bookings"],
        "summary": "File one side's report on a booking",
        "description": "Records one side of a booking reporting on it — today, whether they showed up. A booking carries at most two reports, one per side, identified by `(bookingId, reporterRole)`; there is no report id.\n\n**`attended` is a self-report.** A `CLIENT` report says the client attended; a `SUPPLIER` report says the supplier attended. Neither says anything whatsoever about the other party, so a supplier cannot mark a client as a no-show through this endpoint. `reporterId` is read off the booking (`CLIENT` → the booking's client, `SUPPLIER` → the booking's supplier) and is not accepted in the body, so a caller cannot file a report as somebody else.\n\n**Resubmitting is safe.** This endpoint gets double-clicked from an email, so filing the same answer twice is a no-op rather than an error:\n\n- nothing on file yet → **201** with the newly written report\n- identical to what is on file → **200** with the **stored** report\n- contradicts what is on file → **409** `REPORT_ALREADY_EXISTS`, naming the stored values\n\n**`note` is not part of the claim.** The assertion a report makes is `reportType` + `attended`. Resubmitting those unchanged but with different text therefore returns 200 with the record as stored, including the ORIGINAL note — the new text is discarded, not merged. There is no route that edits a filed report.\n\n**A report does what the same answer does in the dashboard.** It is filed through the one attendance-report path every door uses: a `SUPPLIER` report settles the booking (attended → `COMPLETED`, or `DISPUTED` when the client has reported that they did not attend; did not attend → `SUPPLIER_NO_SHOW`), and a `CLIENT` \"did not attend\" on a completed booking inside the dispute window opens a dispute. A report can be filed once the session has ended. Before that, on a CANCELLED booking, or a `SUPPLIER` report on a booking already settled, is **422** `BOOKING_NOT_REPORTABLE`, with nothing written. A `SUPPLIER` report against a booking with no supplier assigned is also 422, since there is nobody to attribute it to; a `CLIENT` report on the same booking is fine.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Report data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reporterRole": {
                    "type": "string",
                    "enum": ["CLIENT", "SUPPLIER"],
                    "description": "Which side of the booking is filing this report.",
                    "example": "SUPPLIER"
                  },
                  "reportType": {
                    "type": "string",
                    "enum": ["ATTENDANCE"],
                    "default": "ATTENDANCE",
                    "description": "What the report is about. Defaults to ATTENDANCE, the only type today.",
                    "example": "ATTENDANCE"
                  },
                  "attended": {
                    "type": "boolean",
                    "description": "Whether the reporting side attended the booking. This is a self-report — the client confirms the client attended, the supplier confirms the supplier attended. Stored explicitly so \"I did not attend\" is a first-class answer.",
                    "example": true
                  },
                  "note": {
                    "type": "string",
                    "maxLength": 1000,
                    "description": "Optional free-text detail, up to 1000 characters.",
                    "example": "Arrived 10 minutes late but stayed for the full session."
                  }
                },
                "required": ["reporterRole", "attended"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Identical report already on file (no-op)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/BookingReport"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "201": {
            "description": "Report filed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/BookingReport"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Booking not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "A different report from this side is already on file",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "422": {
            "description": "The booking cannot be reported on now — not ended yet, cancelled, or (a SUPPLIER report) already settled (BOOKING_NOT_REPORTABLE) — or has no supplier to report as",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": ["Bookings"],
        "summary": "List the reports filed on a booking",
        "description": "Both sides' reports on this booking — at most two, one per `reporterRole`, unpaginated. A side that has not filed is simply absent, which is not the same as a filed report saying `attended: false`; only an explicit row means \"I did not attend\". Also included in `GET /bookings/{bookingId}/aggregate`, so prefer that when you need the booking and its reports together. An unknown booking returns 404.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The booking — one scheduled unit of service occupying supplier time.",
              "example": "bk_01kv7q41n2hbqxwm03ymn7bxl9"
            },
            "required": true,
            "description": "The booking — one scheduled unit of service occupying supplier time.",
            "name": "bookingId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Reports on the booking",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BookingReport"
                      }
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Booking not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/orders": {
      "post": {
        "tags": ["Orders"],
        "summary": "Create a new order",
        "description": "Creates an order (a cart/purchase record). For a package, add an item with { skuType: \"PACKAGE\", packageId } — the server derives service, offering, session count (creditCount), price and expiry from the package. For a single session use { skuType: \"SINGLE_SESSION\", serviceId, offeringId, quantity }. The order item is the credit ledger: its quantityRemaining is what bookings draw down. Currency is fixed at creation.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Order data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "clientId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The client placing the order.",
                    "example": "cli_01kv8p20m1gnqvxl92xln6awk8"
                  },
                  "currency": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 3,
                    "description": "ISO 4217 currency you quoted the buyer. Verified against the price the server resolves for this order's region; a mismatch is a 400.",
                    "example": "CAD"
                  },
                  "locale": {
                    "type": "string",
                    "description": "The locale your buyer completed this purchase in — typically the language segment of your storefront URL. Normalized to canonical BCP-47 on write, so `en-us` is stored as `en-US`. It is copied onto every booking this order funds and saved as the client's default locale.",
                    "example": "en-US"
                  },
                  "attribution": {
                    "type": "object",
                    "properties": {
                      "searchId": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128,
                        "description": "The `searchId` of the MarketBox search response the buyer booked from — the `X-MB-Search-Id` header / body field of every search route. Stored as given; a value MarketBox never issued is kept but not trusted.",
                        "example": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
                      },
                      "sessionKey": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 64,
                        "description": "The same opaque per-session key you send with site events, at most 64 characters. Never an email, IP or user id.",
                        "example": "sess-example-01"
                      },
                      "surface": {
                        "type": "string",
                        "enum": [
                          "home",
                          "results",
                          "listing",
                          "site_search",
                          "profile",
                          "widget",
                          "assistant",
                          "other"
                        ],
                        "description": "Where on your site the buyer started the purchase.",
                        "example": "results"
                      }
                    },
                    "additionalProperties": false,
                    "description": "Which search and site session this purchase came from: the `searchId` of the search response the buyer booked from, your opaque `sessionKey`, and the `surface` the list was drawn on. Optional. Stored as given and copied onto every booking this order funds; holds and the booking routes never take one of their own. A `searchId` MarketBox never issued is kept but not counted.",
                    "example": {
                      "searchId": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n",
                      "sessionKey": "sess-example-01",
                      "surface": "results"
                    }
                  },
                  "reservationId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The hold this order funds. Preferred: the hold already knows where the booking happens, so the order and its bookings cannot disagree on price.",
                    "example": "resv_01kx16f0a1c7b2sd91xzq3mn5p"
                  },
                  "locationId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Stored Location for a PHYSICAL booking. Ignored when reservationId is given."
                  },
                  "address": {
                    "type": "object",
                    "properties": {
                      "addressOneLine": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The whole address on one line, as a person would write it.",
                        "example": "10 Main St, Toronto, ON M5V 1A1, Canada"
                      },
                      "streetNumber": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The street number.",
                        "example": "10"
                      },
                      "streetName": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The street name.",
                        "example": "Main St"
                      },
                      "city": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The city or town.",
                        "example": "Toronto"
                      },
                      "state": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The state, province or region; an ISO 3166-2 code when one matches.",
                        "example": "ON"
                      },
                      "country": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The country; ISO 3166-1 alpha-2, alpha-3 or the English name.",
                        "example": "CA"
                      },
                      "zipCode": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The postal or ZIP code, in any national format.",
                        "example": "M5V 1A1"
                      },
                      "unitNumber": {
                        "type": "string",
                        "nullable": true,
                        "description": "The unit, suite or apartment, if any.",
                        "example": "4B"
                      }
                    },
                    "required": [
                      "addressOneLine",
                      "streetNumber",
                      "streetName",
                      "city",
                      "state",
                      "country",
                      "zipCode"
                    ],
                    "description": "Service address for a TRAVEL_ZONE (in-home) booking. Ignored when reservationId or locationId is given."
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "skuType": {
                          "type": "string",
                          "enum": [
                            "SINGLE_SESSION",
                            "PACKAGE",
                            "SUBSCRIPTION",
                            "MEMBERSHIP",
                            "DEPOSIT"
                          ],
                          "description": "What kind of line this is: SINGLE_SESSION, PACKAGE, SUBSCRIPTION, MEMBERSHIP, or DEPOSIT.",
                          "example": "PACKAGE"
                        },
                        "packageId": {
                          "type": "string",
                          "minLength": 1,
                          "description": "Required for PACKAGE items. serviceId, offeringId, session count, price and expiry are all derived from the package.",
                          "example": "pkg_01kv7n10k0fnptwk81wkm59vj7"
                        },
                        "serviceId": {
                          "type": "string",
                          "minLength": 1,
                          "description": "Required for SINGLE_SESSION items.",
                          "example": "srv_01kv60qg12e82acr78edfnjhvv"
                        },
                        "offeringId": {
                          "type": "string",
                          "minLength": 1,
                          "description": "Required for SINGLE_SESSION items.",
                          "example": "off_01kv60qge5eh59ap0gw0pqrrys"
                        },
                        "quantity": {
                          "type": "integer",
                          "minimum": 1,
                          "description": "Units to purchase (SINGLE_SESSION).",
                          "example": 1
                        }
                      },
                      "required": ["skuType"]
                    },
                    "default": [],
                    "description": "Line items to purchase."
                  }
                },
                "required": ["clientId", "currency"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Order created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "order": {
                          "$ref": "#/components/schemas/Order"
                        },
                        "items": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/OrderItem"
                          }
                        },
                        "summary": {
                          "type": "object",
                          "properties": {
                            "currency": {
                              "type": "string"
                            },
                            "lines": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "orderItemId": {
                                    "type": "string"
                                  },
                                  "label": {
                                    "type": "object",
                                    "nullable": true,
                                    "additionalProperties": {
                                      "type": "string"
                                    }
                                  },
                                  "skuType": {
                                    "type": "string",
                                    "enum": [
                                      "SINGLE_SESSION",
                                      "PACKAGE",
                                      "SUBSCRIPTION",
                                      "MEMBERSHIP",
                                      "DEPOSIT"
                                    ]
                                  },
                                  "quantity": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "unitPrice": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "lineTotal": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "tax": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "taxable": {
                                    "type": "boolean"
                                  },
                                  "priceRuleId": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "Which regional price rule this line resolved to. Compare against the offering/package `pricing[]` to see exactly which price was applied."
                                  },
                                  "priceScope": {
                                    "type": "string",
                                    "nullable": true,
                                    "enum": [
                                      "DEFAULT",
                                      "COUNTRY",
                                      "STATE",
                                      "POSTAL",
                                      null
                                    ],
                                    "description": "Specificity of the matched rule: DEFAULT, COUNTRY, STATE or POSTAL. DEFAULT means no regional rule matched and the fallback price was used."
                                  }
                                },
                                "required": [
                                  "orderItemId",
                                  "label",
                                  "skuType",
                                  "quantity",
                                  "unitPrice",
                                  "lineTotal",
                                  "tax",
                                  "taxable"
                                ]
                              }
                            },
                            "fees": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "feeId": {
                                    "type": "string",
                                    "description": "The fee as configured on the business model."
                                  },
                                  "businessModelId": {
                                    "type": "string",
                                    "description": "The business model that levied this fee — the commercial definition the charge belongs to."
                                  },
                                  "name": {
                                    "type": "object",
                                    "additionalProperties": {
                                      "type": "string"
                                    },
                                    "description": "Buyer-facing label, snapshotted at purchase time."
                                  },
                                  "calculation": {
                                    "type": "string",
                                    "enum": ["FLAT", "PERCENT"],
                                    "description": "How a service fee is calculated. FLAT charges a fixed amount; PERCENT charges a percentage of the pre-tax total of the lines the fee governs."
                                  },
                                  "percentage": {
                                    "type": "number",
                                    "nullable": true,
                                    "description": "Echoed for PERCENT fees so the buyer can be shown the rate that applied (e.g. \"Admin fee (5%)\"). Absent for FLAT fees."
                                  },
                                  "basis": {
                                    "type": "object",
                                    "properties": {
                                      "amount": {
                                        "type": "integer",
                                        "minimum": 0
                                      },
                                      "currency": {
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 3
                                      }
                                    },
                                    "required": ["amount", "currency"],
                                    "description": "Pre-tax total of this business model's lines — what a PERCENT fee was calculated against. Reported for FLAT fees too, so the figure is auditable."
                                  },
                                  "amount": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "tax": {
                                    "type": "object",
                                    "properties": {
                                      "amount": {
                                        "type": "integer",
                                        "minimum": 0
                                      },
                                      "currency": {
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 3
                                      }
                                    },
                                    "required": ["amount", "currency"],
                                    "description": "Tax on this fee, at the rate of its governing lines that are taxed at a positive rate. Zero when the fee is not taxable, or when none of those lines is taxed (each untaxed line says why in its taxExemptReason)."
                                  },
                                  "taxable": {
                                    "type": "boolean"
                                  }
                                },
                                "required": [
                                  "feeId",
                                  "businessModelId",
                                  "name",
                                  "calculation",
                                  "basis",
                                  "amount",
                                  "tax",
                                  "taxable"
                                ]
                              },
                              "description": "Service fees levied by the business models on this order. Each is a discrete charge in its own right. The fee amounts are NOT in `subtotal` or `taxTotal`, but tax charged on a fee IS added to `taxTotal`. Applied once per fee however many lines it governs."
                            },
                            "feeTotal": {
                              "type": "object",
                              "properties": {
                                "amount": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "currency": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 3
                                }
                              },
                              "required": ["amount", "currency"],
                              "description": "Sum of `fees[].amount`. Sits outside `subtotal`, so `total = subtotal + feeTotal + taxTotal`."
                            },
                            "subtotal": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "taxTotal": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "total": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "amountPaid": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "amountRefunded": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "amountDue": {
                              "$ref": "#/components/schemas/Money"
                            }
                          },
                          "required": [
                            "currency",
                            "lines",
                            "fees",
                            "feeTotal",
                            "subtotal",
                            "taxTotal",
                            "total",
                            "amountPaid",
                            "amountRefunded",
                            "amountDue"
                          ]
                        }
                      },
                      "required": ["order", "items", "summary"]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Client, offering, project, reservation, or location not found (including a caller-supplied clientId/reservationId/locationId that does not resolve in this project)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "422": {
            "description": "The service has no active rate of the kind the line implies, e.g. a SINGLE_SESSION line on a service with no active SINGLE_BOOKING rate (SERVICE_NOT_SOLD_AS); a line names a service that is not LIVE or was deleted, or an offering that is not ACTIVE (NOT_SELLABLE); or a PACKAGE line names a DRAFT or ARCHIVED package (PACKAGE_NOT_ACTIVE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": ["Orders"],
        "summary": "List orders by status, by payment method, or every order in a date range",
        "description": "Exactly one listing mode per request, chosen by which filter you send:\n\n- `status` — orders in that status, narrowed by `startCreatedAt`/`endCreatedAt`.\n- `paymentMethod` — how orders were settled (`STRIPE`, `CASH`, `EXTERNAL`, `COMP`, `MIXED`, `LEGACY`), narrowed by `startSettledAt`/`endSettledAt`. This is the reconciliation read: \"what did we take in cash last month\".\n- neither — every order, narrowed by `startCreatedAt`/`endCreatedAt`.\n\nSending both `status` and `paymentMethod` is a 400, as is a date range belonging to the other mode (`startSettledAt` without `paymentMethod`, or `startCreatedAt` with it) — each index carries only one date, so the pairing is not a preference.\n\n⚠️ The no-filter mode reads an index whose key attributes are written only when an order is created, so every order created before this feature shipped, and every order migrated from MarketBox v1, is MISSING from it until a backfill runs. An empty or short page there does not mean the project has no orders — list by `status` when you need completeness over historical data.\n\nPaginate with `limit` and `cursor`; `nextCursor: null` is the last page. A cursor belongs to the filter set that minted it — replaying one after switching listing mode is rejected with a 400 `BAD_REQUEST` (\"Invalid cursor\") rather than silently returning the wrong page, so start a fresh request instead. To list one client's orders, use `GET /projects/{projectId}/clients/{clientId}/orders`.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "enum": ["DRAFT", "PENDING", "PAID", "CANCELLED"],
              "description": "List only orders in this status. Mutually exclusive with `paymentMethod`; with neither, every order in the created-date window is listed.",
              "example": "PAID"
            },
            "required": false,
            "description": "List only orders in this status. Mutually exclusive with `paymentMethod`; with neither, every order in the created-date window is listed.",
            "name": "status",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": ["STRIPE", "CASH", "EXTERNAL", "COMP", "MIXED", "LEGACY"],
              "description": "List by how the order was settled. This mode reads a settled-date index, so pair it with `startSettledAt`/`endSettledAt` and never with the created-date parameters. Only settled orders carry a payment method, so DRAFT and PENDING orders never appear in this mode; a settled order later CANCELLED (refunded or not) still does, with its `status`. Mutually exclusive with `status`.",
              "example": "CASH"
            },
            "required": false,
            "description": "List by how the order was settled. This mode reads a settled-date index, so pair it with `startSettledAt`/`endSettledAt` and never with the created-date parameters. Only settled orders carry a payment method, so DRAFT and PENDING orders never appear in this mode; a settled order later CANCELLED (refunded or not) still does, with its `status`. Mutually exclusive with `status`.",
            "name": "paymentMethod",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time",
              "description": "Inclusive lower bound on `createdAt`, as an ISO 8601 instant. Valid in the `status` and no-filter modes only.",
              "example": "2026-09-01T00:00:00.000Z"
            },
            "required": false,
            "description": "Inclusive lower bound on `createdAt`, as an ISO 8601 instant. Valid in the `status` and no-filter modes only.",
            "name": "startCreatedAt",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time",
              "description": "Upper bound on `createdAt`, as an ISO 8601 instant, EXCLUSIVE of the instant itself — pass the next period's start to cover a whole day or month. Valid in the `status` and no-filter modes only.",
              "example": "2026-10-01T00:00:00.000Z"
            },
            "required": false,
            "description": "Upper bound on `createdAt`, as an ISO 8601 instant, EXCLUSIVE of the instant itself — pass the next period's start to cover a whole day or month. Valid in the `status` and no-filter modes only.",
            "name": "endCreatedAt",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time",
              "description": "Inclusive lower bound on `settledAt`, as an ISO 8601 instant. Requires `paymentMethod`.",
              "example": "2026-09-01T00:00:00.000Z"
            },
            "required": false,
            "description": "Inclusive lower bound on `settledAt`, as an ISO 8601 instant. Requires `paymentMethod`.",
            "name": "startSettledAt",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time",
              "description": "Upper bound on `settledAt`, as an ISO 8601 instant, EXCLUSIVE of the instant itself — pass the next period's start to cover a whole day or month. Requires `paymentMethod`.",
              "example": "2026-10-01T00:00:00.000Z"
            },
            "required": false,
            "description": "Upper bound on `settledAt`, as an ISO 8601 instant, EXCLUSIVE of the instant itself — pass the next period's start to cover a whole day or month. Requires `paymentMethod`.",
            "name": "endSettledAt",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50,
              "description": "Maximum rows to return in `data`, 1–200. Defaults to 50. Values outside the range return 400. A page can still hold fewer rows than requested, so treat `nextCursor: null` as the only end-of-results signal and never stop on a page that merely looks short.",
              "example": 50
            },
            "required": false,
            "description": "Maximum rows to return in `data`, 1–200. Defaults to 50. Values outside the range return 400. A page can still hold fewer rows than requested, so treat `nextCursor: null` as the only end-of-results signal and never stop on a page that merely looks short.",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Opaque pagination token from a previous response's `nextCursor`. Treat it as a magic string — never parse or construct one. A cursor is only valid for the same filters that produced it, and `nextCursor: null` means the last page."
            },
            "required": false,
            "description": "Opaque pagination token from a previous response's `nextCursor`. Treat it as a magic string — never parse or construct one. A cursor is only valid for the same filters that produced it, and `nextCursor: null` means the last page.",
            "name": "cursor",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Orders list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Order"
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": ["data", "nextCursor"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid cursor or limit; both status and paymentMethod; or a date range paired with the wrong listing mode",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/orders/{orderId}": {
      "get": {
        "tags": ["Orders"],
        "summary": "Get an order by ID",
        "description": "Returns the order header only — totals, currency, status and the `pricingRegion` it resolved at create time. It does NOT include line items; use the `/aggregate` variant when you need the items too, rather than calling this and then listing items separately.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The order — the commercial record. Order items are drawn down into bookings.",
              "example": "ord_01kv8m92p4jcrywn14znp8cym0"
            },
            "required": true,
            "description": "The order — the commercial record. Order items are drawn down into bookings.",
            "name": "orderId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Order",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Order"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": ["Orders"],
        "summary": "Update an order",
        "description": "Deliberately narrow, and tax is not editable: the platform computes it — line tax plus tax on taxable service fees — when the order is created and whenever its lines change. `tax` is still accepted for compatibility, but only when it equals both the computed and the stored figure, i.e. when it changes nothing; any other figure returns 400 TAX_MISMATCH naming both. Omit it. Currency is fixed at creation and totals derive from the line items, so neither is editable here — that is what stops an order and its items disagreeing about money. Change the line items to change the total, and use `POST /status` to move the order through its lifecycle. Returns 409 if the order changed underneath you.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The order — the commercial record. Order items are drawn down into bookings.",
              "example": "ord_01kv8m92p4jcrywn14znp8cym0"
            },
            "required": true,
            "description": "The order — the commercial record. Order items are drawn down into bookings.",
            "name": "orderId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Order update",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tax": {
                    "$ref": "#/components/schemas/Money"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated order",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Order"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error, or TAX_MISMATCH: the tax sent is not both the computed and the stored figure, or the order has lines in a different currency than the order itself",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Order not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "Version conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Orders"],
        "summary": "Soft-delete an order",
        "description": "Marks the order deleted and hides it from list endpoints. The record is retained rather than destroyed, so financial history stays auditable. This is not the same as cancelling: use `POST /status` with `CANCELLED` to record that a real order was called off, and reserve delete for orders raised in error. Delete refuses a real order with 409 `ORDER_NOT_DELETABLE`: one holding a booking (booked or already delivered) or a pending or succeeded payment or refund. A deleted order is also cancelled, and any booking that reached it after that check is cancelled without notifying anyone. Returns 204 with no body.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The order — the commercial record. Order items are drawn down into bookings.",
              "example": "ord_01kv8m92p4jcrywn14znp8cym0"
            },
            "required": true,
            "description": "The order — the commercial record. Order items are drawn down into bookings.",
            "name": "orderId",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Order deleted"
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Order not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "VERSION_CONFLICT, or ORDER_NOT_DELETABLE: the order holds a booking or money, so cancel it instead",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/orders/{orderId}/aggregate": {
      "get": {
        "tags": ["Orders"],
        "summary": "Get an order with its items",
        "description": "The order header plus every line item in one call — the shape to use when rendering a receipt or reconciling what was charged. Each item carries `priceRuleId` and `priceScope`, so you can prove which regional price rule produced its amount: `priceScope: \"DEFAULT\"` where you expected a regional price means the order resolved no region. Prefer this over a GET on the order followed by a separate item fetch.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The order — the commercial record. Order items are drawn down into bookings.",
              "example": "ord_01kv8m92p4jcrywn14znp8cym0"
            },
            "required": true,
            "description": "The order — the commercial record. Order items are drawn down into bookings.",
            "name": "orderId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Order aggregate",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "order": {
                          "$ref": "#/components/schemas/Order"
                        },
                        "items": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/OrderItem"
                          }
                        },
                        "summary": {
                          "type": "object",
                          "properties": {
                            "currency": {
                              "type": "string"
                            },
                            "lines": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "orderItemId": {
                                    "type": "string"
                                  },
                                  "label": {
                                    "type": "object",
                                    "nullable": true,
                                    "additionalProperties": {
                                      "type": "string"
                                    }
                                  },
                                  "skuType": {
                                    "type": "string",
                                    "enum": [
                                      "SINGLE_SESSION",
                                      "PACKAGE",
                                      "SUBSCRIPTION",
                                      "MEMBERSHIP",
                                      "DEPOSIT"
                                    ]
                                  },
                                  "quantity": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "unitPrice": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "lineTotal": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "tax": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "taxable": {
                                    "type": "boolean"
                                  },
                                  "priceRuleId": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "Which regional price rule this line resolved to. Compare against the offering/package `pricing[]` to see exactly which price was applied."
                                  },
                                  "priceScope": {
                                    "type": "string",
                                    "nullable": true,
                                    "enum": [
                                      "DEFAULT",
                                      "COUNTRY",
                                      "STATE",
                                      "POSTAL",
                                      null
                                    ],
                                    "description": "Specificity of the matched rule: DEFAULT, COUNTRY, STATE or POSTAL. DEFAULT means no regional rule matched and the fallback price was used."
                                  }
                                },
                                "required": [
                                  "orderItemId",
                                  "label",
                                  "skuType",
                                  "quantity",
                                  "unitPrice",
                                  "lineTotal",
                                  "tax",
                                  "taxable"
                                ]
                              }
                            },
                            "fees": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "feeId": {
                                    "type": "string",
                                    "description": "The fee as configured on the business model."
                                  },
                                  "businessModelId": {
                                    "type": "string",
                                    "description": "The business model that levied this fee — the commercial definition the charge belongs to."
                                  },
                                  "name": {
                                    "type": "object",
                                    "additionalProperties": {
                                      "type": "string"
                                    },
                                    "description": "Buyer-facing label, snapshotted at purchase time."
                                  },
                                  "calculation": {
                                    "type": "string",
                                    "enum": ["FLAT", "PERCENT"],
                                    "description": "How a service fee is calculated. FLAT charges a fixed amount; PERCENT charges a percentage of the pre-tax total of the lines the fee governs."
                                  },
                                  "percentage": {
                                    "type": "number",
                                    "nullable": true,
                                    "description": "Echoed for PERCENT fees so the buyer can be shown the rate that applied (e.g. \"Admin fee (5%)\"). Absent for FLAT fees."
                                  },
                                  "basis": {
                                    "type": "object",
                                    "properties": {
                                      "amount": {
                                        "type": "integer",
                                        "minimum": 0
                                      },
                                      "currency": {
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 3
                                      }
                                    },
                                    "required": ["amount", "currency"],
                                    "description": "Pre-tax total of this business model's lines — what a PERCENT fee was calculated against. Reported for FLAT fees too, so the figure is auditable."
                                  },
                                  "amount": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "tax": {
                                    "type": "object",
                                    "properties": {
                                      "amount": {
                                        "type": "integer",
                                        "minimum": 0
                                      },
                                      "currency": {
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 3
                                      }
                                    },
                                    "required": ["amount", "currency"],
                                    "description": "Tax on this fee, at the rate of its governing lines that are taxed at a positive rate. Zero when the fee is not taxable, or when none of those lines is taxed (each untaxed line says why in its taxExemptReason)."
                                  },
                                  "taxable": {
                                    "type": "boolean"
                                  }
                                },
                                "required": [
                                  "feeId",
                                  "businessModelId",
                                  "name",
                                  "calculation",
                                  "basis",
                                  "amount",
                                  "tax",
                                  "taxable"
                                ]
                              },
                              "description": "Service fees levied by the business models on this order. Each is a discrete charge in its own right. The fee amounts are NOT in `subtotal` or `taxTotal`, but tax charged on a fee IS added to `taxTotal`. Applied once per fee however many lines it governs."
                            },
                            "feeTotal": {
                              "type": "object",
                              "properties": {
                                "amount": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "currency": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 3
                                }
                              },
                              "required": ["amount", "currency"],
                              "description": "Sum of `fees[].amount`. Sits outside `subtotal`, so `total = subtotal + feeTotal + taxTotal`."
                            },
                            "subtotal": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "taxTotal": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "total": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "amountPaid": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "amountRefunded": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "amountDue": {
                              "$ref": "#/components/schemas/Money"
                            }
                          },
                          "required": [
                            "currency",
                            "lines",
                            "fees",
                            "feeTotal",
                            "subtotal",
                            "taxTotal",
                            "total",
                            "amountPaid",
                            "amountRefunded",
                            "amountDue"
                          ]
                        }
                      },
                      "required": ["order", "items", "summary"]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/clients/{clientId}/orders": {
      "get": {
        "tags": ["Orders"],
        "summary": "List orders for a client",
        "description": "Every order belonging to one client, newest first, across all statuses — unlike the project-level list, no `status` is required. This is the call behind a client's order history.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The client — the person the booking is for.",
              "example": "cli_01kv6r83j9fmquwl81xkm5bwj6"
            },
            "required": true,
            "description": "The client — the person the booking is for.",
            "name": "clientId",
            "in": "path"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50,
              "description": "Maximum rows to return in `data`, 1–200. Defaults to 50. Values outside the range return 400. A page can still hold fewer rows than requested, so treat `nextCursor: null` as the only end-of-results signal and never stop on a page that merely looks short.",
              "example": 50
            },
            "required": false,
            "description": "Maximum rows to return in `data`, 1–200. Defaults to 50. Values outside the range return 400. A page can still hold fewer rows than requested, so treat `nextCursor: null` as the only end-of-results signal and never stop on a page that merely looks short.",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Opaque pagination token from a previous response's `nextCursor`. Treat it as a magic string — never parse or construct one. A cursor is only valid for the same filters that produced it, and `nextCursor: null` means the last page."
            },
            "required": false,
            "description": "Opaque pagination token from a previous response's `nextCursor`. Treat it as a magic string — never parse or construct one. A cursor is only valid for the same filters that produced it, and `nextCursor: null` means the last page.",
            "name": "cursor",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Orders list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Order"
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": ["data", "nextCursor"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid cursor or limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/orders/{orderId}/status": {
      "post": {
        "tags": ["Orders"],
        "summary": "Change order status",
        "description": "Moves the order through its lifecycle. Only these transitions are allowed, and anything else is a 400:\n\n- `DRAFT` -\u003E `PENDING`, `CANCELLED`\n- `PENDING` -\u003E `CANCELLED`, `DRAFT`\n- `PAID` -\u003E `CANCELLED`\n- `CANCELLED` -\u003E nothing. Cancellation is terminal; a cancelled order cannot be revived, so issue a new one instead.\n\n`PAID` cannot be requested: an order becomes PAID when its ledger covers its total (`POST /projects/{projectId}/orders/{orderId}/transactions` for cash, external or comp; the payment-intent flow for cards). Asking for it is a 409 `ORDER_NOT_SETTLED` — record the payment instead of retrying.\n\nPass `cancellationReason` when moving to `CANCELLED` — it is recorded with the caller as `cancelledBy` and ignored for every other target status. A 409 `VERSION_CONFLICT` means the order changed underneath you.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The order — the commercial record. Order items are drawn down into bookings.",
              "example": "ord_01kv8m92p4jcrywn14znp8cym0"
            },
            "required": true,
            "description": "The order — the commercial record. Order items are drawn down into bookings.",
            "name": "orderId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Status change",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": ["DRAFT", "PENDING", "PAID", "CANCELLED"]
                  },
                  "cancellationReason": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Required when status is CANCELLED; omitting it then is a 400. Why the order was cancelled."
                  }
                },
                "required": ["status"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated order",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Order"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid transition or validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Order not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "Version conflict (VERSION_CONFLICT), or a `PAID` target (ORDER_NOT_SETTLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/orders/{orderId}/items": {
      "post": {
        "tags": ["Orders"],
        "summary": "Add an item to an order",
        "description": "Adds a line and returns the whole order with its items, so you never need a follow-up read to get the new total. You do not send a price: the server resolves it from the offering against the order's `pricingRegion`, which is what keeps the charge honest. A line whose resolved currency differs from the order's is rejected with 400 rather than silently converted — if you hit that, the order resolved a different region than you expected, so check `priceScope` on the existing items. A PACKAGE line cannot be added here (400 `VALIDATION_ERROR`): packages are bought when the order is created, by `packageId` in `POST /orders`.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The order — the commercial record. Order items are drawn down into bookings.",
              "example": "ord_01kv8m92p4jcrywn14znp8cym0"
            },
            "required": true,
            "description": "The order — the commercial record. Order items are drawn down into bookings.",
            "name": "orderId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Item data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "skuType": {
                    "type": "string",
                    "enum": [
                      "SINGLE_SESSION",
                      "SUBSCRIPTION",
                      "MEMBERSHIP",
                      "DEPOSIT"
                    ],
                    "description": "What kind of line this is. PACKAGE is not accepted here: a package is bought when the order is created, by packageId."
                  },
                  "serviceId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
                    "example": "srv_01kv60qg12e82acr78edfnjhvv"
                  },
                  "offeringId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The offering — one bookable variant of a service, carrying its own duration and regional pricing rules.",
                    "example": "off_01kv60qge5eh59ap0gw0pqrrys"
                  },
                  "quantity": {
                    "type": "integer",
                    "minimum": 1
                  }
                },
                "required": ["skuType", "serviceId", "offeringId", "quantity"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Item added",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "order": {
                          "$ref": "#/components/schemas/Order"
                        },
                        "items": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/OrderItem"
                          }
                        },
                        "summary": {
                          "type": "object",
                          "properties": {
                            "currency": {
                              "type": "string"
                            },
                            "lines": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "orderItemId": {
                                    "type": "string"
                                  },
                                  "label": {
                                    "type": "object",
                                    "nullable": true,
                                    "additionalProperties": {
                                      "type": "string"
                                    }
                                  },
                                  "skuType": {
                                    "type": "string",
                                    "enum": [
                                      "SINGLE_SESSION",
                                      "PACKAGE",
                                      "SUBSCRIPTION",
                                      "MEMBERSHIP",
                                      "DEPOSIT"
                                    ]
                                  },
                                  "quantity": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "unitPrice": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "lineTotal": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "tax": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "taxable": {
                                    "type": "boolean"
                                  },
                                  "priceRuleId": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "Which regional price rule this line resolved to. Compare against the offering/package `pricing[]` to see exactly which price was applied."
                                  },
                                  "priceScope": {
                                    "type": "string",
                                    "nullable": true,
                                    "enum": [
                                      "DEFAULT",
                                      "COUNTRY",
                                      "STATE",
                                      "POSTAL",
                                      null
                                    ],
                                    "description": "Specificity of the matched rule: DEFAULT, COUNTRY, STATE or POSTAL. DEFAULT means no regional rule matched and the fallback price was used."
                                  }
                                },
                                "required": [
                                  "orderItemId",
                                  "label",
                                  "skuType",
                                  "quantity",
                                  "unitPrice",
                                  "lineTotal",
                                  "tax",
                                  "taxable"
                                ]
                              }
                            },
                            "fees": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "feeId": {
                                    "type": "string",
                                    "description": "The fee as configured on the business model."
                                  },
                                  "businessModelId": {
                                    "type": "string",
                                    "description": "The business model that levied this fee — the commercial definition the charge belongs to."
                                  },
                                  "name": {
                                    "type": "object",
                                    "additionalProperties": {
                                      "type": "string"
                                    },
                                    "description": "Buyer-facing label, snapshotted at purchase time."
                                  },
                                  "calculation": {
                                    "type": "string",
                                    "enum": ["FLAT", "PERCENT"],
                                    "description": "How a service fee is calculated. FLAT charges a fixed amount; PERCENT charges a percentage of the pre-tax total of the lines the fee governs."
                                  },
                                  "percentage": {
                                    "type": "number",
                                    "nullable": true,
                                    "description": "Echoed for PERCENT fees so the buyer can be shown the rate that applied (e.g. \"Admin fee (5%)\"). Absent for FLAT fees."
                                  },
                                  "basis": {
                                    "type": "object",
                                    "properties": {
                                      "amount": {
                                        "type": "integer",
                                        "minimum": 0
                                      },
                                      "currency": {
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 3
                                      }
                                    },
                                    "required": ["amount", "currency"],
                                    "description": "Pre-tax total of this business model's lines — what a PERCENT fee was calculated against. Reported for FLAT fees too, so the figure is auditable."
                                  },
                                  "amount": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "tax": {
                                    "type": "object",
                                    "properties": {
                                      "amount": {
                                        "type": "integer",
                                        "minimum": 0
                                      },
                                      "currency": {
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 3
                                      }
                                    },
                                    "required": ["amount", "currency"],
                                    "description": "Tax on this fee, at the rate of its governing lines that are taxed at a positive rate. Zero when the fee is not taxable, or when none of those lines is taxed (each untaxed line says why in its taxExemptReason)."
                                  },
                                  "taxable": {
                                    "type": "boolean"
                                  }
                                },
                                "required": [
                                  "feeId",
                                  "businessModelId",
                                  "name",
                                  "calculation",
                                  "basis",
                                  "amount",
                                  "tax",
                                  "taxable"
                                ]
                              },
                              "description": "Service fees levied by the business models on this order. Each is a discrete charge in its own right. The fee amounts are NOT in `subtotal` or `taxTotal`, but tax charged on a fee IS added to `taxTotal`. Applied once per fee however many lines it governs."
                            },
                            "feeTotal": {
                              "type": "object",
                              "properties": {
                                "amount": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "currency": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 3
                                }
                              },
                              "required": ["amount", "currency"],
                              "description": "Sum of `fees[].amount`. Sits outside `subtotal`, so `total = subtotal + feeTotal + taxTotal`."
                            },
                            "subtotal": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "taxTotal": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "total": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "amountPaid": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "amountRefunded": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "amountDue": {
                              "$ref": "#/components/schemas/Money"
                            }
                          },
                          "required": [
                            "currency",
                            "lines",
                            "fees",
                            "feeTotal",
                            "subtotal",
                            "taxTotal",
                            "total",
                            "amountPaid",
                            "amountRefunded",
                            "amountDue"
                          ]
                        }
                      },
                      "required": ["order", "items", "summary"]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error (including skuType PACKAGE, which is bought at order create), or currency mismatch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Order or offering not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "422": {
            "description": "The service has no active rate of the kind the line implies, e.g. a SINGLE_SESSION line on a service with no active SINGLE_BOOKING rate (SERVICE_NOT_SOLD_AS); or the line names a service that is not LIVE or was deleted, or an offering that is not ACTIVE (NOT_SELLABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/orders/{orderId}/items/{orderItemId}": {
      "patch": {
        "tags": ["Orders"],
        "summary": "Update an order item quantity",
        "description": "Changes quantity only — the unit price stays as resolved when the line was added, so re-pricing an existing line is not possible through this endpoint. Remove the line and add it again if the price must change. Returns the whole order with its recalculated totals.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The order — the commercial record. Order items are drawn down into bookings.",
              "example": "ord_01kv8m92p4jcrywn14znp8cym0"
            },
            "required": true,
            "description": "The order — the commercial record. Order items are drawn down into bookings.",
            "name": "orderId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The order item — one line of an order. A PACKAGE item funds many bookings; a SINGLE_SESSION item funds one.",
              "example": "oi_01kv8m92p6kdszxo25aoq9dzn1"
            },
            "required": true,
            "description": "The order item — one line of an order. A PACKAGE item funds many bookings; a SINGLE_SESSION item funds one.",
            "name": "orderItemId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Item update",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "quantity": {
                    "type": "integer",
                    "minimum": 1
                  }
                },
                "required": ["quantity"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Item updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "order": {
                          "$ref": "#/components/schemas/Order"
                        },
                        "items": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/OrderItem"
                          }
                        },
                        "summary": {
                          "type": "object",
                          "properties": {
                            "currency": {
                              "type": "string"
                            },
                            "lines": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "orderItemId": {
                                    "type": "string"
                                  },
                                  "label": {
                                    "type": "object",
                                    "nullable": true,
                                    "additionalProperties": {
                                      "type": "string"
                                    }
                                  },
                                  "skuType": {
                                    "type": "string",
                                    "enum": [
                                      "SINGLE_SESSION",
                                      "PACKAGE",
                                      "SUBSCRIPTION",
                                      "MEMBERSHIP",
                                      "DEPOSIT"
                                    ]
                                  },
                                  "quantity": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "unitPrice": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "lineTotal": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "tax": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "taxable": {
                                    "type": "boolean"
                                  },
                                  "priceRuleId": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "Which regional price rule this line resolved to. Compare against the offering/package `pricing[]` to see exactly which price was applied."
                                  },
                                  "priceScope": {
                                    "type": "string",
                                    "nullable": true,
                                    "enum": [
                                      "DEFAULT",
                                      "COUNTRY",
                                      "STATE",
                                      "POSTAL",
                                      null
                                    ],
                                    "description": "Specificity of the matched rule: DEFAULT, COUNTRY, STATE or POSTAL. DEFAULT means no regional rule matched and the fallback price was used."
                                  }
                                },
                                "required": [
                                  "orderItemId",
                                  "label",
                                  "skuType",
                                  "quantity",
                                  "unitPrice",
                                  "lineTotal",
                                  "tax",
                                  "taxable"
                                ]
                              }
                            },
                            "fees": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "feeId": {
                                    "type": "string",
                                    "description": "The fee as configured on the business model."
                                  },
                                  "businessModelId": {
                                    "type": "string",
                                    "description": "The business model that levied this fee — the commercial definition the charge belongs to."
                                  },
                                  "name": {
                                    "type": "object",
                                    "additionalProperties": {
                                      "type": "string"
                                    },
                                    "description": "Buyer-facing label, snapshotted at purchase time."
                                  },
                                  "calculation": {
                                    "type": "string",
                                    "enum": ["FLAT", "PERCENT"],
                                    "description": "How a service fee is calculated. FLAT charges a fixed amount; PERCENT charges a percentage of the pre-tax total of the lines the fee governs."
                                  },
                                  "percentage": {
                                    "type": "number",
                                    "nullable": true,
                                    "description": "Echoed for PERCENT fees so the buyer can be shown the rate that applied (e.g. \"Admin fee (5%)\"). Absent for FLAT fees."
                                  },
                                  "basis": {
                                    "type": "object",
                                    "properties": {
                                      "amount": {
                                        "type": "integer",
                                        "minimum": 0
                                      },
                                      "currency": {
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 3
                                      }
                                    },
                                    "required": ["amount", "currency"],
                                    "description": "Pre-tax total of this business model's lines — what a PERCENT fee was calculated against. Reported for FLAT fees too, so the figure is auditable."
                                  },
                                  "amount": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "tax": {
                                    "type": "object",
                                    "properties": {
                                      "amount": {
                                        "type": "integer",
                                        "minimum": 0
                                      },
                                      "currency": {
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 3
                                      }
                                    },
                                    "required": ["amount", "currency"],
                                    "description": "Tax on this fee, at the rate of its governing lines that are taxed at a positive rate. Zero when the fee is not taxable, or when none of those lines is taxed (each untaxed line says why in its taxExemptReason)."
                                  },
                                  "taxable": {
                                    "type": "boolean"
                                  }
                                },
                                "required": [
                                  "feeId",
                                  "businessModelId",
                                  "name",
                                  "calculation",
                                  "basis",
                                  "amount",
                                  "tax",
                                  "taxable"
                                ]
                              },
                              "description": "Service fees levied by the business models on this order. Each is a discrete charge in its own right. The fee amounts are NOT in `subtotal` or `taxTotal`, but tax charged on a fee IS added to `taxTotal`. Applied once per fee however many lines it governs."
                            },
                            "feeTotal": {
                              "type": "object",
                              "properties": {
                                "amount": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "currency": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 3
                                }
                              },
                              "required": ["amount", "currency"],
                              "description": "Sum of `fees[].amount`. Sits outside `subtotal`, so `total = subtotal + feeTotal + taxTotal`."
                            },
                            "subtotal": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "taxTotal": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "total": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "amountPaid": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "amountRefunded": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "amountDue": {
                              "$ref": "#/components/schemas/Money"
                            }
                          },
                          "required": [
                            "currency",
                            "lines",
                            "fees",
                            "feeTotal",
                            "subtotal",
                            "taxTotal",
                            "total",
                            "amountPaid",
                            "amountRefunded",
                            "amountDue"
                          ]
                        }
                      },
                      "required": ["order", "items", "summary"]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Order or item not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Orders"],
        "summary": "Remove an order item",
        "description": "Drops the line and returns the order with its recalculated totals. Removing a PACKAGE line does not retract bookings already drawn from it, so check `GET /orders/{orderId}/package-bookings?orderItemId=` before removing one that has been booked against.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The order — the commercial record. Order items are drawn down into bookings.",
              "example": "ord_01kv8m92p4jcrywn14znp8cym0"
            },
            "required": true,
            "description": "The order — the commercial record. Order items are drawn down into bookings.",
            "name": "orderId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The order item — one line of an order. A PACKAGE item funds many bookings; a SINGLE_SESSION item funds one.",
              "example": "oi_01kv8m92p6kdszxo25aoq9dzn1"
            },
            "required": true,
            "description": "The order item — one line of an order. A PACKAGE item funds many bookings; a SINGLE_SESSION item funds one.",
            "name": "orderItemId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Item removed; updated order summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "order": {
                          "$ref": "#/components/schemas/Order"
                        },
                        "items": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/OrderItem"
                          }
                        },
                        "summary": {
                          "type": "object",
                          "properties": {
                            "currency": {
                              "type": "string"
                            },
                            "lines": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "orderItemId": {
                                    "type": "string"
                                  },
                                  "label": {
                                    "type": "object",
                                    "nullable": true,
                                    "additionalProperties": {
                                      "type": "string"
                                    }
                                  },
                                  "skuType": {
                                    "type": "string",
                                    "enum": [
                                      "SINGLE_SESSION",
                                      "PACKAGE",
                                      "SUBSCRIPTION",
                                      "MEMBERSHIP",
                                      "DEPOSIT"
                                    ]
                                  },
                                  "quantity": {
                                    "type": "integer",
                                    "minimum": 0
                                  },
                                  "unitPrice": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "lineTotal": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "tax": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "taxable": {
                                    "type": "boolean"
                                  },
                                  "priceRuleId": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "Which regional price rule this line resolved to. Compare against the offering/package `pricing[]` to see exactly which price was applied."
                                  },
                                  "priceScope": {
                                    "type": "string",
                                    "nullable": true,
                                    "enum": [
                                      "DEFAULT",
                                      "COUNTRY",
                                      "STATE",
                                      "POSTAL",
                                      null
                                    ],
                                    "description": "Specificity of the matched rule: DEFAULT, COUNTRY, STATE or POSTAL. DEFAULT means no regional rule matched and the fallback price was used."
                                  }
                                },
                                "required": [
                                  "orderItemId",
                                  "label",
                                  "skuType",
                                  "quantity",
                                  "unitPrice",
                                  "lineTotal",
                                  "tax",
                                  "taxable"
                                ]
                              }
                            },
                            "fees": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "feeId": {
                                    "type": "string",
                                    "description": "The fee as configured on the business model."
                                  },
                                  "businessModelId": {
                                    "type": "string",
                                    "description": "The business model that levied this fee — the commercial definition the charge belongs to."
                                  },
                                  "name": {
                                    "type": "object",
                                    "additionalProperties": {
                                      "type": "string"
                                    },
                                    "description": "Buyer-facing label, snapshotted at purchase time."
                                  },
                                  "calculation": {
                                    "type": "string",
                                    "enum": ["FLAT", "PERCENT"],
                                    "description": "How a service fee is calculated. FLAT charges a fixed amount; PERCENT charges a percentage of the pre-tax total of the lines the fee governs."
                                  },
                                  "percentage": {
                                    "type": "number",
                                    "nullable": true,
                                    "description": "Echoed for PERCENT fees so the buyer can be shown the rate that applied (e.g. \"Admin fee (5%)\"). Absent for FLAT fees."
                                  },
                                  "basis": {
                                    "type": "object",
                                    "properties": {
                                      "amount": {
                                        "type": "integer",
                                        "minimum": 0
                                      },
                                      "currency": {
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 3
                                      }
                                    },
                                    "required": ["amount", "currency"],
                                    "description": "Pre-tax total of this business model's lines — what a PERCENT fee was calculated against. Reported for FLAT fees too, so the figure is auditable."
                                  },
                                  "amount": {
                                    "$ref": "#/components/schemas/Money"
                                  },
                                  "tax": {
                                    "type": "object",
                                    "properties": {
                                      "amount": {
                                        "type": "integer",
                                        "minimum": 0
                                      },
                                      "currency": {
                                        "type": "string",
                                        "minLength": 1,
                                        "maxLength": 3
                                      }
                                    },
                                    "required": ["amount", "currency"],
                                    "description": "Tax on this fee, at the rate of its governing lines that are taxed at a positive rate. Zero when the fee is not taxable, or when none of those lines is taxed (each untaxed line says why in its taxExemptReason)."
                                  },
                                  "taxable": {
                                    "type": "boolean"
                                  }
                                },
                                "required": [
                                  "feeId",
                                  "businessModelId",
                                  "name",
                                  "calculation",
                                  "basis",
                                  "amount",
                                  "tax",
                                  "taxable"
                                ]
                              },
                              "description": "Service fees levied by the business models on this order. Each is a discrete charge in its own right. The fee amounts are NOT in `subtotal` or `taxTotal`, but tax charged on a fee IS added to `taxTotal`. Applied once per fee however many lines it governs."
                            },
                            "feeTotal": {
                              "type": "object",
                              "properties": {
                                "amount": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "currency": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 3
                                }
                              },
                              "required": ["amount", "currency"],
                              "description": "Sum of `fees[].amount`. Sits outside `subtotal`, so `total = subtotal + feeTotal + taxTotal`."
                            },
                            "subtotal": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "taxTotal": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "total": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "amountPaid": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "amountRefunded": {
                              "$ref": "#/components/schemas/Money"
                            },
                            "amountDue": {
                              "$ref": "#/components/schemas/Money"
                            }
                          },
                          "required": [
                            "currency",
                            "lines",
                            "fees",
                            "feeTotal",
                            "subtotal",
                            "taxTotal",
                            "total",
                            "amountPaid",
                            "amountRefunded",
                            "amountDue"
                          ]
                        }
                      },
                      "required": ["order", "items", "summary"]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Order or item not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/orders/{orderId}/package-bookings": {
      "post": {
        "tags": ["Orders"],
        "summary": "Create N package sessions atomically (or best-effort) from one PACKAGE order item",
        "description": "Books all sessions of a package against one PACKAGE order item. Provide exactly one source: slateId (book a whole slate — recommended; the server resolves times/supplier/location and fills the travel-zone location itself), slotIds (cherry-pick), or sessions (explicit). Booking does NOT require the order to be paid — credits exist from order creation — but a CANCELLED order books nothing (409 ORDER_CANCELLED), as package-slate refuses to plan from its credits. Note: this response is NOT wrapped in a { data } envelope, and created[].sessionIndex is 0-based. Returns 409 with freshSuggestions if a chosen slot went stale — regenerated from the stale slate's request but planned from THIS order item (its remaining sessions, offering and expiry), so they can be booked here; null when this item has nothing left to plan — or with code SLOT_HELD/SLOT_BOOKED naming the blocking claim if the requested time is taken. Every session must book the order item's own service and offering (400 ORDER_ITEM_SERVICE_MISMATCH); asking for more sessions than remain is 400 ORDER_ITEM_QUANTITY_UNAVAILABLE (409 with the same code only when a concurrent booking used them first). A session starting after the credit's `expiresAt` is 409 `PACKAGE_EXPIRED` (all_or_nothing refuses the whole call; best_effort reports it in `failed[]`); reusing an `idempotencyKey` with a different body is 409 `IDEMPOTENCY_KEY_CONFLICT`.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The order — the commercial record. Order items are drawn down into bookings.",
              "example": "ord_01kv8m92p4jcrywn14znp8cym0"
            },
            "required": true,
            "description": "The order — the commercial record. Order items are drawn down into bookings.",
            "name": "orderId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Order item + sessions + atomicity",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "orderItemId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The PACKAGE order item to draw down. All N sessions decrement its quantityRemaining.",
                    "example": "oi_01kx16ek2kf2fsc9x7b2n1dfc9"
                  },
                  "idempotencyKey": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Idempotency key that makes retry attempts safe; reusing it returns the original result. A slateId/slotIds retry must arrive within the slate's resolvable window; after that it is refused like a stale slate.",
                    "example": "a3f1c2e4-5b6d-4e7f-8a9b-0c1d2e3f4a5b"
                  },
                  "atomicity": {
                    "type": "string",
                    "enum": ["all_or_nothing", "best_effort"],
                    "default": "all_or_nothing",
                    "description": "all_or_nothing (default, one transaction, max 15 sessions) or best_effort (per-session; requires project opt-in).",
                    "example": "all_or_nothing"
                  },
                  "sessions": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "supplierId": {
                          "type": "string",
                          "minLength": 1,
                          "description": "The supplier who delivers the session. Must belong to this project.",
                          "example": "sup_01kx16ejb3fz2g5h8k1m4p7r9t"
                        },
                        "bookingStartUtc": {
                          "type": "string",
                          "format": "date-time",
                          "description": "When the session starts, as an ISO 8601 UTC instant.",
                          "example": "2026-11-03T20:00:00.000Z"
                        },
                        "bookingEndUtc": {
                          "type": "string",
                          "format": "date-time",
                          "description": "When the session ends, as an ISO 8601 UTC instant.",
                          "example": "2026-11-03T20:30:00.000Z"
                        },
                        "bookingTz": {
                          "type": "string",
                          "minLength": 1,
                          "description": "The session's home zone (IANA). The booking's local date and times are derived from the UTC instants in this zone.",
                          "example": "America/Toronto"
                        },
                        "locationType": {
                          "type": "string",
                          "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"],
                          "description": "Where the session happens: PHYSICAL (at a venue; locationId required), TRAVEL_ZONE (at the client's address; locationId is the supplier's travel zone, and latitude, longitude and address are required) or VIRTUAL (online; locationId must be null).",
                          "example": "VIRTUAL"
                        },
                        "locationId": {
                          "type": "string",
                          "nullable": true,
                          "minLength": 1,
                          "description": "The venue (PHYSICAL) or supplier travel zone (TRAVEL_ZONE). Null for VIRTUAL.",
                          "example": "loc_01kx16ejc7fq4r6s9v2x5z8b1d"
                        },
                        "latitude": {
                          "type": "number",
                          "nullable": true,
                          "description": "Latitude of the client's address. Required for TRAVEL_ZONE.",
                          "example": 43.6532
                        },
                        "longitude": {
                          "type": "number",
                          "nullable": true,
                          "description": "Longitude of the client's address. Required for TRAVEL_ZONE.",
                          "example": -79.3832
                        },
                        "address": {
                          "$ref": "#/components/schemas/Address"
                        },
                        "services": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "serviceId": {
                                "type": "string",
                                "minLength": 1,
                                "description": "The service this session books. Must be the order item's own service.",
                                "example": "srv_01kx16ej8wfp0b4v3x1q7m2d5c"
                              },
                              "offeringId": {
                                "type": "string",
                                "minLength": 1,
                                "description": "The offering this session books. Must be the order item's own offering.",
                                "example": "off_01kx16ej9af1c3s8t6y2w4n7hb"
                              }
                            },
                            "required": ["serviceId", "offeringId"]
                          },
                          "minItems": 1,
                          "description": "The service lines of the session: the order item's service and offering.",
                          "example": [
                            {
                              "serviceId": "srv_01kx16ej8wfp0b4v3x1q7m2d5c",
                              "offeringId": "off_01kx16ej9af1c3s8t6y2w4n7hb"
                            }
                          ]
                        }
                      },
                      "required": [
                        "supplierId",
                        "bookingStartUtc",
                        "bookingEndUtc",
                        "bookingTz",
                        "locationType",
                        "services"
                      ]
                    },
                    "minItems": 1,
                    "description": "Explicit, client-supplied sessions (advanced). Prefer slateId. Provide exactly one of sessions, slateId, or slotIds."
                  },
                  "slateId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Book an entire persisted slate by id (recommended). The server resolves every session; send no session details.",
                    "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                  },
                  "slotIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1
                    },
                    "minItems": 1,
                    "description": "Cherry-pick specific persisted slots by id. Provide exactly one of sessions, slateId, or slotIds.",
                    "example": ["slot_01kx16ejsrfs7tf3edy19wdsf8"]
                  }
                },
                "required": ["orderItemId", "idempotencyKey"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Package bookings created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "orderId": {
                      "type": "string"
                    },
                    "orderItemId": {
                      "type": "string"
                    },
                    "packageOrderItemId": {
                      "type": "string"
                    },
                    "atomicity": {
                      "type": "string",
                      "enum": ["all_or_nothing", "best_effort"]
                    },
                    "created": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "sessionIndex": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "bookingId": {
                            "type": "string"
                          },
                          "allocationId": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "sessionIndex",
                          "bookingId",
                          "allocationId"
                        ]
                      },
                      "description": "Bookings created, each with a 0-based sessionIndex, bookingId and allocationId."
                    },
                    "failed": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "sessionIndex": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "reason": {
                            "type": "string"
                          }
                        },
                        "required": ["sessionIndex", "reason"]
                      },
                      "description": "Per-session failures (best_effort only)."
                    },
                    "quantityRemaining": {
                      "type": "integer",
                      "minimum": 0,
                      "description": "Credits left on the order item after this call."
                    }
                  },
                  "required": [
                    "orderId",
                    "orderItemId",
                    "packageOrderItemId",
                    "atomicity",
                    "created",
                    "failed",
                    "quantityRemaining"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validation error, a session for another service/offering, more sessions than remain, or a location of the wrong type / another supplier’s / with invalid fields",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Order / item / offering / supplier / location not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "PACKAGE_EXPIRED, ORDER_CANCELLED (a cancelled order), ORDER_ITEM_QUANTITY_UNAVAILABLE (a concurrent booking used the credits first), IDEMPOTENCY_KEY_CONFLICT, SLOT_HELD/SLOT_BOOKED (supplier time held/booked), OCCUPANCY_CONTENTION (the calendar is under contention), or the slate/slot went stale (freshSuggestions returned)",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/ErrorMessage"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": ["SLOT_HELD", "SLOT_BOOKED"],
                          "description": "Which kind of claim is blocking the requested time.",
                          "example": "SLOT_HELD"
                        },
                        "message": {
                          "type": "string",
                          "description": "Human-readable summary of the conflict.",
                          "example": "Supplier time is not available: HOLD resv_01kv8p20m1gnqvxl92xln6awk8 (2026-08-01T10:00:00Z–2026-08-01T11:00:00Z)"
                        },
                        "statusCode": {
                          "type": "number",
                          "enum": [409],
                          "description": "The HTTP status, repeated in the body — every MarketBox error carries it, so you can branch on the body alone.",
                          "example": 409
                        },
                        "requestId": {
                          "type": "string",
                          "description": "The id of this request (also returned as the X-Request-Id header). Quote it in a support ticket.",
                          "example": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
                        },
                        "conflicts": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "claimType": {
                                "type": "string",
                                "enum": ["BOOKING", "HOLD"],
                                "description": "Whether the blocking claim is a HOLD or a confirmed BOOKING."
                              },
                              "supplierId": {
                                "type": "string",
                                "nullable": true,
                                "description": "The supplier whose calendar is blocked, when known."
                              },
                              "startUtc": {
                                "type": "string",
                                "format": "date-time",
                                "description": "Start of the blocking claim, UTC ISO 8601.",
                                "example": "2026-08-01T10:00:00Z"
                              },
                              "endUtc": {
                                "type": "string",
                                "format": "date-time",
                                "description": "End of the blocking claim, UTC ISO 8601.",
                                "example": "2026-08-01T11:00:00Z"
                              },
                              "reservationId": {
                                "type": "string",
                                "nullable": true,
                                "description": "Present when claimType is HOLD — the reservationId to convert or release. Null for a BOOKING conflict.",
                                "example": "resv_01kv8p20m1gnqvxl92xln6awk8"
                              },
                              "bookingId": {
                                "type": "string",
                                "nullable": true,
                                "description": "Present when claimType is BOOKING — the id of the confirmed booking occupying this time. Null for a HOLD conflict.",
                                "example": null
                              },
                              "heldUntil": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time",
                                "description": "HOLD only: when the blocking hold lazily expires. Null for a BOOKING conflict.",
                                "example": "2026-08-01T10:05:00Z"
                              }
                            },
                            "required": ["claimType", "startUtc", "endUtc"]
                          },
                          "description": "Every live claim that overlaps the requested time — usually one, but can be more."
                        },
                        "hint": {
                          "type": "string",
                          "description": "What to do next: for SLOT_HELD, convert or release the named reservationId (POST .../holds/{reservationId}/convert or /release); for SLOT_BOOKED, search availability again.",
                          "example": "This time is held (reservation resv_01kv8p20m1gnqvxl92xln6awk8). Convert the hold via POST /v1/projects/{projectId}/holds/{reservationId}/convert, or release it with POST /v1/projects/{projectId}/holds/{reservationId}/release. Direct booking routes will not consume a hold — if you hold, you convert."
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "statusCode",
                        "requestId",
                        "conflicts",
                        "hint"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "statusCode": {
                          "type": "number",
                          "enum": [409],
                          "description": "The HTTP status, repeated in the body — every MarketBox error carries it, so you can branch on the body alone.",
                          "example": 409
                        },
                        "requestId": {
                          "type": "string",
                          "description": "The id of this request (also returned as the X-Request-Id header). Quote it in a support ticket.",
                          "example": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
                        },
                        "freshSuggestions": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "searchId": {
                              "type": "string",
                              "description": "The id of this search, also returned as the `X-MB-Search-Id` header. Every page of a paginated search carries the same id (the cursor keeps it). Keep it for the session if you want attribution: pass it back as `searchId` when the client books, and in the `search.rendered` event when you report what you showed.",
                              "example": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
                            },
                            "status": {
                              "type": "string",
                              "enum": [
                                "OK",
                                "ALTERNATIVE_CADENCE",
                                "NO_COMPLETE_SLATE",
                                "NO_AVAILABILITY"
                              ],
                              "description": "OK, ALTERNATIVE_CADENCE, NO_COMPLETE_SLATE, or NO_AVAILABILITY. ALTERNATIVE_CADENCE is only reachable when this request opted in via cadenceFlexibility or guaranteeSlate — a request sending today’s body (neither set) never observes it."
                            },
                            "reason": {
                              "type": "string",
                              "nullable": true
                            },
                            "suggestionRequestId": {
                              "type": "string",
                              "nullable": true,
                              "description": "Audit id for this suggestion request (present when persisted)."
                            },
                            "resolvableUntil": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "primarySlate": {
                              "type": "object",
                              "nullable": true,
                              "properties": {
                                "slateId": {
                                  "type": "string",
                                  "description": "Pass this to POST .../package-bookings to book the whole plan.",
                                  "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                                },
                                "supplierId": {
                                  "type": "string"
                                },
                                "completeness": {
                                  "type": "string",
                                  "enum": ["COMPLETE", "PARTIAL"]
                                },
                                "sessionsRequested": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true,
                                  "description": "How many sessions were requested (the package's creditCount)."
                                },
                                "sessionsFilled": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "How many of the requested sessions the plan could fill."
                                },
                                "startTimeConsistencyPercent": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 100
                                },
                                "totalTravelTimeMins": {
                                  "type": "number",
                                  "minimum": 0
                                },
                                "slots": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "slotId": {
                                        "type": "string",
                                        "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                                      },
                                      "sessionIndex": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "1-based index of this session within the slate."
                                      },
                                      "supplierId": {
                                        "type": "string"
                                      },
                                      "serviceId": {
                                        "type": "string"
                                      },
                                      "offeringId": {
                                        "type": "string"
                                      },
                                      "bookingStartUtc": {
                                        "type": "string",
                                        "format": "date-time"
                                      },
                                      "bookingEndUtc": {
                                        "type": "string",
                                        "format": "date-time"
                                      },
                                      "bookingTz": {
                                        "type": "string"
                                      },
                                      "locationType": {
                                        "type": "string",
                                        "enum": [
                                          "PHYSICAL",
                                          "VIRTUAL",
                                          "TRAVEL_ZONE"
                                        ]
                                      },
                                      "locationId": {
                                        "type": "string",
                                        "nullable": true
                                      },
                                      "latitude": {
                                        "type": "number",
                                        "nullable": true
                                      },
                                      "longitude": {
                                        "type": "number",
                                        "nullable": true
                                      },
                                      "address": {
                                        "$ref": "#/components/schemas/Address"
                                      },
                                      "travelTimeMins": {
                                        "type": "number",
                                        "nullable": true,
                                        "minimum": 0
                                      },
                                      "capacity": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true
                                      },
                                      "reservationStatus": {
                                        "type": "string",
                                        "enum": [
                                          "FREE",
                                          "HELD",
                                          "CONVERTED",
                                          "RELEASED"
                                        ]
                                      }
                                    },
                                    "required": [
                                      "slotId",
                                      "sessionIndex",
                                      "supplierId",
                                      "serviceId",
                                      "offeringId",
                                      "bookingStartUtc",
                                      "bookingEndUtc",
                                      "bookingTz",
                                      "locationType",
                                      "locationId",
                                      "latitude",
                                      "longitude",
                                      "address",
                                      "travelTimeMins",
                                      "capacity",
                                      "reservationStatus"
                                    ]
                                  }
                                },
                                "position": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                                  "example": 0
                                },
                                "cadenceRrule": {
                                  "type": "string",
                                  "nullable": true,
                                  "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                                  "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                                },
                                "matchesRequestedCadence": {
                                  "type": "boolean",
                                  "description": "True when cadenceRrule is the rrule you asked for.",
                                  "example": false
                                },
                                "cadenceRelaxation": {
                                  "type": "string",
                                  "enum": [
                                    "EXACT",
                                    "INTERVAL_TIGHTENED",
                                    "DAYS_ADDED",
                                    "DAYS_SUBSTITUTED",
                                    "ALL_WORKING_DAYS",
                                    "DIRECT_FILL"
                                  ],
                                  "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                },
                                "cadenceDistance": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                                  "example": 2
                                },
                                "cadenceSummary": {
                                  "type": "object",
                                  "properties": {
                                    "requested": {
                                      "type": "integer",
                                      "nullable": true,
                                      "minimum": 0,
                                      "exclusiveMinimum": true,
                                      "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                                      "example": 4
                                    },
                                    "peak": {
                                      "type": "integer",
                                      "minimum": 0,
                                      "exclusiveMinimum": true,
                                      "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                                      "example": 4
                                    },
                                    "average": {
                                      "type": "number",
                                      "minimum": 0,
                                      "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                                      "example": 2.25
                                    },
                                    "byWeek": {
                                      "type": "array",
                                      "items": {
                                        "type": "object",
                                        "properties": {
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                            "example": "2026-09-14"
                                          },
                                          "sessions": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                            "example": 0
                                          }
                                        },
                                        "required": ["weekStart", "sessions"]
                                      },
                                      "minItems": 1,
                                      "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                                    }
                                  },
                                  "required": [
                                    "requested",
                                    "peak",
                                    "average",
                                    "byWeek"
                                  ],
                                  "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                                },
                                "matchNotes": {
                                  "type": "array",
                                  "items": {
                                    "oneOf": [
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": [
                                              "SUPPLIER_UNAVAILABLE_WEEK"
                                            ]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "openingsInPool": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                "example": 2
                                              },
                                              "supplierWorkdays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "openingsInPool",
                                              "supplierWorkdays"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_EXCLUDED_BY_FILTERS"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "filter": {
                                                "type": "string",
                                                "enum": [
                                                  "daysOfWeek",
                                                  "excludeDates"
                                                ]
                                              },
                                              "supplierWorkdays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "requestedDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "excludedDates": {
                                                "type": "array",
                                                "items": {
                                                  "type": "string"
                                                }
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "filter",
                                              "supplierWorkdays"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_SUPPLY_INSUFFICIENT"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "openingsInPool": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                "example": 2
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "openingsInPool"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_CAPPED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "cap": {
                                                "type": "string",
                                                "enum": [
                                                  "maxSessionsPerWeek",
                                                  "minGapDays"
                                                ]
                                              },
                                              "capValue": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "cap",
                                              "capValue"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["SESSIONS_EXHAUSTED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsRequested": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              },
                                              "sessionsPlacedBefore": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "required": [
                                              "sessionsRequested",
                                              "sessionsPlacedBefore"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["CADENCE_RELAXED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["cadence"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "cadenceRelaxation": {
                                                "type": "string",
                                                "enum": [
                                                  "EXACT",
                                                  "INTERVAL_TIGHTENED",
                                                  "DAYS_ADDED",
                                                  "DAYS_SUBSTITUTED",
                                                  "ALL_WORKING_DAYS",
                                                  "DIRECT_FILL"
                                                ],
                                                "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                              },
                                              "requestedDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "actualDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              }
                                            },
                                            "required": ["cadenceRelaxation"]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": [
                                              "SESSIONS_OUTSIDE_PREFERRED_TIMES"
                                            ]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["timeOfDay"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionIndexes": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                }
                                              },
                                              "localTimes": {
                                                "type": "array",
                                                "items": {
                                                  "type": "string"
                                                }
                                              }
                                            },
                                            "required": [
                                              "sessionIndexes",
                                              "localTimes"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["FIRST_SESSION_LATE"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["startDate"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "firstSessionDate": {
                                                "type": "string"
                                              },
                                              "windowStartDate": {
                                                "type": "string"
                                              },
                                              "dayOffset": {
                                                "type": "integer",
                                                "minimum": 0
                                              },
                                              "earlierSupplyExisted": {
                                                "type": "boolean",
                                                "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                              }
                                            },
                                            "required": [
                                              "firstSessionDate",
                                              "windowStartDate",
                                              "dayOffset",
                                              "earlierSupplyExisted"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["PACKAGE_UNDERFILLED"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsRequested": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              },
                                              "sessionsFilled": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "required": [
                                              "sessionsRequested",
                                              "sessionsFilled"
                                            ]
                                          }
                                        },
                                        "required": ["code", "evidence"],
                                        "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                                      }
                                    ]
                                  },
                                  "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                                },
                                "advice": {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["LATER_START_IMPROVES_CADENCE"]
                                    },
                                    "earliestSustainedWeek": {
                                      "type": "string",
                                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                      "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                                      "example": "2026-09-14"
                                    }
                                  },
                                  "required": ["code", "earliestSustainedWeek"],
                                  "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                                },
                                "matchScore": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 1,
                                  "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                                  "example": 1
                                },
                                "matchComponents": {
                                  "type": "object",
                                  "properties": {
                                    "startDate": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                                    },
                                    "timeOfDay": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                                    },
                                    "daysOfWeek": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                                    },
                                    "sessionsPerWeek": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                                    },
                                    "cadence": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                                    }
                                  },
                                  "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                                }
                              },
                              "required": [
                                "slateId",
                                "supplierId",
                                "completeness",
                                "sessionsRequested",
                                "sessionsFilled",
                                "startTimeConsistencyPercent",
                                "totalTravelTimeMins",
                                "slots",
                                "matchNotes",
                                "matchScore"
                              ],
                              "description": "The best COMPLETE single-supplier slate; book this by slateId."
                            },
                            "alternates": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "slateId": {
                                    "type": "string",
                                    "description": "Pass this to POST .../package-bookings to book the whole plan.",
                                    "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                                  },
                                  "supplierId": {
                                    "type": "string"
                                  },
                                  "completeness": {
                                    "type": "string",
                                    "enum": ["COMPLETE", "PARTIAL"]
                                  },
                                  "sessionsRequested": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "exclusiveMinimum": true,
                                    "description": "How many sessions were requested (the package's creditCount)."
                                  },
                                  "sessionsFilled": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "How many of the requested sessions the plan could fill."
                                  },
                                  "startTimeConsistencyPercent": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 100
                                  },
                                  "totalTravelTimeMins": {
                                    "type": "number",
                                    "minimum": 0
                                  },
                                  "slots": {
                                    "type": "array",
                                    "items": {
                                      "type": "object",
                                      "properties": {
                                        "slotId": {
                                          "type": "string",
                                          "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                                        },
                                        "sessionIndex": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true,
                                          "description": "1-based index of this session within the slate."
                                        },
                                        "supplierId": {
                                          "type": "string"
                                        },
                                        "serviceId": {
                                          "type": "string"
                                        },
                                        "offeringId": {
                                          "type": "string"
                                        },
                                        "bookingStartUtc": {
                                          "type": "string",
                                          "format": "date-time"
                                        },
                                        "bookingEndUtc": {
                                          "type": "string",
                                          "format": "date-time"
                                        },
                                        "bookingTz": {
                                          "type": "string"
                                        },
                                        "locationType": {
                                          "type": "string",
                                          "enum": [
                                            "PHYSICAL",
                                            "VIRTUAL",
                                            "TRAVEL_ZONE"
                                          ]
                                        },
                                        "locationId": {
                                          "type": "string",
                                          "nullable": true
                                        },
                                        "latitude": {
                                          "type": "number",
                                          "nullable": true
                                        },
                                        "longitude": {
                                          "type": "number",
                                          "nullable": true
                                        },
                                        "address": {
                                          "$ref": "#/components/schemas/Address"
                                        },
                                        "travelTimeMins": {
                                          "type": "number",
                                          "nullable": true,
                                          "minimum": 0
                                        },
                                        "capacity": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true
                                        },
                                        "reservationStatus": {
                                          "type": "string",
                                          "enum": [
                                            "FREE",
                                            "HELD",
                                            "CONVERTED",
                                            "RELEASED"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "slotId",
                                        "sessionIndex",
                                        "supplierId",
                                        "serviceId",
                                        "offeringId",
                                        "bookingStartUtc",
                                        "bookingEndUtc",
                                        "bookingTz",
                                        "locationType",
                                        "locationId",
                                        "latitude",
                                        "longitude",
                                        "address",
                                        "travelTimeMins",
                                        "capacity",
                                        "reservationStatus"
                                      ]
                                    }
                                  },
                                  "position": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                                    "example": 0
                                  },
                                  "cadenceRrule": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                                    "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                                  },
                                  "matchesRequestedCadence": {
                                    "type": "boolean",
                                    "description": "True when cadenceRrule is the rrule you asked for.",
                                    "example": false
                                  },
                                  "cadenceRelaxation": {
                                    "type": "string",
                                    "enum": [
                                      "EXACT",
                                      "INTERVAL_TIGHTENED",
                                      "DAYS_ADDED",
                                      "DAYS_SUBSTITUTED",
                                      "ALL_WORKING_DAYS",
                                      "DIRECT_FILL"
                                    ],
                                    "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                  },
                                  "cadenceDistance": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                                    "example": 2
                                  },
                                  "cadenceSummary": {
                                    "type": "object",
                                    "properties": {
                                      "requested": {
                                        "type": "integer",
                                        "nullable": true,
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                                        "example": 4
                                      },
                                      "peak": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                                        "example": 4
                                      },
                                      "average": {
                                        "type": "number",
                                        "minimum": 0,
                                        "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                                        "example": 2.25
                                      },
                                      "byWeek": {
                                        "type": "array",
                                        "items": {
                                          "type": "object",
                                          "properties": {
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                              "example": "2026-09-14"
                                            },
                                            "sessions": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                              "example": 0
                                            }
                                          },
                                          "required": ["weekStart", "sessions"]
                                        },
                                        "minItems": 1,
                                        "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                                      }
                                    },
                                    "required": [
                                      "requested",
                                      "peak",
                                      "average",
                                      "byWeek"
                                    ],
                                    "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                                  },
                                  "matchNotes": {
                                    "type": "array",
                                    "items": {
                                      "oneOf": [
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "SUPPLIER_UNAVAILABLE_WEEK"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "openingsInPool": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                  "example": 2
                                                },
                                                "supplierWorkdays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "openingsInPool",
                                                "supplierWorkdays"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "WEEK_EXCLUDED_BY_FILTERS"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "filter": {
                                                  "type": "string",
                                                  "enum": [
                                                    "daysOfWeek",
                                                    "excludeDates"
                                                  ]
                                                },
                                                "supplierWorkdays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                },
                                                "requestedDays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                },
                                                "excludedDates": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "string"
                                                  }
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "filter",
                                                "supplierWorkdays"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "WEEK_SUPPLY_INSUFFICIENT"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "openingsInPool": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                  "example": 2
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "openingsInPool"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["WEEK_CAPPED"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "cap": {
                                                  "type": "string",
                                                  "enum": [
                                                    "maxSessionsPerWeek",
                                                    "minGapDays"
                                                  ]
                                                },
                                                "capValue": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "cap",
                                                "capValue"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["SESSIONS_EXHAUSTED"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsRequested": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                },
                                                "sessionsPlacedBefore": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                }
                                              },
                                              "required": [
                                                "sessionsRequested",
                                                "sessionsPlacedBefore"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["CADENCE_RELAXED"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["cadence"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "cadenceRelaxation": {
                                                  "type": "string",
                                                  "enum": [
                                                    "EXACT",
                                                    "INTERVAL_TIGHTENED",
                                                    "DAYS_ADDED",
                                                    "DAYS_SUBSTITUTED",
                                                    "ALL_WORKING_DAYS",
                                                    "DIRECT_FILL"
                                                  ],
                                                  "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                                },
                                                "requestedDays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                },
                                                "actualDays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                }
                                              },
                                              "required": ["cadenceRelaxation"]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "evidence"
                                          ],
                                          "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "SESSIONS_OUTSIDE_PREFERRED_TIMES"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["timeOfDay"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionIndexes": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "exclusiveMinimum": true
                                                  }
                                                },
                                                "localTimes": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "string"
                                                  }
                                                }
                                              },
                                              "required": [
                                                "sessionIndexes",
                                                "localTimes"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "evidence"
                                          ],
                                          "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["FIRST_SESSION_LATE"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["startDate"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "firstSessionDate": {
                                                  "type": "string"
                                                },
                                                "windowStartDate": {
                                                  "type": "string"
                                                },
                                                "dayOffset": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "earlierSupplyExisted": {
                                                  "type": "boolean",
                                                  "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                                }
                                              },
                                              "required": [
                                                "firstSessionDate",
                                                "windowStartDate",
                                                "dayOffset",
                                                "earlierSupplyExisted"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "evidence"
                                          ],
                                          "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["PACKAGE_UNDERFILLED"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsRequested": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                },
                                                "sessionsFilled": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                }
                                              },
                                              "required": [
                                                "sessionsRequested",
                                                "sessionsFilled"
                                              ]
                                            }
                                          },
                                          "required": ["code", "evidence"],
                                          "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                                        }
                                      ]
                                    },
                                    "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                                  },
                                  "advice": {
                                    "type": "object",
                                    "properties": {
                                      "code": {
                                        "type": "string",
                                        "enum": ["LATER_START_IMPROVES_CADENCE"]
                                      },
                                      "earliestSustainedWeek": {
                                        "type": "string",
                                        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                        "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                                        "example": "2026-09-14"
                                      }
                                    },
                                    "required": [
                                      "code",
                                      "earliestSustainedWeek"
                                    ],
                                    "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                                  },
                                  "matchScore": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1,
                                    "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                                    "example": 1
                                  },
                                  "matchComponents": {
                                    "type": "object",
                                    "properties": {
                                      "startDate": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                                      },
                                      "timeOfDay": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                                      },
                                      "daysOfWeek": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                                      },
                                      "sessionsPerWeek": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                                      },
                                      "cadence": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                                      }
                                    },
                                    "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                                  }
                                },
                                "required": [
                                  "slateId",
                                  "supplierId",
                                  "completeness",
                                  "sessionsRequested",
                                  "sessionsFilled",
                                  "startTimeConsistencyPercent",
                                  "totalTravelTimeMins",
                                  "slots",
                                  "matchNotes",
                                  "matchScore"
                                ]
                              },
                              "description": "Other bookable options beyond primarySlate, ranked best first and capped at the maxAlternates you sent. Under the default supplierPolicy of SAME_SUPPLIER these are other schedules from the SAME supplier as primarySlate; under PREFERRED or ANY they are other suppliers’ best schedules, one per supplier. Two schedules from one supplier count as different options only when they run on different weekdays, or start at least 30 minutes apart — so a supplier offering 09:00 and 09:20 gives you one option, not two. Each entry’s slateId is bookable exactly like primarySlate’s."
                            },
                            "partial": {
                              "type": "object",
                              "nullable": true,
                              "properties": {
                                "slateId": {
                                  "type": "string",
                                  "description": "Pass this to POST .../package-bookings to book the whole plan.",
                                  "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                                },
                                "supplierId": {
                                  "type": "string"
                                },
                                "completeness": {
                                  "type": "string",
                                  "enum": ["COMPLETE", "PARTIAL"]
                                },
                                "sessionsRequested": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true,
                                  "description": "How many sessions were requested (the package's creditCount)."
                                },
                                "sessionsFilled": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "How many of the requested sessions the plan could fill."
                                },
                                "startTimeConsistencyPercent": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 100
                                },
                                "totalTravelTimeMins": {
                                  "type": "number",
                                  "minimum": 0
                                },
                                "slots": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "slotId": {
                                        "type": "string",
                                        "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                                      },
                                      "sessionIndex": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "1-based index of this session within the slate."
                                      },
                                      "supplierId": {
                                        "type": "string"
                                      },
                                      "serviceId": {
                                        "type": "string"
                                      },
                                      "offeringId": {
                                        "type": "string"
                                      },
                                      "bookingStartUtc": {
                                        "type": "string",
                                        "format": "date-time"
                                      },
                                      "bookingEndUtc": {
                                        "type": "string",
                                        "format": "date-time"
                                      },
                                      "bookingTz": {
                                        "type": "string"
                                      },
                                      "locationType": {
                                        "type": "string",
                                        "enum": [
                                          "PHYSICAL",
                                          "VIRTUAL",
                                          "TRAVEL_ZONE"
                                        ]
                                      },
                                      "locationId": {
                                        "type": "string",
                                        "nullable": true
                                      },
                                      "latitude": {
                                        "type": "number",
                                        "nullable": true
                                      },
                                      "longitude": {
                                        "type": "number",
                                        "nullable": true
                                      },
                                      "address": {
                                        "$ref": "#/components/schemas/Address"
                                      },
                                      "travelTimeMins": {
                                        "type": "number",
                                        "nullable": true,
                                        "minimum": 0
                                      },
                                      "capacity": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true
                                      },
                                      "reservationStatus": {
                                        "type": "string",
                                        "enum": [
                                          "FREE",
                                          "HELD",
                                          "CONVERTED",
                                          "RELEASED"
                                        ]
                                      }
                                    },
                                    "required": [
                                      "slotId",
                                      "sessionIndex",
                                      "supplierId",
                                      "serviceId",
                                      "offeringId",
                                      "bookingStartUtc",
                                      "bookingEndUtc",
                                      "bookingTz",
                                      "locationType",
                                      "locationId",
                                      "latitude",
                                      "longitude",
                                      "address",
                                      "travelTimeMins",
                                      "capacity",
                                      "reservationStatus"
                                    ]
                                  }
                                },
                                "position": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                                  "example": 0
                                },
                                "cadenceRrule": {
                                  "type": "string",
                                  "nullable": true,
                                  "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                                  "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                                },
                                "matchesRequestedCadence": {
                                  "type": "boolean",
                                  "description": "True when cadenceRrule is the rrule you asked for.",
                                  "example": false
                                },
                                "cadenceRelaxation": {
                                  "type": "string",
                                  "enum": [
                                    "EXACT",
                                    "INTERVAL_TIGHTENED",
                                    "DAYS_ADDED",
                                    "DAYS_SUBSTITUTED",
                                    "ALL_WORKING_DAYS",
                                    "DIRECT_FILL"
                                  ],
                                  "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                },
                                "cadenceDistance": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                                  "example": 2
                                },
                                "cadenceSummary": {
                                  "type": "object",
                                  "properties": {
                                    "requested": {
                                      "type": "integer",
                                      "nullable": true,
                                      "minimum": 0,
                                      "exclusiveMinimum": true,
                                      "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                                      "example": 4
                                    },
                                    "peak": {
                                      "type": "integer",
                                      "minimum": 0,
                                      "exclusiveMinimum": true,
                                      "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                                      "example": 4
                                    },
                                    "average": {
                                      "type": "number",
                                      "minimum": 0,
                                      "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                                      "example": 2.25
                                    },
                                    "byWeek": {
                                      "type": "array",
                                      "items": {
                                        "type": "object",
                                        "properties": {
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                            "example": "2026-09-14"
                                          },
                                          "sessions": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                            "example": 0
                                          }
                                        },
                                        "required": ["weekStart", "sessions"]
                                      },
                                      "minItems": 1,
                                      "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                                    }
                                  },
                                  "required": [
                                    "requested",
                                    "peak",
                                    "average",
                                    "byWeek"
                                  ],
                                  "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                                },
                                "matchNotes": {
                                  "type": "array",
                                  "items": {
                                    "oneOf": [
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": [
                                              "SUPPLIER_UNAVAILABLE_WEEK"
                                            ]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "openingsInPool": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                "example": 2
                                              },
                                              "supplierWorkdays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "openingsInPool",
                                              "supplierWorkdays"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_EXCLUDED_BY_FILTERS"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "filter": {
                                                "type": "string",
                                                "enum": [
                                                  "daysOfWeek",
                                                  "excludeDates"
                                                ]
                                              },
                                              "supplierWorkdays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "requestedDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "excludedDates": {
                                                "type": "array",
                                                "items": {
                                                  "type": "string"
                                                }
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "filter",
                                              "supplierWorkdays"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_SUPPLY_INSUFFICIENT"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "openingsInPool": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                "example": 2
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "openingsInPool"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_CAPPED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "cap": {
                                                "type": "string",
                                                "enum": [
                                                  "maxSessionsPerWeek",
                                                  "minGapDays"
                                                ]
                                              },
                                              "capValue": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "cap",
                                              "capValue"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["SESSIONS_EXHAUSTED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsRequested": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              },
                                              "sessionsPlacedBefore": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "required": [
                                              "sessionsRequested",
                                              "sessionsPlacedBefore"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["CADENCE_RELAXED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["cadence"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "cadenceRelaxation": {
                                                "type": "string",
                                                "enum": [
                                                  "EXACT",
                                                  "INTERVAL_TIGHTENED",
                                                  "DAYS_ADDED",
                                                  "DAYS_SUBSTITUTED",
                                                  "ALL_WORKING_DAYS",
                                                  "DIRECT_FILL"
                                                ],
                                                "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                              },
                                              "requestedDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "actualDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              }
                                            },
                                            "required": ["cadenceRelaxation"]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": [
                                              "SESSIONS_OUTSIDE_PREFERRED_TIMES"
                                            ]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["timeOfDay"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionIndexes": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                }
                                              },
                                              "localTimes": {
                                                "type": "array",
                                                "items": {
                                                  "type": "string"
                                                }
                                              }
                                            },
                                            "required": [
                                              "sessionIndexes",
                                              "localTimes"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["FIRST_SESSION_LATE"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["startDate"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "firstSessionDate": {
                                                "type": "string"
                                              },
                                              "windowStartDate": {
                                                "type": "string"
                                              },
                                              "dayOffset": {
                                                "type": "integer",
                                                "minimum": 0
                                              },
                                              "earlierSupplyExisted": {
                                                "type": "boolean",
                                                "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                              }
                                            },
                                            "required": [
                                              "firstSessionDate",
                                              "windowStartDate",
                                              "dayOffset",
                                              "earlierSupplyExisted"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["PACKAGE_UNDERFILLED"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsRequested": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              },
                                              "sessionsFilled": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "required": [
                                              "sessionsRequested",
                                              "sessionsFilled"
                                            ]
                                          }
                                        },
                                        "required": ["code", "evidence"],
                                        "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                                      }
                                    ]
                                  },
                                  "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                                },
                                "advice": {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["LATER_START_IMPROVES_CADENCE"]
                                    },
                                    "earliestSustainedWeek": {
                                      "type": "string",
                                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                      "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                                      "example": "2026-09-14"
                                    }
                                  },
                                  "required": ["code", "earliestSustainedWeek"],
                                  "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                                },
                                "matchScore": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 1,
                                  "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                                  "example": 1
                                },
                                "matchComponents": {
                                  "type": "object",
                                  "properties": {
                                    "startDate": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                                    },
                                    "timeOfDay": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                                    },
                                    "daysOfWeek": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                                    },
                                    "sessionsPerWeek": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                                    },
                                    "cadence": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                                    }
                                  },
                                  "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                                }
                              },
                              "required": [
                                "slateId",
                                "supplierId",
                                "completeness",
                                "sessionsRequested",
                                "sessionsFilled",
                                "startTimeConsistencyPercent",
                                "totalTravelTimeMins",
                                "slots",
                                "matchNotes",
                                "matchScore"
                              ]
                            },
                            "cadenceAlternatives": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "slateId": {
                                    "type": "string",
                                    "description": "Pass this to POST .../package-bookings to book the whole plan.",
                                    "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                                  },
                                  "supplierId": {
                                    "type": "string"
                                  },
                                  "completeness": {
                                    "type": "string",
                                    "enum": ["COMPLETE", "PARTIAL"]
                                  },
                                  "sessionsRequested": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "exclusiveMinimum": true,
                                    "description": "How many sessions were requested (the package's creditCount)."
                                  },
                                  "sessionsFilled": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "How many of the requested sessions the plan could fill."
                                  },
                                  "startTimeConsistencyPercent": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 100
                                  },
                                  "totalTravelTimeMins": {
                                    "type": "number",
                                    "minimum": 0
                                  },
                                  "slots": {
                                    "type": "array",
                                    "items": {
                                      "type": "object",
                                      "properties": {
                                        "slotId": {
                                          "type": "string",
                                          "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                                        },
                                        "sessionIndex": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true,
                                          "description": "1-based index of this session within the slate."
                                        },
                                        "supplierId": {
                                          "type": "string"
                                        },
                                        "serviceId": {
                                          "type": "string"
                                        },
                                        "offeringId": {
                                          "type": "string"
                                        },
                                        "bookingStartUtc": {
                                          "type": "string",
                                          "format": "date-time"
                                        },
                                        "bookingEndUtc": {
                                          "type": "string",
                                          "format": "date-time"
                                        },
                                        "bookingTz": {
                                          "type": "string"
                                        },
                                        "locationType": {
                                          "type": "string",
                                          "enum": [
                                            "PHYSICAL",
                                            "VIRTUAL",
                                            "TRAVEL_ZONE"
                                          ]
                                        },
                                        "locationId": {
                                          "type": "string",
                                          "nullable": true
                                        },
                                        "latitude": {
                                          "type": "number",
                                          "nullable": true
                                        },
                                        "longitude": {
                                          "type": "number",
                                          "nullable": true
                                        },
                                        "address": {
                                          "$ref": "#/components/schemas/Address"
                                        },
                                        "travelTimeMins": {
                                          "type": "number",
                                          "nullable": true,
                                          "minimum": 0
                                        },
                                        "capacity": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true
                                        },
                                        "reservationStatus": {
                                          "type": "string",
                                          "enum": [
                                            "FREE",
                                            "HELD",
                                            "CONVERTED",
                                            "RELEASED"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "slotId",
                                        "sessionIndex",
                                        "supplierId",
                                        "serviceId",
                                        "offeringId",
                                        "bookingStartUtc",
                                        "bookingEndUtc",
                                        "bookingTz",
                                        "locationType",
                                        "locationId",
                                        "latitude",
                                        "longitude",
                                        "address",
                                        "travelTimeMins",
                                        "capacity",
                                        "reservationStatus"
                                      ]
                                    }
                                  },
                                  "position": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                                    "example": 0
                                  },
                                  "cadenceRrule": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                                    "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                                  },
                                  "matchesRequestedCadence": {
                                    "type": "boolean",
                                    "description": "True when cadenceRrule is the rrule you asked for.",
                                    "example": false
                                  },
                                  "cadenceRelaxation": {
                                    "type": "string",
                                    "enum": [
                                      "EXACT",
                                      "INTERVAL_TIGHTENED",
                                      "DAYS_ADDED",
                                      "DAYS_SUBSTITUTED",
                                      "ALL_WORKING_DAYS",
                                      "DIRECT_FILL"
                                    ],
                                    "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                  },
                                  "cadenceDistance": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                                    "example": 2
                                  },
                                  "cadenceSummary": {
                                    "type": "object",
                                    "properties": {
                                      "requested": {
                                        "type": "integer",
                                        "nullable": true,
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                                        "example": 4
                                      },
                                      "peak": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                                        "example": 4
                                      },
                                      "average": {
                                        "type": "number",
                                        "minimum": 0,
                                        "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                                        "example": 2.25
                                      },
                                      "byWeek": {
                                        "type": "array",
                                        "items": {
                                          "type": "object",
                                          "properties": {
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                              "example": "2026-09-14"
                                            },
                                            "sessions": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                              "example": 0
                                            }
                                          },
                                          "required": ["weekStart", "sessions"]
                                        },
                                        "minItems": 1,
                                        "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                                      }
                                    },
                                    "required": [
                                      "requested",
                                      "peak",
                                      "average",
                                      "byWeek"
                                    ],
                                    "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                                  },
                                  "matchNotes": {
                                    "type": "array",
                                    "items": {
                                      "oneOf": [
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "SUPPLIER_UNAVAILABLE_WEEK"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "openingsInPool": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                  "example": 2
                                                },
                                                "supplierWorkdays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "openingsInPool",
                                                "supplierWorkdays"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "WEEK_EXCLUDED_BY_FILTERS"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "filter": {
                                                  "type": "string",
                                                  "enum": [
                                                    "daysOfWeek",
                                                    "excludeDates"
                                                  ]
                                                },
                                                "supplierWorkdays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                },
                                                "requestedDays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                },
                                                "excludedDates": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "string"
                                                  }
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "filter",
                                                "supplierWorkdays"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "WEEK_SUPPLY_INSUFFICIENT"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "openingsInPool": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                  "example": 2
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "openingsInPool"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["WEEK_CAPPED"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "cap": {
                                                  "type": "string",
                                                  "enum": [
                                                    "maxSessionsPerWeek",
                                                    "minGapDays"
                                                  ]
                                                },
                                                "capValue": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "cap",
                                                "capValue"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["SESSIONS_EXHAUSTED"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsRequested": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                },
                                                "sessionsPlacedBefore": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                }
                                              },
                                              "required": [
                                                "sessionsRequested",
                                                "sessionsPlacedBefore"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["CADENCE_RELAXED"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["cadence"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "cadenceRelaxation": {
                                                  "type": "string",
                                                  "enum": [
                                                    "EXACT",
                                                    "INTERVAL_TIGHTENED",
                                                    "DAYS_ADDED",
                                                    "DAYS_SUBSTITUTED",
                                                    "ALL_WORKING_DAYS",
                                                    "DIRECT_FILL"
                                                  ],
                                                  "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                                },
                                                "requestedDays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                },
                                                "actualDays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                }
                                              },
                                              "required": ["cadenceRelaxation"]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "evidence"
                                          ],
                                          "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "SESSIONS_OUTSIDE_PREFERRED_TIMES"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["timeOfDay"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionIndexes": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "exclusiveMinimum": true
                                                  }
                                                },
                                                "localTimes": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "string"
                                                  }
                                                }
                                              },
                                              "required": [
                                                "sessionIndexes",
                                                "localTimes"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "evidence"
                                          ],
                                          "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["FIRST_SESSION_LATE"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["startDate"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "firstSessionDate": {
                                                  "type": "string"
                                                },
                                                "windowStartDate": {
                                                  "type": "string"
                                                },
                                                "dayOffset": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "earlierSupplyExisted": {
                                                  "type": "boolean",
                                                  "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                                }
                                              },
                                              "required": [
                                                "firstSessionDate",
                                                "windowStartDate",
                                                "dayOffset",
                                                "earlierSupplyExisted"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "evidence"
                                          ],
                                          "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["PACKAGE_UNDERFILLED"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsRequested": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                },
                                                "sessionsFilled": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                }
                                              },
                                              "required": [
                                                "sessionsRequested",
                                                "sessionsFilled"
                                              ]
                                            }
                                          },
                                          "required": ["code", "evidence"],
                                          "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                                        }
                                      ]
                                    },
                                    "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                                  },
                                  "advice": {
                                    "type": "object",
                                    "properties": {
                                      "code": {
                                        "type": "string",
                                        "enum": ["LATER_START_IMPROVES_CADENCE"]
                                      },
                                      "earliestSustainedWeek": {
                                        "type": "string",
                                        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                        "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                                        "example": "2026-09-14"
                                      }
                                    },
                                    "required": [
                                      "code",
                                      "earliestSustainedWeek"
                                    ],
                                    "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                                  },
                                  "matchScore": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1,
                                    "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                                    "example": 1
                                  },
                                  "matchComponents": {
                                    "type": "object",
                                    "properties": {
                                      "startDate": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                                      },
                                      "timeOfDay": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                                      },
                                      "daysOfWeek": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                                      },
                                      "sessionsPerWeek": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                                      },
                                      "cadence": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                                      }
                                    },
                                    "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                                  }
                                },
                                "required": [
                                  "slateId",
                                  "supplierId",
                                  "completeness",
                                  "sessionsRequested",
                                  "sessionsFilled",
                                  "startTimeConsistencyPercent",
                                  "totalTravelTimeMins",
                                  "slots",
                                  "matchNotes",
                                  "matchScore"
                                ]
                              },
                              "default": [],
                              "description": "Complete N-session slates that fit the supplier’s real availability but do NOT follow the rrule you asked for — e.g. you requested weekly Fridays, no supplier has eight free Fridays, so this carries a Mon+Fri plan instead. Sorted by cadenceDistance, closest first, when the request carries no sessionsPerWeek target; when it does, ranked by closeness to that target first and cadenceDistance only as the tiebreaker. Always empty unless the request set cadenceFlexibility or guaranteeSlate. Each entry’s slateId is bookable exactly like primarySlate’s."
                            },
                            "requestedCadence": {
                              "type": "string",
                              "nullable": true,
                              "description": "The rrule this request asked for, echoed back so you can diff it against each slate’s cadenceRrule.",
                              "example": "FREQ=WEEKLY;BYDAY=FR;COUNT=8"
                            }
                          },
                          "required": [
                            "status",
                            "reason",
                            "suggestionRequestId",
                            "resolvableUntil",
                            "primarySlate",
                            "alternates",
                            "partial"
                          ]
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "statusCode",
                        "requestId",
                        "freshSuggestions"
                      ]
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Slate too large, best-effort not enabled, a PHYSICAL location without coordinates (UNPROCESSABLE_ENTITY), or the credit’s offering is no longer ACTIVE (NOT_SELLABLE): a service retired since does not refuse credits already bought",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": ["Orders"],
        "summary": "List the bookings created for a PACKAGE order item",
        "description": "Every session already booked against this order — the other half of the package ledger. Compare the count against the item's credit count to see how many sessions remain unbooked, and call this before removing or refunding a PACKAGE line so you know what has already been consumed. Optional `startDate`/`endDate` narrow the window.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The order — the commercial record. Order items are drawn down into bookings.",
              "example": "ord_01kv8m92p4jcrywn14znp8cym0"
            },
            "required": true,
            "description": "The order — the commercial record. Order items are drawn down into bookings.",
            "name": "orderId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The order item — one line of an order. A PACKAGE item funds many bookings; a SINGLE_SESSION item funds one.",
              "example": "oi_01kv8m92p6kdszxo25aoq9dzn1"
            },
            "required": true,
            "description": "The order item — one line of an order. A PACKAGE item funds many bookings; a SINGLE_SESSION item funds one.",
            "name": "orderItemId",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "required": false,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "required": false,
            "name": "endDate",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Package bookings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Booking"
                      }
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Order or item not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers": {
      "get": {
        "tags": ["Suppliers"],
        "summary": "List suppliers for a project, enriched with services and skills; filter by service/skill/region/point",
        "description": "The supplier directory, each row already carrying its resolved `services` and `skills`, so a \"who can do X, near Y\" page needs one call. Every filter is AND, both within a parameter and across parameters: `services=a,b` means a supplier offering BOTH, never either. The location filter is hierarchical and each level requires the one above — `state` without `country` is a 400, as is `city` without both. Use ISO codes: `country` as 3166-1 alpha-2, `state` as 3166-2 in either form (\"CA-ON\" or \"ON\").\n\nOnly active suppliers are listed; inactive and soft-deleted ones never appear, on any combination of filters.\n\nTwo behaviours to plan for. A page holds `limit` rows whenever that many remain, on every combination of filters.\n\nThe location filter matches the regions a supplier SERVES — derived from the travel zones and physical locations on their LIVE schedules — not the address on their profile. A schedule is live when it is ACTIVE, not deleted, and its `endDate` has not passed in the schedule's own timezone; each row's `locations[]` is derived with the same rule, so a supplier is returned by `country`/`state`/`city` exactly when one of their `locations` covers it. A mobile supplier based in Barrie whose travel zone covers Toronto matches `city=Toronto`, while a supplier with an address but no live schedule matches nothing (and has `locations: []`), because they cannot be booked. Coverage resolves to the locality, its borough where one exists, and the wider municipality, so any of those names matches: a zone in Scarborough is returned by `city=Scarborough` and by `city=Toronto`. Results are ordered by supplier id, not by name.\n\nFor a specific address, pass `lat` and `lng` instead of a region: the result is every supplier whose live travel zone contains that point, tested against the zone's actual polygon or radius rather than a place name, and AND-combined with `services`/`skills`. The two location styles are exclusive — `lat`/`lng` with `country`/`state`/`city` is a 400. Suppliers whose live schedules are only at fixed locations have no zone and are not matched by a point; use the region filter or `POST /availability/suppliers` for those.\n\nA short page is possible but uncommon, so treat `nextCursor: null` as the only end-of-results signal and never stop on a page that merely looks short. And a cursor is only valid against the filter set that produced it; changing any filter mid-walk gives undefined results, so restart the walk instead.\n\nEvery page carries the same `searchId` (also the `X-MB-Search-Id` header; the cursor keeps it) and each row its 0-based `position`, continuous across pages. Keep `searchId` for the session if you want attribution. Two optional request headers tag the lookup for insights and are never acted on: `X-MB-Session-Key` (an opaque key you choose, up to 64 characters) and `X-MB-Client-Kind` (`browser`, `server`, `monitor` or `loadtest`).",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50,
              "description": "Maximum rows to return in `data`, 1–200. Defaults to 50. Values outside the range return 400. A page can still hold fewer rows than requested, so treat `nextCursor: null` as the only end-of-results signal and never stop on a page that merely looks short.",
              "example": 50
            },
            "required": false,
            "description": "Maximum rows to return in `data`, 1–200. Defaults to 50. Values outside the range return 400. A page can still hold fewer rows than requested, so treat `nextCursor: null` as the only end-of-results signal and never stop on a page that merely looks short.",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Opaque pagination token from a previous response's `nextCursor`. Treat it as a magic string — never parse or construct one. A cursor is only valid for the same filters that produced it, and `nextCursor: null` means the last page."
            },
            "required": false,
            "description": "Opaque pagination token from a previous response's `nextCursor`. Treat it as a magic string — never parse or construct one. A cursor is only valid for the same filters that produced it, and `nextCursor: null` means the last page.",
            "name": "cursor",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated service IDs. Returns only suppliers offering every listed service (AND). Combined with `skills` using AND. Empty value is treated as no filter."
            },
            "required": false,
            "description": "Comma-separated service IDs. Returns only suppliers offering every listed service (AND). Combined with `skills` using AND. Empty value is treated as no filter.",
            "name": "services",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Comma-separated skill IDs. Returns only suppliers having every listed skill (AND). Combined with `services` using AND. Empty value is treated as no filter."
            },
            "required": false,
            "description": "Comma-separated skill IDs. Returns only suppliers having every listed skill (AND). Combined with `services` using AND. Empty value is treated as no filter.",
            "name": "skills",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "ISO 3166-1 alpha-2 country code (e.g. \"CA\", \"US\"). Required when `state` or `city` is provided."
            },
            "required": false,
            "description": "ISO 3166-1 alpha-2 country code (e.g. \"CA\", \"US\"). Required when `state` or `city` is provided.",
            "name": "country",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "ISO 3166-2 subdivision of `country`, full (\"CA-ON\") or bare (\"ON\"). Requires `country`. Required when `city` is provided."
            },
            "required": false,
            "description": "ISO 3166-2 subdivision of `country`, full (\"CA-ON\") or bare (\"ON\"). Requires `country`. Required when `city` is provided.",
            "name": "state",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "City to filter by. Requires both `country` and `state`."
            },
            "required": false,
            "description": "City to filter by. Requires both `country` and `state`.",
            "name": "city",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Latitude of a point to be covered, decimal degrees in [-90, 90]. With `lng`, returns only suppliers whose live travel zone contains the point (exact polygon/radius test, not a region name). Requires `lng`; cannot be combined with `country`/`state`/`city`.",
              "example": "43.7462"
            },
            "required": false,
            "description": "Latitude of a point to be covered, decimal degrees in [-90, 90]. With `lng`, returns only suppliers whose live travel zone contains the point (exact polygon/radius test, not a region name). Requires `lng`; cannot be combined with `country`/`state`/`city`.",
            "name": "lat",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Longitude of the point, decimal degrees in [-180, 180]. Requires `lat`.",
              "example": "-79.2191"
            },
            "required": false,
            "description": "Longitude of the point, decimal degrees in [-180, 180]. Requires `lat`.",
            "name": "lng",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Suppliers list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "searchId": {
                      "type": "string",
                      "description": "The id of this search, also returned as the `X-MB-Search-Id` header. Every page of a paginated search carries the same id (the cursor keeps it). Keep it for the session if you want attribution: pass it back as `searchId` when the client books, and in the `search.rendered` event when you report what you showed.",
                      "example": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "supplierId": {
                            "type": "string"
                          },
                          "firstName": {
                            "type": "string"
                          },
                          "lastName": {
                            "type": "string"
                          },
                          "email": {
                            "type": "string"
                          },
                          "phone": {
                            "type": "string"
                          },
                          "addressoneline": {
                            "type": "string"
                          },
                          "longitude": {
                            "type": "number"
                          },
                          "latitude": {
                            "type": "number"
                          },
                          "city": {
                            "type": "string"
                          },
                          "state": {
                            "type": "string"
                          },
                          "country": {
                            "type": "string"
                          },
                          "postalcode": {
                            "type": "string"
                          },
                          "bio": {
                            "type": "string"
                          },
                          "maxTravelTime": {
                            "type": "number"
                          },
                          "externalId": {
                            "type": "string"
                          },
                          "externalData": {
                            "type": "object",
                            "additionalProperties": {
                              "nullable": true
                            }
                          },
                          "active": {
                            "type": "boolean"
                          },
                          "updatedAt": {
                            "type": "string"
                          },
                          "timezone": {
                            "type": "string",
                            "description": "The supplier's own IANA timezone. Absent when none is set on the profile, in which case fall back to the project's default timezone rather than the caller's. Every `*Local` time this API renders for this supplier is in this zone.",
                            "example": "America/Toronto"
                          },
                          "avatarUrl": {
                            "type": "string",
                            "nullable": true,
                            "format": "uri"
                          },
                          "services": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "serviceId": {
                                  "type": "string"
                                },
                                "name": {
                                  "type": "object",
                                  "additionalProperties": {
                                    "type": "string"
                                  }
                                }
                              },
                              "required": ["serviceId", "name"]
                            }
                          },
                          "skills": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "skillId": {
                                  "type": "string"
                                },
                                "name": {
                                  "type": "object",
                                  "additionalProperties": {
                                    "type": "string"
                                  }
                                }
                              },
                              "required": ["skillId", "name"]
                            }
                          },
                          "locations": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "locationId": {
                                  "type": "string"
                                },
                                "locationType": {
                                  "type": "string",
                                  "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"]
                                },
                                "name": {
                                  "type": "string"
                                },
                                "country": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "state": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "city": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "addressOneLine": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "street": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "latitude": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "longitude": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "travelZoneType": {
                                  "type": "string",
                                  "nullable": true,
                                  "enum": ["CIRCULAR", "DRAWN", null]
                                }
                              },
                              "required": ["locationId", "locationType", "name"]
                            }
                          },
                          "servedRegions": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "The region paths this supplier is indexed under — the SAME set the `country`/`state`/`city` filter on `GET /suppliers` matches against, so a supplier is returned by that filter exactly when the query's path is in this list. Slug paths at every hierarchy level, sorted: `ca/`, `ca/on/`, `ca/on/toronto/`, `ca/on/scarborough/`. Derived from the travel zones and physical locations on their live schedules (see `locations`), resolved to the locality, its borough and the wider municipality. Empty when the supplier has no live schedule with a geocodable zone. Region rows are pruned by a daily sweep, so this can lag a schedule's `endDate` by up to a day, whereas `locations` is evaluated on every request.",
                            "example": [
                              "ca/",
                              "ca/on/",
                              "ca/on/scarborough/",
                              "ca/on/toronto/"
                            ]
                          },
                          "languages": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "locales": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "defaultLocale": {
                            "type": "string"
                          },
                          "position": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "0-based rank of this entry in the order the response returned it. Paged results continue the count across pages of the same `searchId`, so the first entry of page 2 is numbered after the last of page 1.",
                            "example": 0
                          }
                        },
                        "required": [
                          "supplierId",
                          "firstName",
                          "lastName",
                          "email",
                          "active",
                          "updatedAt",
                          "avatarUrl",
                          "services",
                          "skills",
                          "locations",
                          "servedRegions",
                          "languages",
                          "locales",
                          "position"
                        ]
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": ["searchId", "data", "nextCursor"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid cursor or limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Suppliers"],
        "summary": "Create a supplier",
        "description": "Location fields are canonicalised to ISO codes: `country` is an ISO 3166-1 alpha-2 code (e.g. \"CA\"), `state` an ISO 3166-2 subdivision of that country (\"CA-ON\" or \"ON\"). Invalid codes return 400. `city` is free text.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Supplier data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "firstName": {
                    "type": "string",
                    "minLength": 1
                  },
                  "lastName": {
                    "type": "string",
                    "minLength": 1
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "phone": {
                    "type": "string",
                    "nullable": true,
                    "description": "Phone number. Accepts E.164 or a national NANP number; stored as E.164 (e.g. +14165550134)."
                  },
                  "addressoneline": {
                    "type": "string"
                  },
                  "street": {
                    "type": "string"
                  },
                  "city": {
                    "type": "string"
                  },
                  "state": {
                    "type": "string"
                  },
                  "country": {
                    "type": "string"
                  },
                  "postalcode": {
                    "type": "string"
                  },
                  "longitude": {
                    "type": "number"
                  },
                  "latitude": {
                    "type": "number"
                  },
                  "timezone": {
                    "type": "string",
                    "description": "IANA timezone the supplier works in. Drives when their daily agenda email fires: it is used verbatim as the EventBridge schedule timezone, so a value the scheduler rejects means no agenda email at all. Unset inherits the project’s defaultTimezone.",
                    "example": "America/Toronto"
                  },
                  "bio": {
                    "type": "string"
                  },
                  "maxTravelTime": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "externalId": {
                    "type": "string"
                  },
                  "externalData": {
                    "type": "object",
                    "additionalProperties": {
                      "nullable": true
                    }
                  },
                  "active": {
                    "type": "boolean",
                    "default": true
                  },
                  "serviceIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "default": []
                  },
                  "skillIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "default": []
                  },
                  "languages": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "en",
                        "fr",
                        "es",
                        "de",
                        "it",
                        "pt",
                        "nl",
                        "zh",
                        "ja",
                        "ko",
                        "ar",
                        "hi",
                        "ru",
                        "pl",
                        "tr",
                        "vi"
                      ]
                    },
                    "default": []
                  },
                  "defaultLocale": {
                    "type": "string",
                    "description": "The supplier's own preferred locale (BCP-47, e.g. 'fr-CA'). Staff-set only — never inferred from a booking. Omit to inherit the project default.",
                    "example": "fr-CA"
                  }
                },
                "required": ["firstName", "lastName", "email"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Supplier created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "supplierId": {
                          "type": "string"
                        },
                        "firstName": {
                          "type": "string"
                        },
                        "lastName": {
                          "type": "string"
                        },
                        "email": {
                          "type": "string"
                        },
                        "phone": {
                          "type": "string"
                        },
                        "addressoneline": {
                          "type": "string"
                        },
                        "longitude": {
                          "type": "number"
                        },
                        "latitude": {
                          "type": "number"
                        },
                        "city": {
                          "type": "string"
                        },
                        "state": {
                          "type": "string"
                        },
                        "country": {
                          "type": "string"
                        },
                        "postalcode": {
                          "type": "string"
                        },
                        "bio": {
                          "type": "string"
                        },
                        "maxTravelTime": {
                          "type": "number"
                        },
                        "externalId": {
                          "type": "string"
                        },
                        "externalData": {
                          "type": "object",
                          "additionalProperties": {
                            "nullable": true
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "updatedAt": {
                          "type": "string"
                        },
                        "timezone": {
                          "type": "string",
                          "description": "The supplier's own IANA timezone. Absent when none is set on the profile, in which case fall back to the project's default timezone rather than the caller's. Every `*Local` time this API renders for this supplier is in this zone.",
                          "example": "America/Toronto"
                        },
                        "avatarUrl": {
                          "type": "string",
                          "nullable": true,
                          "format": "uri"
                        },
                        "services": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "serviceId": {
                                "type": "string"
                              },
                              "name": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              }
                            },
                            "required": ["serviceId", "name"]
                          }
                        },
                        "skills": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "skillId": {
                                "type": "string"
                              },
                              "name": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              }
                            },
                            "required": ["skillId", "name"]
                          }
                        },
                        "locations": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "locationId": {
                                "type": "string"
                              },
                              "locationType": {
                                "type": "string",
                                "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"]
                              },
                              "name": {
                                "type": "string"
                              },
                              "country": {
                                "type": "string",
                                "nullable": true
                              },
                              "state": {
                                "type": "string",
                                "nullable": true
                              },
                              "city": {
                                "type": "string",
                                "nullable": true
                              },
                              "addressOneLine": {
                                "type": "string",
                                "nullable": true
                              },
                              "street": {
                                "type": "string",
                                "nullable": true
                              },
                              "latitude": {
                                "type": "number",
                                "nullable": true
                              },
                              "longitude": {
                                "type": "number",
                                "nullable": true
                              },
                              "travelZoneType": {
                                "type": "string",
                                "nullable": true,
                                "enum": ["CIRCULAR", "DRAWN", null]
                              }
                            },
                            "required": ["locationId", "locationType", "name"]
                          }
                        },
                        "servedRegions": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The region paths this supplier is indexed under — the SAME set the `country`/`state`/`city` filter on `GET /suppliers` matches against, so a supplier is returned by that filter exactly when the query's path is in this list. Slug paths at every hierarchy level, sorted: `ca/`, `ca/on/`, `ca/on/toronto/`, `ca/on/scarborough/`. Derived from the travel zones and physical locations on their live schedules (see `locations`), resolved to the locality, its borough and the wider municipality. Empty when the supplier has no live schedule with a geocodable zone. Region rows are pruned by a daily sweep, so this can lag a schedule's `endDate` by up to a day, whereas `locations` is evaluated on every request.",
                          "example": [
                            "ca/",
                            "ca/on/",
                            "ca/on/scarborough/",
                            "ca/on/toronto/"
                          ]
                        },
                        "languages": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "locales": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "defaultLocale": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "supplierId",
                        "firstName",
                        "lastName",
                        "email",
                        "active",
                        "updatedAt",
                        "avatarUrl",
                        "services",
                        "skills",
                        "locations",
                        "servedRegions",
                        "languages",
                        "locales"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error or unknown service/skill id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "Duplicate email in project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/{supplierId}": {
      "get": {
        "tags": ["Suppliers"],
        "summary": "One supplier in full: profile, services, skills, locations, rating and working hours",
        "description": "Everything about one supplier in a single call — the same shape `GET /suppliers` returns for a row, plus two blocks the list deliberately omits because they cost a read each: `rating` and `availability`. Use it for a supplier profile page; use the list for a directory.\n\nIt also carries an `access` block saying whether the supplier record is linked to a person and what that person may do on the project: `userId`, `invitationStatus`, `roles`, `membershipStatus` and `accessEndedAt`. The list does not carry it.\n\nThe response carries the full booking identity, not just display content: `supplierId` to book against, `active` for whether they take bookings at all, `services[]` with ids AND localized labels, `timezone` for rendering their hours, `country`/`state`/`postalcode` (the inputs regional price rules resolve against), and every `locations[].locationId` — including travel zones, which is the id you send as `locationId` when you book a mobile service.\n\n`availability` is the recurring pattern of WHEN AND WHERE THIS SUPPLIER WORKS. It is not a list of bookable times: it ignores existing bookings, time off, and how long an offering takes, so never present a slot built from it as available. For times you can actually book, call `POST /availability/suppliers` with a service, an offering and a location. Only ACTIVE schedules appear, so `availability.schedules: []` means this supplier cannot currently be booked at all — which can be true even when `active` is `true`, because the two are set independently.\n\nUnlike the list, this endpoint DOES return an inactive supplier, with `active: false`, so a profile page for a paused supplier still renders. A 404 means the id is unknown in this project, belongs to another project, or has been deleted — those three are not distinguished.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The supplier — the person or resource delivering the service.",
              "example": "sup_01kv60qh1k5xylm7r0c1qj8zpa"
            },
            "required": true,
            "description": "The supplier — the person or resource delivering the service.",
            "name": "supplierId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "The supplier",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "supplierId": {
                          "type": "string"
                        },
                        "firstName": {
                          "type": "string"
                        },
                        "lastName": {
                          "type": "string"
                        },
                        "email": {
                          "type": "string"
                        },
                        "phone": {
                          "type": "string"
                        },
                        "addressoneline": {
                          "type": "string"
                        },
                        "longitude": {
                          "type": "number"
                        },
                        "latitude": {
                          "type": "number"
                        },
                        "city": {
                          "type": "string"
                        },
                        "state": {
                          "type": "string"
                        },
                        "country": {
                          "type": "string"
                        },
                        "postalcode": {
                          "type": "string"
                        },
                        "bio": {
                          "type": "string"
                        },
                        "maxTravelTime": {
                          "type": "number"
                        },
                        "externalId": {
                          "type": "string"
                        },
                        "externalData": {
                          "type": "object",
                          "additionalProperties": {
                            "nullable": true
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "updatedAt": {
                          "type": "string"
                        },
                        "timezone": {
                          "type": "string",
                          "description": "The supplier's own IANA timezone. Absent when none is set on the profile, in which case fall back to the project's default timezone rather than the caller's. Every `*Local` time this API renders for this supplier is in this zone.",
                          "example": "America/Toronto"
                        },
                        "avatarUrl": {
                          "type": "string",
                          "nullable": true,
                          "format": "uri"
                        },
                        "services": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "serviceId": {
                                "type": "string"
                              },
                              "name": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              }
                            },
                            "required": ["serviceId", "name"]
                          }
                        },
                        "skills": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "skillId": {
                                "type": "string"
                              },
                              "name": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              }
                            },
                            "required": ["skillId", "name"]
                          }
                        },
                        "locations": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "locationId": {
                                "type": "string"
                              },
                              "locationType": {
                                "type": "string",
                                "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"]
                              },
                              "name": {
                                "type": "string"
                              },
                              "country": {
                                "type": "string",
                                "nullable": true
                              },
                              "state": {
                                "type": "string",
                                "nullable": true
                              },
                              "city": {
                                "type": "string",
                                "nullable": true
                              },
                              "addressOneLine": {
                                "type": "string",
                                "nullable": true
                              },
                              "street": {
                                "type": "string",
                                "nullable": true
                              },
                              "latitude": {
                                "type": "number",
                                "nullable": true
                              },
                              "longitude": {
                                "type": "number",
                                "nullable": true
                              },
                              "travelZoneType": {
                                "type": "string",
                                "nullable": true,
                                "enum": ["CIRCULAR", "DRAWN", null]
                              }
                            },
                            "required": ["locationId", "locationType", "name"]
                          }
                        },
                        "servedRegions": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The region paths this supplier is indexed under — the SAME set the `country`/`state`/`city` filter on `GET /suppliers` matches against, so a supplier is returned by that filter exactly when the query's path is in this list. Slug paths at every hierarchy level, sorted: `ca/`, `ca/on/`, `ca/on/toronto/`, `ca/on/scarborough/`. Derived from the travel zones and physical locations on their live schedules (see `locations`), resolved to the locality, its borough and the wider municipality. Empty when the supplier has no live schedule with a geocodable zone. Region rows are pruned by a daily sweep, so this can lag a schedule's `endDate` by up to a day, whereas `locations` is evaluated on every request.",
                          "example": [
                            "ca/",
                            "ca/on/",
                            "ca/on/scarborough/",
                            "ca/on/toronto/"
                          ]
                        },
                        "languages": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "locales": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "defaultLocale": {
                          "type": "string"
                        },
                        "rating": {
                          "type": "object",
                          "properties": {
                            "averageRating": {
                              "type": "number",
                              "description": "Mean star rating across every review of this supplier, rounded to one decimal place. Maintained in the same atomic write that records each review, so it never disagrees with the rows behind it. `0` when there are no reviews — check `reviewCount` before rendering a rating, or an unrated supplier displays as zero stars.",
                              "example": 4.7
                            },
                            "reviewCount": {
                              "type": "integer",
                              "description": "How many reviews the average is based on.",
                              "example": 128
                            },
                            "recent": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "reviewId": {
                                    "type": "string"
                                  },
                                  "supplierId": {
                                    "type": "string"
                                  },
                                  "clientId": {
                                    "type": "string"
                                  },
                                  "projectId": {
                                    "type": "string"
                                  },
                                  "ratingStars": {
                                    "type": "integer"
                                  },
                                  "reviewText": {
                                    "type": "string"
                                  },
                                  "reviewerId": {
                                    "type": "string"
                                  },
                                  "bookingId": {
                                    "type": "string"
                                  },
                                  "direction": {
                                    "type": "string",
                                    "enum": [
                                      "CLIENT_TO_SUPPLIER",
                                      "SUPPLIER_TO_CLIENT"
                                    ]
                                  },
                                  "subjectType": {
                                    "type": "string",
                                    "enum": ["SUPPLIER", "CLIENT"]
                                  },
                                  "subjectId": {
                                    "type": "string"
                                  },
                                  "createdAt": {
                                    "type": "string"
                                  },
                                  "supplierName": {
                                    "type": "string"
                                  },
                                  "clientName": {
                                    "type": "string"
                                  }
                                },
                                "required": [
                                  "reviewId",
                                  "supplierId",
                                  "projectId",
                                  "ratingStars",
                                  "direction",
                                  "subjectType",
                                  "subjectId",
                                  "createdAt"
                                ]
                              },
                              "description": "The 5 newest reviews, for a profile card. This is a preview, not the full set — page `GET /reviews?supplierId=…` for that. Empty when the supplier has no reviews. No email address is returned for either party."
                            }
                          },
                          "required": [
                            "averageRating",
                            "reviewCount",
                            "recent"
                          ],
                          "description": "This supplier's star rating, plus a preview of the newest reviews."
                        },
                        "availability": {
                          "type": "object",
                          "properties": {
                            "timezone": {
                              "type": "string",
                              "description": "The timezone to read this supplier's working hours in — their own if set, otherwise the project default. Check `timezoneSource` before treating it as the supplier's own.",
                              "example": "America/Toronto"
                            },
                            "timezoneSource": {
                              "type": "string",
                              "enum": ["SUPPLIER", "PROJECT"],
                              "description": "Where `timezone` came from. `SUPPLIER` means it is set on the supplier profile. `PROJECT` means the profile has none and the project default was substituted — a reasonable display default, but not a statement about where this supplier actually works.",
                              "example": "SUPPLIER"
                            },
                            "schedules": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "scheduleId": {
                                    "type": "string",
                                    "description": "Stable id for this schedule.",
                                    "example": "sch_01kv60qgnef2kt3pvqgwmkbzfr"
                                  },
                                  "timezone": {
                                    "type": "string",
                                    "description": "The IANA timezone every `HH:mm` and date on THIS schedule is expressed in. Usually the same as `availability.timezone`, but a supplier working across zones can have schedules that differ — always read the times against this field, not the parent one.",
                                    "example": "America/Toronto"
                                  },
                                  "startDate": {
                                    "type": "string",
                                    "description": "First date this schedule is in effect, `YYYY-MM-DD` in its `timezone`.",
                                    "example": "2026-01-01"
                                  },
                                  "endDate": {
                                    "type": "string",
                                    "description": "Last date this schedule is in effect, `YYYY-MM-DD` in its `timezone`.",
                                    "example": "2026-12-31"
                                  },
                                  "rrule": {
                                    "type": "string",
                                    "description": "The recurrence rule (RFC 5545) that decides which weeks inside `startDate`–`endDate` the schedule runs. `FREQ=WEEKLY;INTERVAL=1` is every week; `INTERVAL=2` is fortnightly. The weekdays come from `weeklyHours`, not from this string.",
                                    "example": "FREQ=WEEKLY;INTERVAL=1"
                                  },
                                  "exdates": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    },
                                    "description": "Individual dates excluded from the recurrence (`YYYY-MM-DD`) — holidays and one-off closures. Empty when there are none.",
                                    "example": ["2026-07-01"]
                                  },
                                  "weeklyHours": {
                                    "type": "array",
                                    "items": {
                                      "type": "object",
                                      "properties": {
                                        "dayOfWeek": {
                                          "type": "string",
                                          "enum": [
                                            "MO",
                                            "TU",
                                            "WE",
                                            "TH",
                                            "FR",
                                            "SA",
                                            "SU"
                                          ],
                                          "description": "The weekday this range falls on, as a two-letter iCalendar code — the same codes an RRULE BYDAY uses.",
                                          "example": "MO"
                                        },
                                        "startTime": {
                                          "type": "string",
                                          "description": "Start of the working window, 24-hour `HH:mm` in the schedule's `timezone`.",
                                          "example": "09:00"
                                        },
                                        "endTime": {
                                          "type": "string",
                                          "description": "End of the working window, 24-hour `HH:mm` in the schedule's `timezone`. Earlier than `startTime` when the range runs past midnight — see `crossesMidnight`.",
                                          "example": "17:00"
                                        },
                                        "crossesMidnight": {
                                          "type": "boolean",
                                          "description": "True when the range runs into the next calendar day (`endTime` \u003C= `startTime`), e.g. 22:00–02:00. Do not compare the two strings numerically without checking this first, or a night shift reads as a negative-length day.",
                                          "example": false
                                        }
                                      },
                                      "required": [
                                        "dayOfWeek",
                                        "startTime",
                                        "endTime",
                                        "crossesMidnight"
                                      ]
                                    },
                                    "description": "The working windows that repeat each covered week. A weekday absent from this array is a day the supplier does not work under this schedule. Never empty."
                                  },
                                  "appliesToAllOfferings": {
                                    "type": "boolean",
                                    "description": "True when this schedule covers every offering the supplier can deliver, in which case `offeringIds` is empty. False means it covers only the ids in `offeringIds`.",
                                    "example": true
                                  },
                                  "offeringIds": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    },
                                    "description": "The offerings this schedule covers. Empty when `appliesToAllOfferings` is true — an empty array there means \"all\", not \"none\".",
                                    "example": []
                                  },
                                  "locationIds": {
                                    "type": "array",
                                    "items": {
                                      "type": "string"
                                    },
                                    "description": "Physical and virtual locations this schedule is worked at. Each id also appears in the supplier's `locations[]` with its full address. Excludes the travel zone, which has its own field.",
                                    "example": [
                                      "loc_01kv60qg12e82acr78edfnjhvv"
                                    ]
                                  },
                                  "travelZone": {
                                    "type": "object",
                                    "nullable": true,
                                    "properties": {
                                      "locationId": {
                                        "type": "string",
                                        "description": "The travel zone this schedule covers. This is the id to send as `locationId` when you book, and it also appears in the supplier's `locations[]` with `locationType: \"TRAVEL_ZONE\"`.",
                                        "example": "stz_01kv60qgnef2kt3pvqgwmkbzfr"
                                      },
                                      "source": {
                                        "type": "string",
                                        "enum": [
                                          "PROJECT_LOCATION",
                                          "SUPPLIER_TRAVEL_ZONE"
                                        ],
                                        "description": "Who owns the zone. `SUPPLIER_TRAVEL_ZONE` is a zone drawn for this supplier alone (id prefix `stz_`); `PROJECT_LOCATION` is a project-wide zone shared by several suppliers (id prefix `loc_`). Both are booked the same way — the distinction only matters if you render a coverage map.",
                                        "example": "SUPPLIER_TRAVEL_ZONE"
                                      }
                                    },
                                    "required": ["locationId", "source"],
                                    "description": "The travel zone this schedule covers, or `null` for a fixed-location schedule."
                                  },
                                  "summary": {
                                    "type": "object",
                                    "properties": {
                                      "days": {
                                        "type": "string",
                                        "description": "Human-readable weekdays, e.g. \"Mon, Wed, Fri\".",
                                        "example": "Mon, Wed, Fri"
                                      },
                                      "times": {
                                        "type": "string",
                                        "description": "Human-readable hours, e.g. \"9:00 AM – 5:00 PM\".",
                                        "example": "9:00 AM – 5:00 PM"
                                      },
                                      "dateRange": {
                                        "type": "string",
                                        "description": "Human-readable effective period, e.g. \"Jan 1 – Dec 31, 2026\".",
                                        "example": "Jan 1 – Dec 31, 2026"
                                      },
                                      "coverageArea": {
                                        "type": "string",
                                        "description": "Human-readable description of where this schedule applies.",
                                        "example": "Toronto travel zone"
                                      },
                                      "offerings": {
                                        "type": "string",
                                        "description": "Human-readable description of which offerings this schedule covers.",
                                        "example": "All offerings"
                                      }
                                    },
                                    "required": [
                                      "days",
                                      "times",
                                      "dateRange",
                                      "coverageArea",
                                      "offerings"
                                    ],
                                    "description": "Pre-rendered display strings for this schedule, built by MarketBox and shown in its dashboard. Convenient for a profile page; they are English and not localized, so build your own from the structured fields above if you serve multiple locales."
                                  }
                                },
                                "required": [
                                  "scheduleId",
                                  "timezone",
                                  "startDate",
                                  "endDate",
                                  "rrule",
                                  "exdates",
                                  "weeklyHours",
                                  "appliesToAllOfferings",
                                  "offeringIds",
                                  "locationIds",
                                  "travelZone",
                                  "summary"
                                ]
                              },
                              "description": "The supplier's LIVE schedules — the recurring pattern of when and where they work. A schedule is live when it is ACTIVE, not deleted, and its `endDate` has not passed in its own `timezone`; that is the same rule the `GET /suppliers` location filter and `locations[]` use. Inactive, deleted and ended schedules never appear, so `[]` means this supplier currently has no working hours at all and cannot be booked, whatever `active` says."
                            }
                          },
                          "required": [
                            "timezone",
                            "timezoneSource",
                            "schedules"
                          ],
                          "description": "When and where this supplier WORKS — their recurring schedule pattern. This is not a list of bookable times: it ignores existing bookings, time off, and how long an offering takes. For times you can actually book, call `POST /availability/suppliers` with a service, an offering and a location."
                        },
                        "access": {
                          "type": "object",
                          "properties": {
                            "userId": {
                              "type": "string",
                              "nullable": true,
                              "description": "The linked MarketBox user id (`Users.userId`, not the Cognito `sub`), or `null` when the record is not linked to a person. It is the user `/suppliers/me` resolves that person's token to."
                            },
                            "invitationStatus": {
                              "type": "string",
                              "enum": ["NONE", "INVITED", "LINKED"],
                              "description": "`NONE` (never invited, or unlinked since), `INVITED` (invited, not yet accepted) or `LINKED` (a person accepted)."
                            },
                            "roles": {
                              "type": "array",
                              "items": {
                                "type": "string",
                                "enum": [
                                  "CLIENT",
                                  "ADMIN",
                                  "MANAGER",
                                  "DEVELOPER",
                                  "SUPPLIER"
                                ]
                              },
                              "description": "Every role the linked person holds on the project, in the order `CLIENT`, `ADMIN`, `MANAGER`, `DEVELOPER`, `SUPPLIER`. Empty when the record is not linked, whatever the person still holds elsewhere, and empty unless the membership is `ACTIVE`."
                            },
                            "membershipStatus": {
                              "type": "string",
                              "nullable": true,
                              "enum": ["ACTIVE", "INACTIVE", null],
                              "description": "Whether the linked person's membership of the project is `ACTIVE` or `INACTIVE` (every status other than `ACTIVE` is reported as `INACTIVE`). `null` when the record is not linked."
                            },
                            "accessEndedAt": {
                              "type": "string",
                              "nullable": true,
                              "description": "When the record was last unlinked from a person (ISO 8601, UTC), or `null` if it never was. Cleared again when someone accepts a new invitation. `NONE` with a value here means the supplier was removed; `NONE` with `null` means never invited."
                            }
                          },
                          "required": [
                            "userId",
                            "invitationStatus",
                            "roles",
                            "membershipStatus",
                            "accessEndedAt"
                          ],
                          "description": "Whether this record is linked to a person who can sign in, and what that person holds on the project. Tells a removed supplier (`accessEndedAt` set) from one who was never invited."
                        }
                      },
                      "required": [
                        "supplierId",
                        "firstName",
                        "lastName",
                        "email",
                        "active",
                        "updatedAt",
                        "avatarUrl",
                        "services",
                        "skills",
                        "locations",
                        "servedRegions",
                        "languages",
                        "locales",
                        "rating",
                        "availability",
                        "access"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Supplier not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": ["Suppliers"],
        "summary": "Update a supplier; sync its service/skill mappings when arrays are supplied",
        "description": "Same ISO location contract as create: `country` is ISO 3166-1 alpha-2, `state` an ISO 3166-2 subdivision (\"CA-ON\" or \"ON\"). Invalid codes return 400.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The supplier — the person or resource delivering the service.",
              "example": "sup_01kv60qh1k5xylm7r0c1qj8zpa"
            },
            "required": true,
            "description": "The supplier — the person or resource delivering the service.",
            "name": "supplierId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Fields to update",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "firstName": {
                    "type": "string",
                    "minLength": 1
                  },
                  "lastName": {
                    "type": "string",
                    "minLength": 1
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "phone": {
                    "type": "string",
                    "nullable": true,
                    "description": "Phone number. Accepts E.164 or a national NANP number; stored as E.164 (e.g. +14165550134)."
                  },
                  "addressoneline": {
                    "type": "string"
                  },
                  "street": {
                    "type": "string"
                  },
                  "city": {
                    "type": "string"
                  },
                  "state": {
                    "type": "string"
                  },
                  "country": {
                    "type": "string"
                  },
                  "postalcode": {
                    "type": "string"
                  },
                  "longitude": {
                    "type": "number"
                  },
                  "latitude": {
                    "type": "number"
                  },
                  "timezone": {
                    "type": "string",
                    "description": "IANA timezone the supplier works in. Drives when their daily agenda email fires: it is used verbatim as the EventBridge schedule timezone, so a value the scheduler rejects means no agenda email at all. Unset inherits the project’s defaultTimezone.",
                    "example": "America/Toronto"
                  },
                  "bio": {
                    "type": "string",
                    "nullable": true,
                    "description": "Omit to leave the current bio unchanged; pass null to clear it."
                  },
                  "maxTravelTime": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "externalId": {
                    "type": "string"
                  },
                  "externalData": {
                    "type": "object",
                    "additionalProperties": {
                      "nullable": true
                    }
                  },
                  "active": {
                    "type": "boolean"
                  },
                  "serviceIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "skillIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "languages": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "en",
                        "fr",
                        "es",
                        "de",
                        "it",
                        "pt",
                        "nl",
                        "zh",
                        "ja",
                        "ko",
                        "ar",
                        "hi",
                        "ru",
                        "pl",
                        "tr",
                        "vi"
                      ]
                    }
                  },
                  "defaultLocale": {
                    "type": "string",
                    "nullable": true,
                    "description": "The supplier's own preferred locale (BCP-47, e.g. 'fr-CA'). Staff-set only — never inferred from a booking. Omit to leave the current value unchanged; pass null to clear it.",
                    "example": "fr-CA"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated supplier",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "supplierId": {
                          "type": "string"
                        },
                        "firstName": {
                          "type": "string"
                        },
                        "lastName": {
                          "type": "string"
                        },
                        "email": {
                          "type": "string"
                        },
                        "phone": {
                          "type": "string"
                        },
                        "addressoneline": {
                          "type": "string"
                        },
                        "longitude": {
                          "type": "number"
                        },
                        "latitude": {
                          "type": "number"
                        },
                        "city": {
                          "type": "string"
                        },
                        "state": {
                          "type": "string"
                        },
                        "country": {
                          "type": "string"
                        },
                        "postalcode": {
                          "type": "string"
                        },
                        "bio": {
                          "type": "string"
                        },
                        "maxTravelTime": {
                          "type": "number"
                        },
                        "externalId": {
                          "type": "string"
                        },
                        "externalData": {
                          "type": "object",
                          "additionalProperties": {
                            "nullable": true
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "updatedAt": {
                          "type": "string"
                        },
                        "timezone": {
                          "type": "string",
                          "description": "The supplier's own IANA timezone. Absent when none is set on the profile, in which case fall back to the project's default timezone rather than the caller's. Every `*Local` time this API renders for this supplier is in this zone.",
                          "example": "America/Toronto"
                        },
                        "avatarUrl": {
                          "type": "string",
                          "nullable": true,
                          "format": "uri"
                        },
                        "services": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "serviceId": {
                                "type": "string"
                              },
                              "name": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              }
                            },
                            "required": ["serviceId", "name"]
                          }
                        },
                        "skills": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "skillId": {
                                "type": "string"
                              },
                              "name": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              }
                            },
                            "required": ["skillId", "name"]
                          }
                        },
                        "locations": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "locationId": {
                                "type": "string"
                              },
                              "locationType": {
                                "type": "string",
                                "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"]
                              },
                              "name": {
                                "type": "string"
                              },
                              "country": {
                                "type": "string",
                                "nullable": true
                              },
                              "state": {
                                "type": "string",
                                "nullable": true
                              },
                              "city": {
                                "type": "string",
                                "nullable": true
                              },
                              "addressOneLine": {
                                "type": "string",
                                "nullable": true
                              },
                              "street": {
                                "type": "string",
                                "nullable": true
                              },
                              "latitude": {
                                "type": "number",
                                "nullable": true
                              },
                              "longitude": {
                                "type": "number",
                                "nullable": true
                              },
                              "travelZoneType": {
                                "type": "string",
                                "nullable": true,
                                "enum": ["CIRCULAR", "DRAWN", null]
                              }
                            },
                            "required": ["locationId", "locationType", "name"]
                          }
                        },
                        "servedRegions": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The region paths this supplier is indexed under — the SAME set the `country`/`state`/`city` filter on `GET /suppliers` matches against, so a supplier is returned by that filter exactly when the query's path is in this list. Slug paths at every hierarchy level, sorted: `ca/`, `ca/on/`, `ca/on/toronto/`, `ca/on/scarborough/`. Derived from the travel zones and physical locations on their live schedules (see `locations`), resolved to the locality, its borough and the wider municipality. Empty when the supplier has no live schedule with a geocodable zone. Region rows are pruned by a daily sweep, so this can lag a schedule's `endDate` by up to a day, whereas `locations` is evaluated on every request.",
                          "example": [
                            "ca/",
                            "ca/on/",
                            "ca/on/scarborough/",
                            "ca/on/toronto/"
                          ]
                        },
                        "languages": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "locales": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "defaultLocale": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "supplierId",
                        "firstName",
                        "lastName",
                        "email",
                        "active",
                        "updatedAt",
                        "avatarUrl",
                        "services",
                        "skills",
                        "locations",
                        "servedRegions",
                        "languages",
                        "locales"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error or unknown service/skill id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Supplier not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "Duplicate email in project, or `active` was sent and changed between this update’s read and its write (CONFLICT): read the supplier again and retry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Suppliers"],
        "summary": "Soft-delete a supplier (cascade-removes its mappings and avatar)",
        "description": "Retires a supplier. The profile is soft-deleted and stays readable to bookings that reference it, but the cascade around it is permanent: every service and skill mapping is hard-deleted and the avatar images are removed from storage. There is no undelete — recreating the supplier means re-adding all mappings and re-uploading the avatar, so use the `active` flag on update if you only need them off the roster temporarily. Existing bookings are not cancelled and not reassigned; deal with the diary first or the supplier stays booked for work nobody will be matched to. Deleting an id from another project, or one already deleted, is a 404.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The supplier — the person or resource delivering the service.",
              "example": "sup_01kv60qh1k5xylm7r0c1qj8zpa"
            },
            "required": true,
            "description": "The supplier — the person or resource delivering the service.",
            "name": "supplierId",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Supplier not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "CONFLICT: the supplier's sign-in changed while it was being deleted. Try again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/{supplierId}/services/{serviceId}": {
      "post": {
        "tags": ["Suppliers"],
        "summary": "Add a service to a supplier",
        "description": "Declares that this supplier performs this service, which is what makes them appear in availability searches and in `?services=` filters for it. Idempotent: re-adding an existing mapping succeeds and changes nothing, so you can call it without checking first. The service must already exist in the project — an unknown id is a 400, not a silently created mapping. Returns the full enriched supplier, so use this response rather than re-fetching. Adding one mapping at a time is fine for a handful; to replace a supplier's whole service set in one write, send `serviceIds` to PUT /suppliers/{supplierId} instead.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The supplier — the person or resource delivering the service.",
              "example": "sup_01kv60qh1k5xylm7r0c1qj8zpa"
            },
            "required": true,
            "description": "The supplier — the person or resource delivering the service.",
            "name": "supplierId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
              "example": "srv_01kv60qg12e82acr78edfnjhvv"
            },
            "required": true,
            "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
            "name": "serviceId",
            "in": "path"
          }
        ],
        "responses": {
          "201": {
            "description": "Supplier with the service added",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "supplierId": {
                          "type": "string"
                        },
                        "firstName": {
                          "type": "string"
                        },
                        "lastName": {
                          "type": "string"
                        },
                        "email": {
                          "type": "string"
                        },
                        "phone": {
                          "type": "string"
                        },
                        "addressoneline": {
                          "type": "string"
                        },
                        "longitude": {
                          "type": "number"
                        },
                        "latitude": {
                          "type": "number"
                        },
                        "city": {
                          "type": "string"
                        },
                        "state": {
                          "type": "string"
                        },
                        "country": {
                          "type": "string"
                        },
                        "postalcode": {
                          "type": "string"
                        },
                        "bio": {
                          "type": "string"
                        },
                        "maxTravelTime": {
                          "type": "number"
                        },
                        "externalId": {
                          "type": "string"
                        },
                        "externalData": {
                          "type": "object",
                          "additionalProperties": {
                            "nullable": true
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "updatedAt": {
                          "type": "string"
                        },
                        "timezone": {
                          "type": "string",
                          "description": "The supplier's own IANA timezone. Absent when none is set on the profile, in which case fall back to the project's default timezone rather than the caller's. Every `*Local` time this API renders for this supplier is in this zone.",
                          "example": "America/Toronto"
                        },
                        "avatarUrl": {
                          "type": "string",
                          "nullable": true,
                          "format": "uri"
                        },
                        "services": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "serviceId": {
                                "type": "string"
                              },
                              "name": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              }
                            },
                            "required": ["serviceId", "name"]
                          }
                        },
                        "skills": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "skillId": {
                                "type": "string"
                              },
                              "name": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              }
                            },
                            "required": ["skillId", "name"]
                          }
                        },
                        "locations": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "locationId": {
                                "type": "string"
                              },
                              "locationType": {
                                "type": "string",
                                "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"]
                              },
                              "name": {
                                "type": "string"
                              },
                              "country": {
                                "type": "string",
                                "nullable": true
                              },
                              "state": {
                                "type": "string",
                                "nullable": true
                              },
                              "city": {
                                "type": "string",
                                "nullable": true
                              },
                              "addressOneLine": {
                                "type": "string",
                                "nullable": true
                              },
                              "street": {
                                "type": "string",
                                "nullable": true
                              },
                              "latitude": {
                                "type": "number",
                                "nullable": true
                              },
                              "longitude": {
                                "type": "number",
                                "nullable": true
                              },
                              "travelZoneType": {
                                "type": "string",
                                "nullable": true,
                                "enum": ["CIRCULAR", "DRAWN", null]
                              }
                            },
                            "required": ["locationId", "locationType", "name"]
                          }
                        },
                        "servedRegions": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The region paths this supplier is indexed under — the SAME set the `country`/`state`/`city` filter on `GET /suppliers` matches against, so a supplier is returned by that filter exactly when the query's path is in this list. Slug paths at every hierarchy level, sorted: `ca/`, `ca/on/`, `ca/on/toronto/`, `ca/on/scarborough/`. Derived from the travel zones and physical locations on their live schedules (see `locations`), resolved to the locality, its borough and the wider municipality. Empty when the supplier has no live schedule with a geocodable zone. Region rows are pruned by a daily sweep, so this can lag a schedule's `endDate` by up to a day, whereas `locations` is evaluated on every request.",
                          "example": [
                            "ca/",
                            "ca/on/",
                            "ca/on/scarborough/",
                            "ca/on/toronto/"
                          ]
                        },
                        "languages": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "locales": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "defaultLocale": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "supplierId",
                        "firstName",
                        "lastName",
                        "email",
                        "active",
                        "updatedAt",
                        "avatarUrl",
                        "services",
                        "skills",
                        "locations",
                        "servedRegions",
                        "languages",
                        "locales"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Unknown service id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Supplier not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Suppliers"],
        "summary": "Remove a service from a supplier",
        "description": "Stops this supplier being offered for this service in availability searches. The mapping is hard-deleted, not soft-deleted, so re-adding it later creates a fresh mapping with no memory of the old one. Idempotent and forgiving: removing a mapping that was never there still returns 204, so a 204 is not evidence the mapping existed. Bookings already made against this supplier for the service are untouched and still stand — this only affects future matching.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The supplier — the person or resource delivering the service.",
              "example": "sup_01kv60qh1k5xylm7r0c1qj8zpa"
            },
            "required": true,
            "description": "The supplier — the person or resource delivering the service.",
            "name": "supplierId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
              "example": "srv_01kv60qg12e82acr78edfnjhvv"
            },
            "required": true,
            "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
            "name": "serviceId",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Removed"
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Supplier not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/{supplierId}/skills/{skillId}": {
      "post": {
        "tags": ["Suppliers"],
        "summary": "Add a skill to a supplier",
        "description": "Grants the supplier a skill. Skills gate offerings rather than services: an offering that lists `skillIds` can only be performed by suppliers holding all of them, so a supplier mapped to the right service can still be invisible in availability if a skill is missing — check here first when a supplier you expect does not come back from a slot search. Idempotent, and an unknown `skillId` is a 400. Returns the full enriched supplier. To set the whole skill set at once, send `skillIds` to PUT /suppliers/{supplierId}.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The supplier — the person or resource delivering the service.",
              "example": "sup_01kv60qh1k5xylm7r0c1qj8zpa"
            },
            "required": true,
            "description": "The supplier — the person or resource delivering the service.",
            "name": "supplierId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "A skill a supplier can hold, used to match suppliers to services.",
              "example": "skl_01kv60qgw8n3vlm5q9c0hj7ypx"
            },
            "required": true,
            "description": "A skill a supplier can hold, used to match suppliers to services.",
            "name": "skillId",
            "in": "path"
          }
        ],
        "responses": {
          "201": {
            "description": "Supplier with the skill added",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "supplierId": {
                          "type": "string"
                        },
                        "firstName": {
                          "type": "string"
                        },
                        "lastName": {
                          "type": "string"
                        },
                        "email": {
                          "type": "string"
                        },
                        "phone": {
                          "type": "string"
                        },
                        "addressoneline": {
                          "type": "string"
                        },
                        "longitude": {
                          "type": "number"
                        },
                        "latitude": {
                          "type": "number"
                        },
                        "city": {
                          "type": "string"
                        },
                        "state": {
                          "type": "string"
                        },
                        "country": {
                          "type": "string"
                        },
                        "postalcode": {
                          "type": "string"
                        },
                        "bio": {
                          "type": "string"
                        },
                        "maxTravelTime": {
                          "type": "number"
                        },
                        "externalId": {
                          "type": "string"
                        },
                        "externalData": {
                          "type": "object",
                          "additionalProperties": {
                            "nullable": true
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "updatedAt": {
                          "type": "string"
                        },
                        "timezone": {
                          "type": "string",
                          "description": "The supplier's own IANA timezone. Absent when none is set on the profile, in which case fall back to the project's default timezone rather than the caller's. Every `*Local` time this API renders for this supplier is in this zone.",
                          "example": "America/Toronto"
                        },
                        "avatarUrl": {
                          "type": "string",
                          "nullable": true,
                          "format": "uri"
                        },
                        "services": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "serviceId": {
                                "type": "string"
                              },
                              "name": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              }
                            },
                            "required": ["serviceId", "name"]
                          }
                        },
                        "skills": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "skillId": {
                                "type": "string"
                              },
                              "name": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              }
                            },
                            "required": ["skillId", "name"]
                          }
                        },
                        "locations": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "locationId": {
                                "type": "string"
                              },
                              "locationType": {
                                "type": "string",
                                "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"]
                              },
                              "name": {
                                "type": "string"
                              },
                              "country": {
                                "type": "string",
                                "nullable": true
                              },
                              "state": {
                                "type": "string",
                                "nullable": true
                              },
                              "city": {
                                "type": "string",
                                "nullable": true
                              },
                              "addressOneLine": {
                                "type": "string",
                                "nullable": true
                              },
                              "street": {
                                "type": "string",
                                "nullable": true
                              },
                              "latitude": {
                                "type": "number",
                                "nullable": true
                              },
                              "longitude": {
                                "type": "number",
                                "nullable": true
                              },
                              "travelZoneType": {
                                "type": "string",
                                "nullable": true,
                                "enum": ["CIRCULAR", "DRAWN", null]
                              }
                            },
                            "required": ["locationId", "locationType", "name"]
                          }
                        },
                        "servedRegions": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The region paths this supplier is indexed under — the SAME set the `country`/`state`/`city` filter on `GET /suppliers` matches against, so a supplier is returned by that filter exactly when the query's path is in this list. Slug paths at every hierarchy level, sorted: `ca/`, `ca/on/`, `ca/on/toronto/`, `ca/on/scarborough/`. Derived from the travel zones and physical locations on their live schedules (see `locations`), resolved to the locality, its borough and the wider municipality. Empty when the supplier has no live schedule with a geocodable zone. Region rows are pruned by a daily sweep, so this can lag a schedule's `endDate` by up to a day, whereas `locations` is evaluated on every request.",
                          "example": [
                            "ca/",
                            "ca/on/",
                            "ca/on/scarborough/",
                            "ca/on/toronto/"
                          ]
                        },
                        "languages": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "locales": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "defaultLocale": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "supplierId",
                        "firstName",
                        "lastName",
                        "email",
                        "active",
                        "updatedAt",
                        "avatarUrl",
                        "services",
                        "skills",
                        "locations",
                        "servedRegions",
                        "languages",
                        "locales"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Unknown skill id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Supplier not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Suppliers"],
        "summary": "Remove a skill from a supplier",
        "description": "Revokes a skill, narrowing which offerings this supplier can be matched to. Expect the supplier to drop out of availability for every offering that required it, which is often more than the one you had in mind — list the supplier first if you want to see what they currently hold. The mapping is hard-deleted, and removing one that is not there still returns 204, so the status code says nothing about whether anything changed. Bookings already placed are unaffected.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The supplier — the person or resource delivering the service.",
              "example": "sup_01kv60qh1k5xylm7r0c1qj8zpa"
            },
            "required": true,
            "description": "The supplier — the person or resource delivering the service.",
            "name": "supplierId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "A skill a supplier can hold, used to match suppliers to services.",
              "example": "skl_01kv60qgw8n3vlm5q9c0hj7ypx"
            },
            "required": true,
            "description": "A skill a supplier can hold, used to match suppliers to services.",
            "name": "skillId",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Removed"
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Supplier not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/{supplierId}/avatar/upload-url": {
      "post": {
        "tags": ["Suppliers"],
        "summary": "Get a presigned URL to upload a supplier avatar",
        "description": "Step 1 of 2. The image never passes through this API: you get back a short-lived URL and PUT the bytes straight to storage, then call PUT /suppliers/{supplierId}/avatar with the `variantId` returned here to attach the result.\n\nSend exactly the `headers` map you get back and nothing else. The routing metadata is signed into the URL query string, so adding `x-amz-meta-*` headers of your own makes the upload fail with a 403 that looks like a permissions problem and is not. The URL expires in 5 minutes — presign immediately before uploading, not while the user is still choosing a file. `contentType` must be image/jpeg, image/png or image/webp, and `contentLength` must be the real byte length, above zero and at most 5 MB; anything else is a 400 here rather than a failure at upload time.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The supplier — the person or resource delivering the service.",
              "example": "sup_01kv60qh1k5xylm7r0c1qj8zpa"
            },
            "required": true,
            "description": "The supplier — the person or resource delivering the service.",
            "name": "supplierId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Upload metadata",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "contentType": {
                    "type": "string",
                    "enum": ["image/jpeg", "image/png", "image/webp"]
                  },
                  "contentLength": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "maximum": 5242880
                  }
                },
                "required": ["contentType", "contentLength"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Presigned upload",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "uploadId": {
                          "type": "string"
                        },
                        "variantId": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string",
                          "format": "uri"
                        },
                        "method": {
                          "type": "string",
                          "enum": ["PUT"]
                        },
                        "headers": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "expiresIn": {
                          "type": "integer",
                          "minimum": 0,
                          "exclusiveMinimum": true
                        }
                      },
                      "required": [
                        "uploadId",
                        "variantId",
                        "url",
                        "method",
                        "headers",
                        "expiresIn"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid content type or size",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Supplier not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/{supplierId}/avatar": {
      "put": {
        "tags": ["Suppliers"],
        "summary": "Confirm an uploaded avatar and attach it to the supplier",
        "description": "Step 2 of 2: attaches the uploaded image to the supplier and returns the enriched supplier with its new avatar. Pass the `variantId` from the presign response, not the `uploadId`.\n\nResizing happens asynchronously after your upload lands, so calling this straight away often returns 400 \"Avatar variant not ready yet\". That is a retry signal, not a failure — back off a second or two and call again; the upload is fine. Only a successful call here attaches anything, so an upload that is never confirmed leaves the supplier unchanged. Confirming a different `variantId` replaces the current avatar and deletes the old image variants, which cannot be undone; re-confirming the same one is harmless.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The supplier — the person or resource delivering the service.",
              "example": "sup_01kv60qh1k5xylm7r0c1qj8zpa"
            },
            "required": true,
            "description": "The supplier — the person or resource delivering the service.",
            "name": "supplierId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Confirm payload",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "uploadId": {
                    "type": "string"
                  },
                  "variantId": {
                    "type": "string"
                  }
                },
                "required": ["uploadId", "variantId"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Supplier with avatar attached",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "supplierId": {
                          "type": "string"
                        },
                        "firstName": {
                          "type": "string"
                        },
                        "lastName": {
                          "type": "string"
                        },
                        "email": {
                          "type": "string"
                        },
                        "phone": {
                          "type": "string"
                        },
                        "addressoneline": {
                          "type": "string"
                        },
                        "longitude": {
                          "type": "number"
                        },
                        "latitude": {
                          "type": "number"
                        },
                        "city": {
                          "type": "string"
                        },
                        "state": {
                          "type": "string"
                        },
                        "country": {
                          "type": "string"
                        },
                        "postalcode": {
                          "type": "string"
                        },
                        "bio": {
                          "type": "string"
                        },
                        "maxTravelTime": {
                          "type": "number"
                        },
                        "externalId": {
                          "type": "string"
                        },
                        "externalData": {
                          "type": "object",
                          "additionalProperties": {
                            "nullable": true
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "updatedAt": {
                          "type": "string"
                        },
                        "timezone": {
                          "type": "string",
                          "description": "The supplier's own IANA timezone. Absent when none is set on the profile, in which case fall back to the project's default timezone rather than the caller's. Every `*Local` time this API renders for this supplier is in this zone.",
                          "example": "America/Toronto"
                        },
                        "avatarUrl": {
                          "type": "string",
                          "nullable": true,
                          "format": "uri"
                        },
                        "services": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "serviceId": {
                                "type": "string"
                              },
                              "name": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              }
                            },
                            "required": ["serviceId", "name"]
                          }
                        },
                        "skills": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "skillId": {
                                "type": "string"
                              },
                              "name": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              }
                            },
                            "required": ["skillId", "name"]
                          }
                        },
                        "locations": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "locationId": {
                                "type": "string"
                              },
                              "locationType": {
                                "type": "string",
                                "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"]
                              },
                              "name": {
                                "type": "string"
                              },
                              "country": {
                                "type": "string",
                                "nullable": true
                              },
                              "state": {
                                "type": "string",
                                "nullable": true
                              },
                              "city": {
                                "type": "string",
                                "nullable": true
                              },
                              "addressOneLine": {
                                "type": "string",
                                "nullable": true
                              },
                              "street": {
                                "type": "string",
                                "nullable": true
                              },
                              "latitude": {
                                "type": "number",
                                "nullable": true
                              },
                              "longitude": {
                                "type": "number",
                                "nullable": true
                              },
                              "travelZoneType": {
                                "type": "string",
                                "nullable": true,
                                "enum": ["CIRCULAR", "DRAWN", null]
                              }
                            },
                            "required": ["locationId", "locationType", "name"]
                          }
                        },
                        "servedRegions": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The region paths this supplier is indexed under — the SAME set the `country`/`state`/`city` filter on `GET /suppliers` matches against, so a supplier is returned by that filter exactly when the query's path is in this list. Slug paths at every hierarchy level, sorted: `ca/`, `ca/on/`, `ca/on/toronto/`, `ca/on/scarborough/`. Derived from the travel zones and physical locations on their live schedules (see `locations`), resolved to the locality, its borough and the wider municipality. Empty when the supplier has no live schedule with a geocodable zone. Region rows are pruned by a daily sweep, so this can lag a schedule's `endDate` by up to a day, whereas `locations` is evaluated on every request.",
                          "example": [
                            "ca/",
                            "ca/on/",
                            "ca/on/scarborough/",
                            "ca/on/toronto/"
                          ]
                        },
                        "languages": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "locales": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "defaultLocale": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "supplierId",
                        "firstName",
                        "lastName",
                        "email",
                        "active",
                        "updatedAt",
                        "avatarUrl",
                        "services",
                        "skills",
                        "locations",
                        "servedRegions",
                        "languages",
                        "locales"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Variant not ready yet — retry shortly",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Supplier not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "The photo changed while this request was being saved, by another confirm or remove (CONFLICT): read the supplier again and retry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Suppliers"],
        "summary": "Remove a supplier's avatar",
        "description": "Clears the avatar reference and deletes the stored image variants. Both the reference and the images are gone for good, so restoring the same picture means uploading it again through the presign flow. Returns 204 whether or not the supplier had an avatar, so use it freely without a prior read — but do not read the 204 as proof one was removed. To swap an avatar, skip this and confirm the new one directly; that replaces the old image in a single step and leaves no window where the supplier has none.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The supplier — the person or resource delivering the service.",
              "example": "sup_01kv60qh1k5xylm7r0c1qj8zpa"
            },
            "required": true,
            "description": "The supplier — the person or resource delivering the service.",
            "name": "supplierId",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Avatar removed"
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Supplier not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "The photo changed while this request was being saved, by another confirm or remove (CONFLICT): read the supplier again and retry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/reviews": {
      "post": {
        "tags": ["Reviews"],
        "summary": "Create a supplier review (1–5 star rating with optional comment)",
        "description": "Records a rating against a supplier and folds it into that supplier's running average in the same atomic write, so the aggregate never disagrees with the rows behind it.\n\nTreat this as permanent. There is no update or delete route, so a review posted by mistake moves the supplier's average for good — validate on your side before calling. Nothing is deduplicated and no booking is required: the same reviewer can post repeatedly, and each submission counts again, so enforce \"one review per completed booking\" yourself if that is your intent. `reviewerId` is optional and stored as given; it is not authenticated or checked against the client who was served.\n\n`bookingId` is optional and links the review to a booking. Supplying it stops MarketBox's rating follow-up emails for that booking — omit it and the client keeps being nudged to rate a booking they have already reviewed. It is stored as given and is **not** validated: an id that does not exist, or belongs to another project or another client, is accepted and simply links to nothing. It does not deduplicate either — two reviews carrying the same `bookingId` both count.\n\n`ratingStars` must be a whole number from 1 to 5, and `reviewText` is optional and capped at 5000 characters. The supplier must exist in this project, or 404.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Review data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "supplierId": {
                    "type": "string",
                    "minLength": 1
                  },
                  "ratingStars": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 5
                  },
                  "reviewText": {
                    "type": "string",
                    "maxLength": 5000
                  },
                  "reviewerId": {
                    "type": "string"
                  },
                  "bookingId": {
                    "type": "string",
                    "description": "Optional booking this review is about. Supplying it links the review to that booking and stops the rating follow-up emails for it. Stored as given and not validated against the booking, and it does not deduplicate.",
                    "example": "bk_01kv60qge5eh59ap0gw0pqrrys"
                  }
                },
                "required": ["supplierId", "ratingStars"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Review created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "reviewId": {
                          "type": "string"
                        },
                        "supplierId": {
                          "type": "string"
                        },
                        "clientId": {
                          "type": "string"
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "ratingStars": {
                          "type": "integer"
                        },
                        "reviewText": {
                          "type": "string"
                        },
                        "reviewerId": {
                          "type": "string"
                        },
                        "bookingId": {
                          "type": "string"
                        },
                        "direction": {
                          "type": "string",
                          "enum": ["CLIENT_TO_SUPPLIER", "SUPPLIER_TO_CLIENT"]
                        },
                        "subjectType": {
                          "type": "string",
                          "enum": ["SUPPLIER", "CLIENT"]
                        },
                        "subjectId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "supplierName": {
                          "type": "string"
                        },
                        "clientName": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "reviewId",
                        "supplierId",
                        "projectId",
                        "ratingStars",
                        "direction",
                        "subjectType",
                        "subjectId",
                        "createdAt"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Supplier not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": ["Reviews"],
        "summary": "List reviews for a project (newest first); filter by supplier",
        "description": "Reviews newest-first, either across the project or for one supplier via `supplierId`. This returns individual reviews only. The running average maintained when a review is created is not exposed by this API, and no supplier field carries it, so a star rating has to be computed here — which means walking every page for that supplier, not averaging the first one. Paginated with an opaque cursor that stays valid only while the filter is unchanged. Unlike creating a review, an unknown `supplierId` is not rejected here — it simply returns an empty page, so an empty result does not confirm the id was right.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50,
              "description": "Maximum rows to return in `data`, 1–200. Defaults to 50. Values outside the range return 400. A page can still hold fewer rows than requested, so treat `nextCursor: null` as the only end-of-results signal and never stop on a page that merely looks short.",
              "example": 50
            },
            "required": false,
            "description": "Maximum rows to return in `data`, 1–200. Defaults to 50. Values outside the range return 400. A page can still hold fewer rows than requested, so treat `nextCursor: null` as the only end-of-results signal and never stop on a page that merely looks short.",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Opaque pagination token from a previous response's `nextCursor`. Treat it as a magic string — never parse or construct one. A cursor is only valid for the same filters that produced it, and `nextCursor: null` means the last page."
            },
            "required": false,
            "description": "Opaque pagination token from a previous response's `nextCursor`. Treat it as a magic string — never parse or construct one. A cursor is only valid for the same filters that produced it, and `nextCursor: null` means the last page.",
            "name": "cursor",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Restrict results to reviews of this supplier. Omit to list all project reviews."
            },
            "required": false,
            "description": "Restrict results to reviews of this supplier. Omit to list all project reviews.",
            "name": "supplierId",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Reviews list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "reviewId": {
                            "type": "string"
                          },
                          "supplierId": {
                            "type": "string"
                          },
                          "clientId": {
                            "type": "string"
                          },
                          "projectId": {
                            "type": "string"
                          },
                          "ratingStars": {
                            "type": "integer"
                          },
                          "reviewText": {
                            "type": "string"
                          },
                          "reviewerId": {
                            "type": "string"
                          },
                          "bookingId": {
                            "type": "string"
                          },
                          "direction": {
                            "type": "string",
                            "enum": ["CLIENT_TO_SUPPLIER", "SUPPLIER_TO_CLIENT"]
                          },
                          "subjectType": {
                            "type": "string",
                            "enum": ["SUPPLIER", "CLIENT"]
                          },
                          "subjectId": {
                            "type": "string"
                          },
                          "createdAt": {
                            "type": "string"
                          },
                          "supplierName": {
                            "type": "string"
                          },
                          "clientName": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "reviewId",
                          "supplierId",
                          "projectId",
                          "ratingStars",
                          "direction",
                          "subjectType",
                          "subjectId",
                          "createdAt"
                        ]
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": ["data", "nextCursor"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid cursor or limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/clients/{clientId}/reviews": {
      "get": {
        "tags": ["Reviews"],
        "summary": "List the reviews written about a client",
        "description": "Reviews **of** this client — the ones suppliers wrote about them — newest first. It is not the reviews this client wrote; those are reviews of a supplier and are read through `GET /reviews?supplierId=…`. Only `SUPPLIER_TO_CLIENT` reviews appear here, so every row has this client as its `subjectId`.\n\nPaginated with `limit` and an opaque `cursor`; `nextCursor: null` is the only end-of-results signal, and a cursor is valid only for the filters that produced it. Each row carries best-effort `supplierName` / `clientName` merged in from the two profiles, so a page renders without further calls; a counterparty that cannot be resolved keeps its bare id and those fields are absent. No email address is returned for either party.\n\nA client that does not exist in this project returns 404 rather than an empty page, so an empty `data` genuinely means \"nobody has reviewed this client yet\".",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The client — the person the booking is for.",
              "example": "cli_01kv6r83j9fmquwl81xkm5bwj6"
            },
            "required": true,
            "description": "The client — the person the booking is for.",
            "name": "clientId",
            "in": "path"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50,
              "description": "Maximum rows to return in `data`, 1–200. Defaults to 50. Values outside the range return 400. A page can still hold fewer rows than requested, so treat `nextCursor: null` as the only end-of-results signal and never stop on a page that merely looks short.",
              "example": 50
            },
            "required": false,
            "description": "Maximum rows to return in `data`, 1–200. Defaults to 50. Values outside the range return 400. A page can still hold fewer rows than requested, so treat `nextCursor: null` as the only end-of-results signal and never stop on a page that merely looks short.",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Opaque pagination token from a previous response's `nextCursor`. Treat it as a magic string — never parse or construct one. A cursor is only valid for the same filters that produced it, and `nextCursor: null` means the last page."
            },
            "required": false,
            "description": "Opaque pagination token from a previous response's `nextCursor`. Treat it as a magic string — never parse or construct one. A cursor is only valid for the same filters that produced it, and `nextCursor: null` means the last page.",
            "name": "cursor",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Reviews of the client",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "reviewId": {
                            "type": "string"
                          },
                          "supplierId": {
                            "type": "string"
                          },
                          "clientId": {
                            "type": "string"
                          },
                          "projectId": {
                            "type": "string"
                          },
                          "ratingStars": {
                            "type": "integer"
                          },
                          "reviewText": {
                            "type": "string"
                          },
                          "reviewerId": {
                            "type": "string"
                          },
                          "bookingId": {
                            "type": "string"
                          },
                          "direction": {
                            "type": "string",
                            "enum": ["CLIENT_TO_SUPPLIER", "SUPPLIER_TO_CLIENT"]
                          },
                          "subjectType": {
                            "type": "string",
                            "enum": ["SUPPLIER", "CLIENT"]
                          },
                          "subjectId": {
                            "type": "string"
                          },
                          "createdAt": {
                            "type": "string"
                          },
                          "supplierName": {
                            "type": "string"
                          },
                          "clientName": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "reviewId",
                          "supplierId",
                          "projectId",
                          "ratingStars",
                          "direction",
                          "subjectType",
                          "subjectId",
                          "createdAt"
                        ]
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": ["data", "nextCursor"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid cursor or limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Client not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/clients/{clientId}/review-summary": {
      "get": {
        "tags": ["Reviews"],
        "summary": "Get a client's average rating and review count",
        "description": "The running average of the reviews suppliers have written about this client, maintained at write time rather than computed on read — so it never disagrees with the rows behind it and does not require walking `GET /clients/{clientId}/reviews`.\n\n`averageRating` is rounded to one decimal place. A client nobody has reviewed returns `averageRating: 0` and `reviewCount: 0`, **not** 404 — \"unrated\" and \"does not exist\" are different answers, and a 404 here means the client id is unknown in this project.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The client — the person the booking is for.",
              "example": "cli_01kv6r83j9fmquwl81xkm5bwj6"
            },
            "required": true,
            "description": "The client — the person the booking is for.",
            "name": "clientId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Client rating summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "clientId": {
                          "type": "string"
                        },
                        "averageRating": {
                          "type": "number"
                        },
                        "reviewCount": {
                          "type": "integer"
                        }
                      },
                      "required": ["clientId", "averageRating", "reviewCount"]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Client not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suppliers/{supplierId}/review-summary": {
      "get": {
        "tags": ["Reviews"],
        "summary": "Get a supplier's average rating and review count",
        "description": "This supplier's star rating and how many reviews it is based on, read from the aggregate maintained in the same atomic write that records each review.\n\nThis is the endpoint to use for a rating badge. `GET /reviews?supplierId=…` returns individual reviews and exposes no average, so computing a rating from it means paging through every review that supplier has ever received — averaging the first page gives a wrong number. That is no longer necessary.\n\n`averageRating` is rounded to one decimal place. A supplier nobody has reviewed returns `averageRating: 0` and `reviewCount: 0`, **not** 404 — a 404 here means the supplier id is unknown in this project.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The supplier — the person or resource delivering the service.",
              "example": "sup_01kv60qh1k5xylm7r0c1qj8zpa"
            },
            "required": true,
            "description": "The supplier — the person or resource delivering the service.",
            "name": "supplierId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Supplier rating summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "supplierId": {
                          "type": "string"
                        },
                        "averageRating": {
                          "type": "number"
                        },
                        "reviewCount": {
                          "type": "integer"
                        }
                      },
                      "required": ["supplierId", "averageRating", "reviewCount"]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Supplier not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/availability/search": {
      "post": {
        "tags": ["Availability"],
        "summary": "Find suppliers + suggested/open slots for a service, location and window",
        "description": "The main \"when can this be booked\" call. Returns two parallel, slot-centric arrays: `timeSlots`, the engine's ranked suggestions with travel between jobs taken into account, and `openSlots`, every free interval at `interval` granularity with no ranking. Show `timeSlots` to clients and keep `openSlots` for a \"more times\" view; they overlap by design. Identify the place with `locationId`, or with both `lat` and `lng` for in-home and travel-zone discovery — one or the other is required. `durationMinutes` is honoured only for FLEXIBLE offerings and is otherwise ignored in favour of the offering's own duration.\n\nFailures come back inside a 200. The body carries `status` and an `errors` array, so an empty `timeSlots` with a non-empty `errors` means the search broke, not that nobody is free — check `errors` before telling a client there is no availability.\n\nSetting `bookingType: \"recurring\"` changes what `timeSlots` contains: recurring time patterns rather than individual slots, so do not parse the two the same way. That branch adds two requirements, each a 400 and each guarding an input that used to return silence instead of an error — `rrule` is required, and it must carry a bounded positive COUNT (e.g. \"FREQ=WEEKLY;BYDAY=TU;COUNT=3\"). `lookAheadStartDate` is any ISO-8601 instant: a \"Z\" suffix and a numeric offset like \"-04:00\" are equally valid.\n\nEvery response carries a `searchId` (also the `X-MB-Search-Id` header) and `suppliers`, each supplier that appears in the slots with its 0-based `position` by first appearance. Keep `searchId` for the session if you want attribution. Two optional request headers tag the search for insights and are never acted on: `X-MB-Session-Key` (an opaque key you choose, up to 64 characters) and `X-MB-Client-Kind` (`browser`, `server`, `monitor` or `loadtest`).",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Service + location + window",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string",
                    "minLength": 1
                  },
                  "offeringId": {
                    "type": "string",
                    "minLength": 1
                  },
                  "locationId": {
                    "type": "string"
                  },
                  "lat": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "number"
                      }
                    ]
                  },
                  "lng": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "number"
                      }
                    ]
                  },
                  "durationMinutes": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true
                  },
                  "lookAheadStartDate": {
                    "type": "string"
                  },
                  "lookAheadDays": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true
                  },
                  "timezone": {
                    "type": "string",
                    "minLength": 1
                  },
                  "distanceUnit": {
                    "type": "string",
                    "enum": ["km", "mi"]
                  },
                  "order": {
                    "type": "string",
                    "nullable": true,
                    "enum": ["mustBeFirst", "mustBeLast", null]
                  },
                  "preferredDays": {
                    "type": "array",
                    "nullable": true,
                    "items": {
                      "type": "integer"
                    }
                  },
                  "preferredTimes": {
                    "type": "array",
                    "nullable": true,
                    "items": {
                      "type": "object",
                      "properties": {
                        "startTime": {
                          "type": "string"
                        },
                        "endTime": {
                          "type": "string"
                        }
                      },
                      "required": ["startTime", "endTime"]
                    }
                  },
                  "emptyDayAnchorTime": {
                    "type": "string",
                    "nullable": true
                  },
                  "maxNumberOfBookingsPerDay": {
                    "type": "integer",
                    "nullable": true,
                    "minimum": 0,
                    "exclusiveMinimum": true
                  },
                  "preferredTimeSlotThresholdMins": {
                    "type": "integer",
                    "minimum": 0
                  },
                  "timeSuggestionsLimit": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true
                  },
                  "sortBy": {
                    "type": "string",
                    "enum": ["leastTravelTime", "nearestDate"]
                  },
                  "skills": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1
                    },
                    "description": "Supplier skill IDs. A supplier must hold ALL of them to be considered. Omit for no skill filter.",
                    "example": ["skl_01kv60qg12e82acr78edfnjhvv"]
                  },
                  "interval": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true
                  },
                  "language": {
                    "type": "string",
                    "description": "Preferred language for localized skill and offering NAMES. Not a filter — it never affects which suppliers or services match, and has no effect on this response."
                  },
                  "bookingType": {
                    "type": "string",
                    "enum": ["single", "recurring"],
                    "default": "single"
                  },
                  "rrule": {
                    "type": "string"
                  },
                  "endDate": {
                    "type": "string"
                  },
                  "daysOfWeek": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 6
                    }
                  },
                  "package": {
                    "type": "boolean"
                  },
                  "consistencyAsPercentage": {
                    "type": "boolean"
                  },
                  "fromMb": {
                    "type": "boolean"
                  }
                },
                "required": ["serviceId", "offeringId"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Suggested slots + open slots",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "searchId": {
                      "type": "string",
                      "description": "The id of this search, also returned as the `X-MB-Search-Id` header. Every page of a paginated search carries the same id (the cursor keeps it). Keep it for the session if you want attribution: pass it back as `searchId` when the client books, and in the `search.rendered` event when you report what you showed.",
                      "example": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
                    },
                    "status": {
                      "type": "string"
                    },
                    "timeSlots": {
                      "type": "array",
                      "items": {
                        "nullable": true
                      },
                      "description": "Suggested slots, or recurring time patterns when bookingType=recurring. Each entry carries `timeSlotDateAndTime` (the slot instant rendered in the response `timezone`, with that zone's offset at that instant — R-30) and `timeSlotStartUtc` (the same instant in UTC, `Z` — R-31, always present, always the same instant as `timeSlotDateAndTime`). Prefer `timeSlotStartUtc` as the booking anchor."
                    },
                    "openSlots": {
                      "type": "array",
                      "items": {
                        "nullable": true
                      },
                      "description": "Every free interval at `interval` granularity, unranked. Each entry carries `timeSlotDateAndTime` (the slot instant rendered in the response `timezone`, with that zone's offset at that instant — R-30) and `timeSlotStartUtc` (the same instant in UTC, `Z` — R-31, always present, always the same instant as `timeSlotDateAndTime`). Prefer `timeSlotStartUtc` as the booking anchor."
                    },
                    "timezone": {
                      "type": "string",
                      "description": "The IANA timezone actually used to render `timeSlotDateAndTime` and bucket days (R-32) — the request `timezone`, or the project default.",
                      "example": "America/Chicago"
                    },
                    "supplierZones": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      },
                      "description": "IANA profile zone of each supplier that appears in `timeSlots`/`openSlots`, keyed by supplierId. Use it as the R-10 fallback for `bookingTz` on a virtual booking (location zone wins when there is one). Absent key = the supplier has no profile zone; use the project default.",
                      "example": {
                        "sup_01abc": "America/Toronto"
                      }
                    },
                    "engineEnabled": {
                      "type": "boolean",
                      "description": "False when Smart Clusters is switched off for this project. The engine then does not run, so `timeSlots` is empty because it was not computed, not because nobody is free; `openSlots` is unaffected. Check it before telling a client there is no availability.",
                      "example": true
                    },
                    "suppliers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "supplierId": {
                            "type": "string",
                            "example": "sup_01kv60qh3m7wznp8s0d2rk9abc"
                          },
                          "position": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "0-based rank of this entry in the order the response returned it. Paged results continue the count across pages of the same `searchId`, so the first entry of page 2 is numbered after the last of page 1.",
                            "example": 0
                          }
                        },
                        "required": ["supplierId", "position"],
                        "description": "Each supplier that appears in `timeSlots` or `openSlots`, with its `position` — the 0-based rank of its FIRST slot in the returned order (`timeSlots` first, then `openSlots`). Ordered by position. The shape `search.rendered` takes."
                      }
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "searchId",
                    "status",
                    "timeSlots",
                    "openSlots",
                    "suppliers",
                    "errors"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "No offering for this serviceId/offeringId, or no location for this locationId (sent without lat/lng); the message names the id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/availability/time-slots": {
      "post": {
        "tags": ["Availability"],
        "summary": "Generate clustered time slots from suppliers + engine config",
        "description": "Runs the clustering engine directly on suppliers and a config YOU supply. Nothing is read from the project — not the catalogue, not the supplier roster, not existing bookings — so this answers \"what would the engine do with these inputs\", not \"when is this bookable\". The supplier availability you pass is taken at face value, which means it will happily return slots for people who are already booked; never drive a booking flow from it. Use /availability/search, or /availability/suppliers for a supplier-centric view, for anything a client sees.\n\nIt exists for tuning and diagnosis: `metrics` and `kpis` in the response let you compare configs against a fixed input set, and replaying a captured payload reproduces a result (see the note on `metrics` below for when it does not). `config` is passed through to the engine largely unvalidated, so a malformed knob tends to surface as poor output or an entry in `errors` rather than a 400 — and as with the other availability routes, `errors` arrives inside a 200.\n\n`metrics.totalTravelTimeRequestsMade` is the number of distinct drives (direction, place) answered for this request, shared across all suppliers; a failed or unroutable drive is not counted.\n\nHistory: counts and slot distances changed on 2026-11-12 (routing in shared rounds). A payload captured before then can replay with different counts, distances and labels, and can gain slots.\n\nThe response carries a `searchId` (also the `X-MB-Search-Id` header) like every search route, but nothing is logged for insights: the suppliers and config are yours, not the project's.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Suppliers + engine config",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "config": {
                    "type": "object",
                    "properties": {},
                    "additionalProperties": {
                      "nullable": true
                    }
                  },
                  "suppliers": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "supplierId": {
                          "type": "string"
                        },
                        "maxTravelTimeMins": {
                          "type": "number"
                        },
                        "bufferTimeMins": {
                          "type": "number"
                        },
                        "availability": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "startDateAndTime": {
                                "type": "string"
                              },
                              "endDateAndTime": {
                                "type": "string"
                              },
                              "rrule": {
                                "type": "string"
                              },
                              "startGeoLocation": {
                                "type": "array",
                                "items": {
                                  "type": "number"
                                },
                                "minItems": 2,
                                "maxItems": 2
                              },
                              "endGeoLocation": {
                                "type": "array",
                                "items": {
                                  "type": "number"
                                },
                                "minItems": 2,
                                "maxItems": 2
                              },
                              "timezone": {
                                "type": "string"
                              }
                            },
                            "required": ["startDateAndTime", "endDateAndTime"]
                          }
                        },
                        "bookings": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "startDateAndTime": {
                                "type": "string"
                              },
                              "durationMins": {
                                "type": "number"
                              },
                              "geoLocation": {
                                "type": "array",
                                "nullable": true,
                                "items": {
                                  "type": "number"
                                },
                                "minItems": 2,
                                "maxItems": 2
                              },
                              "isGeoAnchoring": {
                                "type": "boolean"
                              }
                            },
                            "required": ["startDateAndTime", "durationMins"]
                          }
                        },
                        "blockedTime": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "startDateAndTime": {
                                "type": "string"
                              },
                              "endDateAndTime": {
                                "type": "string"
                              },
                              "rrule": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": ["startDateAndTime", "endDateAndTime"]
                          }
                        },
                        "maxTravelTimeFromStartGeoLocationMins": {
                          "type": "number",
                          "nullable": true
                        },
                        "maxTravelTimeToEndGeoLocationMins": {
                          "type": "number",
                          "nullable": true
                        },
                        "timezone": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "supplierId",
                        "maxTravelTimeMins",
                        "availability"
                      ]
                    }
                  }
                },
                "required": ["config", "suppliers"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Suggested slots + metrics/kpis",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "searchId": {
                      "type": "string",
                      "description": "The id of this search, also returned as the `X-MB-Search-Id` header. Every page of a paginated search carries the same id (the cursor keeps it). Keep it for the session if you want attribution: pass it back as `searchId` when the client books, and in the `search.rendered` event when you report what you showed.",
                      "example": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
                    },
                    "status": {
                      "type": "string"
                    },
                    "timeSlots": {
                      "type": "array",
                      "items": {
                        "nullable": true
                      },
                      "description": "Clustered suggested slots. Each entry carries `timeSlotDateAndTime` (the slot instant rendered in the response `timezone`, with that zone's offset at that instant — R-30) and `timeSlotStartUtc` (the same instant in UTC, `Z` — R-31, always present, always the same instant as `timeSlotDateAndTime`). Prefer `timeSlotStartUtc` as the booking anchor."
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "metrics": {
                      "nullable": true
                    },
                    "kpis": {
                      "nullable": true
                    }
                  },
                  "required": ["searchId", "status", "timeSlots", "errors"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/availability/suppliers": {
      "post": {
        "tags": ["Availability"],
        "summary": "Supplier-centric availability: paginated suppliers, each with open slots grouped by day",
        "description": "Returns availability grouped by supplier — a paginated list of suppliers, each with its full profile (same shape as GET /suppliers) and its open slots bucketed by local day. Use this to render a wall of supplier cards with bookable times, instead of the flat, slot-centric arrays /availability/search returns. Provide serviceId + offeringId and either locationId or both lat and lng. Returns regular-interval open slots only — no clustered/travel-optimized suggestions and no recurring patterns (use /availability/search for those). Suppliers that match the service and location but have no availability in the window are still returned, with days: []. Paginate with limit (max 50) + the opaque cursor; nextCursor is null on the last page. Each slot carries a UTC anchor (startUtc/endUtc) plus *Local strings rendered in the request timezone.\n\nEvery page carries the same `searchId` (also the `X-MB-Search-Id` header; the cursor keeps it) and each supplier its 0-based `position`, continuous across pages. Keep `searchId` for the session if you want attribution. Two optional request headers tag the search for insights and are never acted on: `X-MB-Session-Key` (an opaque key you choose, up to 64 characters) and `X-MB-Client-Kind` (`browser`, `server`, `monitor` or `loadtest`).",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Service + location + window (+ pagination)",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The service to find supplier availability for.",
                    "example": "srv_01kv60qg12e82acr78edfnjhvv"
                  },
                  "offeringId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The specific offering (variant) of the service being booked.",
                    "example": "off_01kv60qge5eh59ap0gw0pqrrys"
                  },
                  "locationId": {
                    "type": "string",
                    "description": "Where the service is delivered. Provide this OR both `lat` and `lng`. A stored location id (PHYSICAL / VIRTUAL / TRAVEL_ZONE).",
                    "example": "loc_01kv60qh3m7wznp8s0d2rk9abc"
                  },
                  "lat": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "number"
                      }
                    ],
                    "description": "Client/service latitude. Provide `lat` + `lng` together as an alternative to `locationId` (in-home / travel-zone discovery).",
                    "example": 41.881832
                  },
                  "lng": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "number"
                      }
                    ],
                    "description": "Client/service longitude — see `lat`.",
                    "example": -87.623177
                  },
                  "durationMinutes": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "description": "Override the booked duration (minutes). Only honoured for FLEXIBLE offerings; otherwise the offering’s own duration is used.",
                    "example": 60
                  },
                  "lookAheadStartDate": {
                    "type": "string",
                    "description": "Start of the search window (ISO-8601). Defaults to now. Slots before this instant are excluded.",
                    "example": "2025-07-07T00:00:00-05:00"
                  },
                  "lookAheadDays": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "description": "How many days forward to search from the start. Defaults to the engine’s configured window.",
                    "example": 7
                  },
                  "timezone": {
                    "type": "string",
                    "minLength": 1,
                    "description": "IANA timezone governing day bucketing and every `*Local` field in the response (R-32). Defaults to the project timezone.",
                    "example": "America/Chicago"
                  },
                  "distanceUnit": {
                    "type": "string",
                    "enum": ["km", "mi"],
                    "description": "Unit for travel/distance calculations.",
                    "example": "km"
                  },
                  "interval": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "description": "Open-slot granularity in minutes (e.g. 15 → :00 / :15 / :30 / :45). Defaults to 15.",
                    "example": 15
                  },
                  "language": {
                    "type": "string",
                    "description": "Preferred language for localized skill and offering NAMES. Not a filter — it never affects which suppliers or services match, and has no effect on this response.",
                    "example": "en"
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 50,
                    "default": 20,
                    "description": "Suppliers per page (1–50, default 20). Kept small because each supplier’s availability is computed on demand.",
                    "example": 20
                  },
                  "cursor": {
                    "type": "string",
                    "description": "Opaque pagination token from a previous response’s `nextCursor`. Omit for the first page."
                  },
                  "preferredTimes": {
                    "type": "array",
                    "nullable": true,
                    "items": {
                      "type": "object",
                      "properties": {
                        "startTime": {
                          "type": "string",
                          "description": "Local time-of-day the window opens (HH:mm).",
                          "example": "17:00"
                        },
                        "endTime": {
                          "type": "string",
                          "description": "Local time-of-day the window closes (HH:mm).",
                          "example": "20:00"
                        }
                      },
                      "required": ["startTime", "endTime"]
                    },
                    "description": "Time-of-day windows the caller would prefer sessions to fall in (e.g. \"after work\"). Feeds the per-supplier match score — a supplier with no availability inside these windows is still returned, just ranked lower. Not a filter: no slot is removed for falling outside them.",
                    "example": [
                      {
                        "startTime": "17:00",
                        "endTime": "20:00"
                      }
                    ]
                  },
                  "daysOfWeek": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 6
                    },
                    "minItems": 1,
                    "maxItems": 7,
                    "description": "Weekdays the caller would prefer sessions to land on (0 = Sunday … 6 = Saturday). On THIS route this is a ranking preference, not a hard filter — unlike the same-named field on /availability/package-slate, a weekday left out of this list is never removed from a supplier's slots; it only lowers that supplier's match score. At least one weekday is required when this field is present — omit the field entirely for \"any day\".",
                    "example": [1, 3, 5]
                  },
                  "excludeDates": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                    },
                    "maxItems": 90,
                    "description": "Local calendar dates (YYYY-MM-DD) that must not carry a session — a holiday, a trip. Matched against each slot's own local calendar date, not against a UTC instant. Pass each date individually; there is no range form.",
                    "example": ["2026-08-20", "2026-08-21", "2026-08-22"]
                  },
                  "sessionsPerWeek": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 14,
                    "description": "How many sessions per week the caller wants to be able to book with this supplier. On this route there is no package and no session count to plan against, so this preference can only ever feed the match score. On package-slate a package supplies a creditCount, giving the planner an actual COUNT to plan sessions against.",
                    "example": 3
                  }
                },
                "required": ["serviceId", "offeringId"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Suppliers, each with open slots grouped by day",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "searchId": {
                      "type": "string",
                      "description": "The id of this search, also returned as the `X-MB-Search-Id` header. Every page of a paginated search carries the same id (the cursor keeps it). Keep it for the session if you want attribution: pass it back as `searchId` when the client books, and in the `search.rendered` event when you report what you showed.",
                      "example": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "supplier": {
                            "type": "object",
                            "properties": {
                              "supplierId": {
                                "type": "string"
                              },
                              "firstName": {
                                "type": "string"
                              },
                              "lastName": {
                                "type": "string"
                              },
                              "email": {
                                "type": "string"
                              },
                              "phone": {
                                "type": "string"
                              },
                              "addressoneline": {
                                "type": "string"
                              },
                              "longitude": {
                                "type": "number"
                              },
                              "latitude": {
                                "type": "number"
                              },
                              "city": {
                                "type": "string"
                              },
                              "state": {
                                "type": "string"
                              },
                              "country": {
                                "type": "string"
                              },
                              "postalcode": {
                                "type": "string"
                              },
                              "bio": {
                                "type": "string"
                              },
                              "maxTravelTime": {
                                "type": "number"
                              },
                              "externalId": {
                                "type": "string"
                              },
                              "externalData": {
                                "type": "object",
                                "additionalProperties": {
                                  "nullable": true
                                }
                              },
                              "active": {
                                "type": "boolean"
                              },
                              "updatedAt": {
                                "type": "string"
                              },
                              "timezone": {
                                "type": "string",
                                "description": "The supplier's own IANA timezone. Absent when none is set on the profile, in which case fall back to the project's default timezone rather than the caller's. Every `*Local` time this API renders for this supplier is in this zone.",
                                "example": "America/Toronto"
                              },
                              "avatarUrl": {
                                "type": "string",
                                "nullable": true,
                                "format": "uri"
                              },
                              "services": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "serviceId": {
                                      "type": "string"
                                    },
                                    "name": {
                                      "type": "object",
                                      "additionalProperties": {
                                        "type": "string"
                                      }
                                    }
                                  },
                                  "required": ["serviceId", "name"]
                                }
                              },
                              "skills": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "skillId": {
                                      "type": "string"
                                    },
                                    "name": {
                                      "type": "object",
                                      "additionalProperties": {
                                        "type": "string"
                                      }
                                    }
                                  },
                                  "required": ["skillId", "name"]
                                }
                              },
                              "locations": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "locationId": {
                                      "type": "string"
                                    },
                                    "locationType": {
                                      "type": "string",
                                      "enum": [
                                        "PHYSICAL",
                                        "VIRTUAL",
                                        "TRAVEL_ZONE"
                                      ]
                                    },
                                    "name": {
                                      "type": "string"
                                    },
                                    "country": {
                                      "type": "string",
                                      "nullable": true
                                    },
                                    "state": {
                                      "type": "string",
                                      "nullable": true
                                    },
                                    "city": {
                                      "type": "string",
                                      "nullable": true
                                    },
                                    "addressOneLine": {
                                      "type": "string",
                                      "nullable": true
                                    },
                                    "street": {
                                      "type": "string",
                                      "nullable": true
                                    },
                                    "latitude": {
                                      "type": "number",
                                      "nullable": true
                                    },
                                    "longitude": {
                                      "type": "number",
                                      "nullable": true
                                    },
                                    "travelZoneType": {
                                      "type": "string",
                                      "nullable": true,
                                      "enum": ["CIRCULAR", "DRAWN", null]
                                    }
                                  },
                                  "required": [
                                    "locationId",
                                    "locationType",
                                    "name"
                                  ]
                                }
                              },
                              "servedRegions": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                },
                                "description": "The region paths this supplier is indexed under — the SAME set the `country`/`state`/`city` filter on `GET /suppliers` matches against, so a supplier is returned by that filter exactly when the query's path is in this list. Slug paths at every hierarchy level, sorted: `ca/`, `ca/on/`, `ca/on/toronto/`, `ca/on/scarborough/`. Derived from the travel zones and physical locations on their live schedules (see `locations`), resolved to the locality, its borough and the wider municipality. Empty when the supplier has no live schedule with a geocodable zone. Region rows are pruned by a daily sweep, so this can lag a schedule's `endDate` by up to a day, whereas `locations` is evaluated on every request.",
                                "example": [
                                  "ca/",
                                  "ca/on/",
                                  "ca/on/scarborough/",
                                  "ca/on/toronto/"
                                ]
                              },
                              "languages": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "locales": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "defaultLocale": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "supplierId",
                              "firstName",
                              "lastName",
                              "email",
                              "active",
                              "updatedAt",
                              "avatarUrl",
                              "services",
                              "skills",
                              "locations",
                              "servedRegions",
                              "languages",
                              "locales"
                            ],
                            "description": "The supplier, in the same enriched shape as `GET /suppliers` (profile, `avatarUrl`, `services`, `skills`, `locations`) — enough to render a card without a follow-up call."
                          },
                          "days": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "date": {
                                  "type": "string",
                                  "description": "Local calendar date (YYYY-MM-DD) in the request `timezone` — the day these slots fall on.",
                                  "example": "2025-07-07"
                                },
                                "slots": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "slotId": {
                                        "type": "string",
                                        "description": "Opaque id for this open slot. A slot is availability, not a hold — book it with the times below; it can be taken by another client until you do.",
                                        "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301"
                                      },
                                      "startUtc": {
                                        "type": "string",
                                        "description": "Slot start as a UTC instant (ISO-8601, Z) — the engine's `timeSlotStartUtc` verbatim (R-31). Prefer this over `startLocal` as the booking start anchor.",
                                        "example": "2025-07-07T14:00:00.000Z"
                                      },
                                      "startLocal": {
                                        "type": "string",
                                        "description": "The slot start as a local clock in the request `timezone`, with that zone's offset at that instant (ISO-8601, R-30) — e.g. `2025-07-07T09:00:00-05:00`. Always denotes the same instant as `startUtc` (the engine's `timeSlotStartUtc`). For display.",
                                        "example": "2025-07-07T09:00:00-05:00"
                                      },
                                      "endUtc": {
                                        "type": "string",
                                        "description": "Slot end (start + the resolved service duration) as a UTC instant.",
                                        "example": "2025-07-07T14:30:00.000Z"
                                      },
                                      "endLocal": {
                                        "type": "string",
                                        "description": "Slot end rendered in the request `timezone`. For display.",
                                        "example": "2025-07-07T09:30:00-05:00"
                                      }
                                    },
                                    "required": [
                                      "slotId",
                                      "startUtc",
                                      "startLocal",
                                      "endUtc",
                                      "endLocal"
                                    ]
                                  },
                                  "description": "Open slots on this day, ascending by `startUtc`."
                                }
                              },
                              "required": ["date", "slots"]
                            },
                            "description": "Days with open slots, ascending. Empty (`[]`) when this supplier matches the service and location but has no availability in the window."
                          },
                          "availabilityMatch": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "score": {
                                "type": "number",
                                "description": "How well this supplier fits the schedule you asked for, 0–1. The plain mean of the `components` below — only the criteria you actually sent are averaged, so sending one preference does not cap every supplier at 0.25. Unrounded. Rank suppliers by this WITHIN a page; see the note on `availabilityMatch` about paging.",
                                "example": 0.8035714285714286
                              },
                              "components": {
                                "type": "object",
                                "properties": {
                                  "startDate": {
                                    "type": "number",
                                    "description": "How soon the supplier’s first open slot arrives after `lookAheadStartDate`, as `1 - (daysUntilFirstSlot / windowDays)`. 1 = free on day one. Present only when you sent `lookAheadStartDate`.",
                                    "example": 0.7142857142857143
                                  },
                                  "timeOfDay": {
                                    "type": "number",
                                    "description": "Of the days this supplier has any availability, the fraction with at least one slot starting inside a `preferredTimes` window. Present only when you sent `preferredTimes`.",
                                    "example": 0.5
                                  },
                                  "daysOfWeek": {
                                    "type": "number",
                                    "description": "Of the weekdays you asked for, the fraction the supplier can cover somewhere in the window. Present only when you sent `daysOfWeek`.",
                                    "example": 1
                                  },
                                  "sessionsPerWeek": {
                                    "type": "number",
                                    "description": "Of the whole weeks in the window, the fraction in which the supplier has at least `sessionsPerWeek` distinct days carrying a slot. A trailing partial week is not counted. Present only when you sent `sessionsPerWeek`.",
                                    "example": 1
                                  }
                                },
                                "description": "The per-criterion breakdown behind `score` — each 0–1, each a coverage RATIO rather than a slot count, so a busy calendar does not automatically outrank a well-fitting one. A key appears only when you supplied the matching request field. Use it to explain a ranking (\"great on Mondays, poor on afternoons\") instead of showing a bare number.",
                                "example": {
                                  "startDate": 0.7142857142857143,
                                  "timeOfDay": 0.5,
                                  "daysOfWeek": 1,
                                  "sessionsPerWeek": 1
                                }
                              }
                            },
                            "required": ["score", "components"],
                            "description": "How well this supplier matches the schedule preferences on the request (`lookAheadStartDate`, `preferredTimes`, `daysOfWeek`, `sessionsPerWeek`). ABSENT when you supplied none of them — no preferences expressed is not a perfect match, and a bare request gets exactly today’s response. `excludeDates` has no component: it removes slots from the pool instead of scoring. Ranking is WITHIN A PAGE only — page membership is decided before any availability is computed, so a supplier on page 2 can legitimately outscore every supplier on page 1."
                          },
                          "position": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "0-based rank of this entry in the order the response returned it. Paged results continue the count across pages of the same `searchId`, so the first entry of page 2 is numbered after the last of page 1.",
                            "example": 0
                          }
                        },
                        "required": ["supplier", "days", "position"]
                      },
                      "description": "Suppliers on this page, in a stable order across pages."
                    },
                    "timezone": {
                      "type": "string",
                      "description": "The IANA timezone actually used for day bucketing and every `*Local` field (the request `timezone`, or the project default) — R-32.",
                      "example": "America/Chicago"
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true,
                      "description": "Pass back as `cursor` to fetch the next page of suppliers. `null` on the last page."
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Non-fatal engine messages. Usually empty."
                    }
                  },
                  "required": [
                    "searchId",
                    "data",
                    "timezone",
                    "nextCursor",
                    "errors"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validation error (e.g. neither locationId nor lat+lng, or a malformed cursor)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "No offering for this serviceId/offeringId, or no location for this locationId (sent without lat/lng); the message names the id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/availability/package-slate": {
      "post": {
        "tags": ["Availability"],
        "summary": "Build a single-supplier N-session package slate (policy-driven), persisting suggestions",
        "description": "Builds one or more \"slates\" — complete N-session plans for a package — from a single supplier's availability. Name what to plan in ONE of two ways: packageId (session count is derived from its creditCount), or a client's credit — orderId together with orderItemId (a package line of that order). A credit plans its remaining sessions in its own service/offering, ends the window at the credit's expiresAt, and works even when the package has since been deleted. Naming neither source, or both, is a 400. With a credit, an optional clientId names the client it must belong to: another client's order is refused exactly like a missing one (400 INVALID_ORDER_REFERENCE). When the window is derived from the cadence (no lookAheadDays or endDate) and no relaxation is asked for, a credit that expires before its sessions fit is a NO_COMPLETE_SLATE whose reason names the expiry. When you size the window yourself (lookAheadDays or endDate), or opt in to relaxation, the window is cut at the expiry instead, and an expiry too early for the sessions gives the generic NO_COMPLETE_SLATE, without that reason. Either way the rrule COUNT is replaced by the session count (the package's creditCount, or the credit's remaining sessions). Give a location (locationId, or lat+lng+address for travel zones), a timezone, a lookAheadStartDate with a numeric offset, and an rrule with a bounded COUNT. When persist is true (default) the returned primarySlate.slateId can be booked directly via POST /orders/{orderId}/package-bookings with { slateId }. Returns 422 when nothing is bookable.\n\nThe rrule is your PREFERRED cadence, not a hard filter — set cadenceFlexibility to FALLBACK (or ALWAYS) to opt in to relaxation. When the supplier has no complete plan on the days you asked for, the response then carries cadenceAlternatives: complete slates at a denser, supplier-feasible cadence (you asked for weekly Fridays, we offer Mon+Fri over four weeks), sorted closest-first by cadenceDistance. Read the outcome from status, not from the HTTP code alone: NO_COMPLETE_SLATE is NO LONGER the only non-OK outcome. ALTERNATIVE_CADENCE is a SUCCESS — it means primarySlate is null but cadenceAlternatives is not empty, and every entry there is bookable in exactly the same way as primarySlate (same shape, same slateId, same POST /orders/{orderId}/package-bookings call). A caller who does not set cadenceFlexibility sees no change at all: it defaults to NONE, cadenceAlternatives comes back empty, and an unbookable request is still a 422.\n\nThe response carries a `searchId` (also the `X-MB-Search-Id` header, and the persisted suggestion request's correlation id) and each slate its 0-based `position` across the whole response. Keep `searchId` for the session if you want attribution. Two optional request headers tag the search for insights and are never acted on: `X-MB-Session-Key` (an opaque key you choose, up to 64 characters) and `X-MB-Client-Kind` (`browser`, `server`, `monitor` or `loadtest`).",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Service + location + cadence + policy knobs",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "packageId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The package to plan sessions for. serviceId, offeringId and the session count (creditCount) are resolved from it server-side.",
                    "example": "pkg_01kv7n10k0fnptwk81wkm59vj7"
                  },
                  "locationId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Discovery by a stored location id. Provide this OR lat+lng.",
                    "example": "loc_01kv60qgs4e4nbjhzradnqtj0h"
                  },
                  "lat": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "number"
                      }
                    ],
                    "description": "Client latitude (travel-zone branch). Provide with lng instead of locationId.",
                    "example": 43.6532
                  },
                  "lng": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "number"
                      }
                    ],
                    "description": "Client longitude (travel-zone branch).",
                    "example": -79.3832
                  },
                  "address": {
                    "type": "object",
                    "properties": {
                      "addressOneLine": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The whole address on one line, as a person would write it.",
                        "example": "10 Main St, Toronto, ON M5V 1A1, Canada"
                      },
                      "streetNumber": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The street number.",
                        "example": "10"
                      },
                      "streetName": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The street name.",
                        "example": "Main St"
                      },
                      "city": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The city or town.",
                        "example": "Toronto"
                      },
                      "state": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The state, province or region; an ISO 3166-2 code when one matches.",
                        "example": "ON"
                      },
                      "country": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The country; ISO 3166-1 alpha-2, alpha-3 or the English name.",
                        "example": "CA"
                      },
                      "zipCode": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The postal or ZIP code, in any national format.",
                        "example": "M5V 1A1"
                      },
                      "unitNumber": {
                        "type": "string",
                        "nullable": true,
                        "description": "The unit, suite or apartment, if any.",
                        "example": "4B"
                      }
                    },
                    "required": [
                      "addressOneLine",
                      "streetNumber",
                      "streetName",
                      "city",
                      "state",
                      "country",
                      "zipCode"
                    ],
                    "description": "Structured client address. Required on the lat/lng (travel-zone) branch — it is stamped onto every returned slot so a later book-by-id satisfies the TRAVEL_ZONE address rule."
                  },
                  "supplierId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Pin the plan to one supplier; only that supplier is considered.",
                    "example": "sup_01kv60qgnef2kt3pvqgwmkbzfr"
                  },
                  "timezone": {
                    "type": "string",
                    "minLength": 1,
                    "description": "IANA timezone for the plan.",
                    "example": "America/Toronto"
                  },
                  "lookAheadStartDate": {
                    "type": "string",
                    "description": "When the recurring window starts. MUST carry a numeric UTC offset (e.g. -04:00), NOT a Z suffix.",
                    "example": "2026-07-09T00:00:00-04:00"
                  },
                  "rrule": {
                    "type": "string",
                    "description": "Your PREFERRED cadence for the sessions. MUST include a bounded, positive COUNT. When cadenceFlexibility is FALLBACK or ALWAYS and no supplier can meet this exactly, denser supplier-feasible cadences come back in cadenceAlternatives instead of a 422.",
                    "example": "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;COUNT=8"
                  },
                  "lookAheadDays": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true
                  },
                  "endDate": {
                    "type": "string"
                  },
                  "preferredTimes": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "startTime": {
                          "type": "string"
                        },
                        "endTime": {
                          "type": "string"
                        }
                      },
                      "required": ["startTime", "endTime"]
                    }
                  },
                  "daysOfWeek": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 6
                    },
                    "minItems": 1,
                    "maxItems": 7,
                    "description": "Weekdays sessions may fall on (0 = Sunday … 6 = Saturday). At least one weekday is required when this field is present — omit the field entirely for \"any day\"; an empty array is rejected. This is a HARD filter, not a preference: a weekday you leave out is removed from the supplier availability the planner sees, so no session can land on it and cadence relaxation cannot reintroduce it.",
                    "example": [1, 2]
                  },
                  "excludeDates": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                    },
                    "maxItems": 90,
                    "description": "Local calendar dates (YYYY-MM-DD) that must not carry a session — a holiday, a trip. Matched against each slot's own local calendar date as the planner buckets it, not against a UTC instant. Pass each date individually; there is no range form.",
                    "example": ["2026-08-20", "2026-08-21", "2026-08-22"]
                  },
                  "sessionsPerWeek": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 14,
                    "description": "How many sessions a week you want, independent of which weekdays. A TARGET, not a cap: distinct from maxSessionsPerWeek, which bounds sessions per Monday-anchored week and applies only to direct-fill slates. The target is always SCORED — matchComponents.sessionsPerWeek reports it on every slate — but it only STEERS which slates get built when cadence relaxation actually runs: cadenceFlexibility ALWAYS, cadenceFlexibility FALLBACK once the requested cadence yields nothing, or guaranteeSlate true, which promotes NONE to FALLBACK. On the default cadenceFlexibility of NONE your rrule fixes the schedule completely, so the target is scored and reported but changes nothing about which slates come back — send it together with cadenceFlexibility FALLBACK or ALWAYS to have it steer. Where it steers, it steers the ORDER too, and that order carries the half of your preference matchScore cannot: matchComponents.sessionsPerWeek asks for AT LEAST the target, so against a target of 2 a three-a-week slate scores exactly as well as a two-a-week one. Take the results in the order they arrive; re-sorting them by matchScore throws that preference away.",
                    "example": 3
                  },
                  "cadenceFlexibility": {
                    "type": "string",
                    "enum": ["NONE", "FALLBACK", "ALWAYS"],
                    "default": "NONE",
                    "description": "How hard to try when the supplier cannot meet your rrule exactly. NONE (default) is today’s behaviour: no cadence at the requested rrule means no slate. FALLBACK also returns cadenceAlternatives — complete slates at a DENSER, supplier-feasible cadence (you asked for weekly Fridays, we offer Mon+Fri) — but only when the requested cadence yields nothing. ALWAYS returns them alongside a successful primarySlate too, so you can show \"…or twice a week\".",
                    "example": "FALLBACK"
                  },
                  "guaranteeSlate": {
                    "type": "boolean",
                    "default": false,
                    "description": "Try harder before giving up. When every relaxed cadence also fails, fall back to a direct fill: all N sessions picked straight from the supplier’s openings with no recurrence rule, one per day, at the most consistent start time available. This guarantees flexibility of CADENCE, not of capacity — a supplier without N open days still yields no complete plan, and an under-filled plan is surfaced (or not) by the project’s allowPartialPackages setting via `partial`, exactly as it is today. Implies cadenceFlexibility FALLBACK.",
                    "example": true
                  },
                  "maxCadenceAlternatives": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 10,
                    "default": 3,
                    "description": "Max entries in cadenceAlternatives. Ignored when cadenceFlexibility is NONE.",
                    "example": 3
                  },
                  "allowWeekdaySubstitution": {
                    "type": "boolean",
                    "default": true,
                    "description": "Whether a relaxed cadence may DROP a requested weekday. Set false to keep every weekday you asked for and only ever add to them — use it when the requested day is non-negotiable (e.g. the client is only home on Fridays).",
                    "example": true
                  },
                  "minGapDays": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 90,
                    "description": "Minimum whole days between consecutive sessions in a direct-fill slate. Use it to stop a dense fallback from stacking sessions on back-to-back days. It reaches only the direct fill, not any relaxed cadence-ladder rung, so a rung can still land sessions closer together than this.",
                    "example": 2
                  },
                  "maxSessionsPerWeek": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "maximum": 14,
                    "description": "Cap on sessions per Monday-anchored calendar week in a direct-fill slate — it reaches only the direct fill, not any relaxed cadence-ladder rung, so a rung built at a denser cadence can still land more sessions in a week than this. See sessionsPerWeek for the corresponding TARGET.",
                    "example": 3
                  },
                  "maxAlternates": {
                    "type": "integer",
                    "minimum": 0,
                    "default": 3,
                    "description": "Maximum entries in alternates — same-supplier schedules or other suppliers, per your supplierPolicy. 0 returns none.",
                    "example": 3
                  },
                  "persist": {
                    "type": "boolean",
                    "default": true,
                    "description": "Persist the slate so it can be booked later by slateId. Defaults true.",
                    "example": true
                  },
                  "orderId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The order holding the credit. With orderItemId, instead of packageId: plans the credit's remaining sessions in its own service/offering, ending at its expiresAt.",
                    "example": "ord_01kv7n10k0fnptwk81wkm59vj7"
                  },
                  "orderItemId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The PACKAGE order item (credit) to plan for. Requires orderId.",
                    "example": "oi_01kv7n10k0fnptwk81wkm59vj7"
                  },
                  "clientId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Optional, with orderId + orderItemId only: the client the credit must belong to. When the order is another client's, the slate is refused exactly as for an order that does not exist (400 INVALID_ORDER_REFERENCE).",
                    "example": "cli_01kv7n10k0fnptwk81wkm59vj7"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Primary slate (OK), a usable partial slate, or — when cadenceFlexibility was set — bookable cadenceAlternatives (ALTERNATIVE_CADENCE)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "searchId": {
                      "type": "string",
                      "description": "The id of this search, also returned as the `X-MB-Search-Id` header. Every page of a paginated search carries the same id (the cursor keeps it). Keep it for the session if you want attribution: pass it back as `searchId` when the client books, and in the `search.rendered` event when you report what you showed.",
                      "example": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "OK",
                        "ALTERNATIVE_CADENCE",
                        "NO_COMPLETE_SLATE",
                        "NO_AVAILABILITY"
                      ],
                      "description": "OK, ALTERNATIVE_CADENCE, NO_COMPLETE_SLATE, or NO_AVAILABILITY. ALTERNATIVE_CADENCE is only reachable when this request opted in via cadenceFlexibility or guaranteeSlate — a request sending today’s body (neither set) never observes it."
                    },
                    "reason": {
                      "type": "string",
                      "nullable": true
                    },
                    "suggestionRequestId": {
                      "type": "string",
                      "nullable": true,
                      "description": "Audit id for this suggestion request (present when persisted)."
                    },
                    "resolvableUntil": {
                      "type": "string",
                      "nullable": true,
                      "format": "date-time"
                    },
                    "primarySlate": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "slateId": {
                          "type": "string",
                          "description": "Pass this to POST .../package-bookings to book the whole plan.",
                          "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                        },
                        "supplierId": {
                          "type": "string"
                        },
                        "completeness": {
                          "type": "string",
                          "enum": ["COMPLETE", "PARTIAL"]
                        },
                        "sessionsRequested": {
                          "type": "integer",
                          "minimum": 0,
                          "exclusiveMinimum": true,
                          "description": "How many sessions were requested (the package's creditCount)."
                        },
                        "sessionsFilled": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "How many of the requested sessions the plan could fill."
                        },
                        "startTimeConsistencyPercent": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 100
                        },
                        "totalTravelTimeMins": {
                          "type": "number",
                          "minimum": 0
                        },
                        "slots": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "slotId": {
                                "type": "string",
                                "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                              },
                              "sessionIndex": {
                                "type": "integer",
                                "minimum": 0,
                                "exclusiveMinimum": true,
                                "description": "1-based index of this session within the slate."
                              },
                              "supplierId": {
                                "type": "string"
                              },
                              "serviceId": {
                                "type": "string"
                              },
                              "offeringId": {
                                "type": "string"
                              },
                              "bookingStartUtc": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "bookingEndUtc": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "bookingTz": {
                                "type": "string"
                              },
                              "locationType": {
                                "type": "string",
                                "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"]
                              },
                              "locationId": {
                                "type": "string",
                                "nullable": true
                              },
                              "latitude": {
                                "type": "number",
                                "nullable": true
                              },
                              "longitude": {
                                "type": "number",
                                "nullable": true
                              },
                              "address": {
                                "$ref": "#/components/schemas/Address"
                              },
                              "travelTimeMins": {
                                "type": "number",
                                "nullable": true,
                                "minimum": 0
                              },
                              "capacity": {
                                "type": "integer",
                                "minimum": 0,
                                "exclusiveMinimum": true
                              },
                              "reservationStatus": {
                                "type": "string",
                                "enum": [
                                  "FREE",
                                  "HELD",
                                  "CONVERTED",
                                  "RELEASED"
                                ]
                              }
                            },
                            "required": [
                              "slotId",
                              "sessionIndex",
                              "supplierId",
                              "serviceId",
                              "offeringId",
                              "bookingStartUtc",
                              "bookingEndUtc",
                              "bookingTz",
                              "locationType",
                              "locationId",
                              "latitude",
                              "longitude",
                              "address",
                              "travelTimeMins",
                              "capacity",
                              "reservationStatus"
                            ]
                          }
                        },
                        "position": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                          "example": 0
                        },
                        "cadenceRrule": {
                          "type": "string",
                          "nullable": true,
                          "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                          "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                        },
                        "matchesRequestedCadence": {
                          "type": "boolean",
                          "description": "True when cadenceRrule is the rrule you asked for.",
                          "example": false
                        },
                        "cadenceRelaxation": {
                          "type": "string",
                          "enum": [
                            "EXACT",
                            "INTERVAL_TIGHTENED",
                            "DAYS_ADDED",
                            "DAYS_SUBSTITUTED",
                            "ALL_WORKING_DAYS",
                            "DIRECT_FILL"
                          ],
                          "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                        },
                        "cadenceDistance": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                          "example": 2
                        },
                        "cadenceSummary": {
                          "type": "object",
                          "properties": {
                            "requested": {
                              "type": "integer",
                              "nullable": true,
                              "minimum": 0,
                              "exclusiveMinimum": true,
                              "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                              "example": 4
                            },
                            "peak": {
                              "type": "integer",
                              "minimum": 0,
                              "exclusiveMinimum": true,
                              "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                              "example": 4
                            },
                            "average": {
                              "type": "number",
                              "minimum": 0,
                              "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                              "example": 2.25
                            },
                            "byWeek": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "weekStart": {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                    "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                    "example": "2026-09-14"
                                  },
                                  "sessions": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                    "example": 0
                                  }
                                },
                                "required": ["weekStart", "sessions"]
                              },
                              "minItems": 1,
                              "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                            }
                          },
                          "required": [
                            "requested",
                            "peak",
                            "average",
                            "byWeek"
                          ],
                          "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                        },
                        "matchNotes": {
                          "type": "array",
                          "items": {
                            "oneOf": [
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["SUPPLIER_UNAVAILABLE_WEEK"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["sessionsPerWeek"]
                                  },
                                  "weekStart": {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                    "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                    "example": "2026-09-14"
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionsPlaced": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "description": "Sessions this slate placed in this week."
                                      },
                                      "sessionsTargeted": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                      },
                                      "openingsInPool": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                        "example": 2
                                      },
                                      "supplierWorkdays": {
                                        "type": "array",
                                        "items": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 6
                                        },
                                        "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                      }
                                    },
                                    "required": [
                                      "sessionsPlaced",
                                      "sessionsTargeted",
                                      "openingsInPool",
                                      "supplierWorkdays"
                                    ]
                                  }
                                },
                                "required": [
                                  "code",
                                  "component",
                                  "weekStart",
                                  "evidence"
                                ],
                                "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["WEEK_EXCLUDED_BY_FILTERS"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["sessionsPerWeek"]
                                  },
                                  "weekStart": {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                    "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                    "example": "2026-09-14"
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionsPlaced": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "description": "Sessions this slate placed in this week."
                                      },
                                      "sessionsTargeted": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                      },
                                      "filter": {
                                        "type": "string",
                                        "enum": ["daysOfWeek", "excludeDates"]
                                      },
                                      "supplierWorkdays": {
                                        "type": "array",
                                        "items": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 6
                                        },
                                        "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                      },
                                      "requestedDays": {
                                        "type": "array",
                                        "items": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 6
                                        },
                                        "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                      },
                                      "excludedDates": {
                                        "type": "array",
                                        "items": {
                                          "type": "string"
                                        }
                                      }
                                    },
                                    "required": [
                                      "sessionsPlaced",
                                      "sessionsTargeted",
                                      "filter",
                                      "supplierWorkdays"
                                    ]
                                  }
                                },
                                "required": [
                                  "code",
                                  "component",
                                  "weekStart",
                                  "evidence"
                                ],
                                "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["WEEK_SUPPLY_INSUFFICIENT"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["sessionsPerWeek"]
                                  },
                                  "weekStart": {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                    "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                    "example": "2026-09-14"
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionsPlaced": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "description": "Sessions this slate placed in this week."
                                      },
                                      "sessionsTargeted": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                      },
                                      "openingsInPool": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                        "example": 2
                                      }
                                    },
                                    "required": [
                                      "sessionsPlaced",
                                      "sessionsTargeted",
                                      "openingsInPool"
                                    ]
                                  }
                                },
                                "required": [
                                  "code",
                                  "component",
                                  "weekStart",
                                  "evidence"
                                ],
                                "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["WEEK_CAPPED"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["sessionsPerWeek"]
                                  },
                                  "weekStart": {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                    "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                    "example": "2026-09-14"
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionsPlaced": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "description": "Sessions this slate placed in this week."
                                      },
                                      "sessionsTargeted": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                      },
                                      "cap": {
                                        "type": "string",
                                        "enum": [
                                          "maxSessionsPerWeek",
                                          "minGapDays"
                                        ]
                                      },
                                      "capValue": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true
                                      }
                                    },
                                    "required": [
                                      "sessionsPlaced",
                                      "sessionsTargeted",
                                      "cap",
                                      "capValue"
                                    ]
                                  }
                                },
                                "required": [
                                  "code",
                                  "component",
                                  "weekStart",
                                  "evidence"
                                ],
                                "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["SESSIONS_EXHAUSTED"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["sessionsPerWeek"]
                                  },
                                  "weekStart": {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                    "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                    "example": "2026-09-14"
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionsRequested": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true
                                      },
                                      "sessionsPlacedBefore": {
                                        "type": "integer",
                                        "minimum": 0
                                      }
                                    },
                                    "required": [
                                      "sessionsRequested",
                                      "sessionsPlacedBefore"
                                    ]
                                  }
                                },
                                "required": [
                                  "code",
                                  "component",
                                  "weekStart",
                                  "evidence"
                                ],
                                "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["CADENCE_RELAXED"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["cadence"]
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "cadenceRelaxation": {
                                        "type": "string",
                                        "enum": [
                                          "EXACT",
                                          "INTERVAL_TIGHTENED",
                                          "DAYS_ADDED",
                                          "DAYS_SUBSTITUTED",
                                          "ALL_WORKING_DAYS",
                                          "DIRECT_FILL"
                                        ],
                                        "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                      },
                                      "requestedDays": {
                                        "type": "array",
                                        "items": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 6
                                        },
                                        "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                      },
                                      "actualDays": {
                                        "type": "array",
                                        "items": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 6
                                        },
                                        "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                      }
                                    },
                                    "required": ["cadenceRelaxation"]
                                  }
                                },
                                "required": ["code", "component", "evidence"],
                                "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["SESSIONS_OUTSIDE_PREFERRED_TIMES"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["timeOfDay"]
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionIndexes": {
                                        "type": "array",
                                        "items": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true
                                        }
                                      },
                                      "localTimes": {
                                        "type": "array",
                                        "items": {
                                          "type": "string"
                                        }
                                      }
                                    },
                                    "required": ["sessionIndexes", "localTimes"]
                                  }
                                },
                                "required": ["code", "component", "evidence"],
                                "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["FIRST_SESSION_LATE"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["startDate"]
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "firstSessionDate": {
                                        "type": "string"
                                      },
                                      "windowStartDate": {
                                        "type": "string"
                                      },
                                      "dayOffset": {
                                        "type": "integer",
                                        "minimum": 0
                                      },
                                      "earlierSupplyExisted": {
                                        "type": "boolean",
                                        "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                      }
                                    },
                                    "required": [
                                      "firstSessionDate",
                                      "windowStartDate",
                                      "dayOffset",
                                      "earlierSupplyExisted"
                                    ]
                                  }
                                },
                                "required": ["code", "component", "evidence"],
                                "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["PACKAGE_UNDERFILLED"]
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionsRequested": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true
                                      },
                                      "sessionsFilled": {
                                        "type": "integer",
                                        "minimum": 0
                                      }
                                    },
                                    "required": [
                                      "sessionsRequested",
                                      "sessionsFilled"
                                    ]
                                  }
                                },
                                "required": ["code", "evidence"],
                                "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                              }
                            ]
                          },
                          "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                        },
                        "advice": {
                          "type": "object",
                          "properties": {
                            "code": {
                              "type": "string",
                              "enum": ["LATER_START_IMPROVES_CADENCE"]
                            },
                            "earliestSustainedWeek": {
                              "type": "string",
                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                              "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                              "example": "2026-09-14"
                            }
                          },
                          "required": ["code", "earliestSustainedWeek"],
                          "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                        },
                        "matchScore": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 1,
                          "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                          "example": 1
                        },
                        "matchComponents": {
                          "type": "object",
                          "properties": {
                            "startDate": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1,
                              "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                            },
                            "timeOfDay": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1,
                              "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                            },
                            "daysOfWeek": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1,
                              "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                            },
                            "sessionsPerWeek": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1,
                              "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                            },
                            "cadence": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1,
                              "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                            }
                          },
                          "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                        }
                      },
                      "required": [
                        "slateId",
                        "supplierId",
                        "completeness",
                        "sessionsRequested",
                        "sessionsFilled",
                        "startTimeConsistencyPercent",
                        "totalTravelTimeMins",
                        "slots",
                        "matchNotes",
                        "matchScore"
                      ],
                      "description": "The best COMPLETE single-supplier slate; book this by slateId."
                    },
                    "alternates": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slateId": {
                            "type": "string",
                            "description": "Pass this to POST .../package-bookings to book the whole plan.",
                            "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                          },
                          "supplierId": {
                            "type": "string"
                          },
                          "completeness": {
                            "type": "string",
                            "enum": ["COMPLETE", "PARTIAL"]
                          },
                          "sessionsRequested": {
                            "type": "integer",
                            "minimum": 0,
                            "exclusiveMinimum": true,
                            "description": "How many sessions were requested (the package's creditCount)."
                          },
                          "sessionsFilled": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "How many of the requested sessions the plan could fill."
                          },
                          "startTimeConsistencyPercent": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 100
                          },
                          "totalTravelTimeMins": {
                            "type": "number",
                            "minimum": 0
                          },
                          "slots": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "slotId": {
                                  "type": "string",
                                  "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                                },
                                "sessionIndex": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true,
                                  "description": "1-based index of this session within the slate."
                                },
                                "supplierId": {
                                  "type": "string"
                                },
                                "serviceId": {
                                  "type": "string"
                                },
                                "offeringId": {
                                  "type": "string"
                                },
                                "bookingStartUtc": {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                "bookingEndUtc": {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                "bookingTz": {
                                  "type": "string"
                                },
                                "locationType": {
                                  "type": "string",
                                  "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"]
                                },
                                "locationId": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "latitude": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "longitude": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "address": {
                                  "$ref": "#/components/schemas/Address"
                                },
                                "travelTimeMins": {
                                  "type": "number",
                                  "nullable": true,
                                  "minimum": 0
                                },
                                "capacity": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true
                                },
                                "reservationStatus": {
                                  "type": "string",
                                  "enum": [
                                    "FREE",
                                    "HELD",
                                    "CONVERTED",
                                    "RELEASED"
                                  ]
                                }
                              },
                              "required": [
                                "slotId",
                                "sessionIndex",
                                "supplierId",
                                "serviceId",
                                "offeringId",
                                "bookingStartUtc",
                                "bookingEndUtc",
                                "bookingTz",
                                "locationType",
                                "locationId",
                                "latitude",
                                "longitude",
                                "address",
                                "travelTimeMins",
                                "capacity",
                                "reservationStatus"
                              ]
                            }
                          },
                          "position": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                            "example": 0
                          },
                          "cadenceRrule": {
                            "type": "string",
                            "nullable": true,
                            "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                            "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                          },
                          "matchesRequestedCadence": {
                            "type": "boolean",
                            "description": "True when cadenceRrule is the rrule you asked for.",
                            "example": false
                          },
                          "cadenceRelaxation": {
                            "type": "string",
                            "enum": [
                              "EXACT",
                              "INTERVAL_TIGHTENED",
                              "DAYS_ADDED",
                              "DAYS_SUBSTITUTED",
                              "ALL_WORKING_DAYS",
                              "DIRECT_FILL"
                            ],
                            "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                          },
                          "cadenceDistance": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                            "example": 2
                          },
                          "cadenceSummary": {
                            "type": "object",
                            "properties": {
                              "requested": {
                                "type": "integer",
                                "nullable": true,
                                "minimum": 0,
                                "exclusiveMinimum": true,
                                "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                                "example": 4
                              },
                              "peak": {
                                "type": "integer",
                                "minimum": 0,
                                "exclusiveMinimum": true,
                                "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                                "example": 4
                              },
                              "average": {
                                "type": "number",
                                "minimum": 0,
                                "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                                "example": 2.25
                              },
                              "byWeek": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "weekStart": {
                                      "type": "string",
                                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                      "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                      "example": "2026-09-14"
                                    },
                                    "sessions": {
                                      "type": "integer",
                                      "minimum": 0,
                                      "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                      "example": 0
                                    }
                                  },
                                  "required": ["weekStart", "sessions"]
                                },
                                "minItems": 1,
                                "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                              }
                            },
                            "required": [
                              "requested",
                              "peak",
                              "average",
                              "byWeek"
                            ],
                            "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                          },
                          "matchNotes": {
                            "type": "array",
                            "items": {
                              "oneOf": [
                                {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["SUPPLIER_UNAVAILABLE_WEEK"]
                                    },
                                    "component": {
                                      "type": "string",
                                      "enum": ["sessionsPerWeek"]
                                    },
                                    "weekStart": {
                                      "type": "string",
                                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                      "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                      "example": "2026-09-14"
                                    },
                                    "evidence": {
                                      "type": "object",
                                      "properties": {
                                        "sessionsPlaced": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "description": "Sessions this slate placed in this week."
                                        },
                                        "sessionsTargeted": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true,
                                          "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                        },
                                        "openingsInPool": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                          "example": 2
                                        },
                                        "supplierWorkdays": {
                                          "type": "array",
                                          "items": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "maximum": 6
                                          },
                                          "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                        }
                                      },
                                      "required": [
                                        "sessionsPlaced",
                                        "sessionsTargeted",
                                        "openingsInPool",
                                        "supplierWorkdays"
                                      ]
                                    }
                                  },
                                  "required": [
                                    "code",
                                    "component",
                                    "weekStart",
                                    "evidence"
                                  ],
                                  "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["WEEK_EXCLUDED_BY_FILTERS"]
                                    },
                                    "component": {
                                      "type": "string",
                                      "enum": ["sessionsPerWeek"]
                                    },
                                    "weekStart": {
                                      "type": "string",
                                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                      "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                      "example": "2026-09-14"
                                    },
                                    "evidence": {
                                      "type": "object",
                                      "properties": {
                                        "sessionsPlaced": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "description": "Sessions this slate placed in this week."
                                        },
                                        "sessionsTargeted": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true,
                                          "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                        },
                                        "filter": {
                                          "type": "string",
                                          "enum": ["daysOfWeek", "excludeDates"]
                                        },
                                        "supplierWorkdays": {
                                          "type": "array",
                                          "items": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "maximum": 6
                                          },
                                          "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                        },
                                        "requestedDays": {
                                          "type": "array",
                                          "items": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "maximum": 6
                                          },
                                          "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                        },
                                        "excludedDates": {
                                          "type": "array",
                                          "items": {
                                            "type": "string"
                                          }
                                        }
                                      },
                                      "required": [
                                        "sessionsPlaced",
                                        "sessionsTargeted",
                                        "filter",
                                        "supplierWorkdays"
                                      ]
                                    }
                                  },
                                  "required": [
                                    "code",
                                    "component",
                                    "weekStart",
                                    "evidence"
                                  ],
                                  "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["WEEK_SUPPLY_INSUFFICIENT"]
                                    },
                                    "component": {
                                      "type": "string",
                                      "enum": ["sessionsPerWeek"]
                                    },
                                    "weekStart": {
                                      "type": "string",
                                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                      "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                      "example": "2026-09-14"
                                    },
                                    "evidence": {
                                      "type": "object",
                                      "properties": {
                                        "sessionsPlaced": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "description": "Sessions this slate placed in this week."
                                        },
                                        "sessionsTargeted": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true,
                                          "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                        },
                                        "openingsInPool": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                          "example": 2
                                        }
                                      },
                                      "required": [
                                        "sessionsPlaced",
                                        "sessionsTargeted",
                                        "openingsInPool"
                                      ]
                                    }
                                  },
                                  "required": [
                                    "code",
                                    "component",
                                    "weekStart",
                                    "evidence"
                                  ],
                                  "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["WEEK_CAPPED"]
                                    },
                                    "component": {
                                      "type": "string",
                                      "enum": ["sessionsPerWeek"]
                                    },
                                    "weekStart": {
                                      "type": "string",
                                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                      "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                      "example": "2026-09-14"
                                    },
                                    "evidence": {
                                      "type": "object",
                                      "properties": {
                                        "sessionsPlaced": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "description": "Sessions this slate placed in this week."
                                        },
                                        "sessionsTargeted": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true,
                                          "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                        },
                                        "cap": {
                                          "type": "string",
                                          "enum": [
                                            "maxSessionsPerWeek",
                                            "minGapDays"
                                          ]
                                        },
                                        "capValue": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true
                                        }
                                      },
                                      "required": [
                                        "sessionsPlaced",
                                        "sessionsTargeted",
                                        "cap",
                                        "capValue"
                                      ]
                                    }
                                  },
                                  "required": [
                                    "code",
                                    "component",
                                    "weekStart",
                                    "evidence"
                                  ],
                                  "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["SESSIONS_EXHAUSTED"]
                                    },
                                    "component": {
                                      "type": "string",
                                      "enum": ["sessionsPerWeek"]
                                    },
                                    "weekStart": {
                                      "type": "string",
                                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                      "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                      "example": "2026-09-14"
                                    },
                                    "evidence": {
                                      "type": "object",
                                      "properties": {
                                        "sessionsRequested": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true
                                        },
                                        "sessionsPlacedBefore": {
                                          "type": "integer",
                                          "minimum": 0
                                        }
                                      },
                                      "required": [
                                        "sessionsRequested",
                                        "sessionsPlacedBefore"
                                      ]
                                    }
                                  },
                                  "required": [
                                    "code",
                                    "component",
                                    "weekStart",
                                    "evidence"
                                  ],
                                  "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["CADENCE_RELAXED"]
                                    },
                                    "component": {
                                      "type": "string",
                                      "enum": ["cadence"]
                                    },
                                    "evidence": {
                                      "type": "object",
                                      "properties": {
                                        "cadenceRelaxation": {
                                          "type": "string",
                                          "enum": [
                                            "EXACT",
                                            "INTERVAL_TIGHTENED",
                                            "DAYS_ADDED",
                                            "DAYS_SUBSTITUTED",
                                            "ALL_WORKING_DAYS",
                                            "DIRECT_FILL"
                                          ],
                                          "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                        },
                                        "requestedDays": {
                                          "type": "array",
                                          "items": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "maximum": 6
                                          },
                                          "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                        },
                                        "actualDays": {
                                          "type": "array",
                                          "items": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "maximum": 6
                                          },
                                          "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                        }
                                      },
                                      "required": ["cadenceRelaxation"]
                                    }
                                  },
                                  "required": ["code", "component", "evidence"],
                                  "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": [
                                        "SESSIONS_OUTSIDE_PREFERRED_TIMES"
                                      ]
                                    },
                                    "component": {
                                      "type": "string",
                                      "enum": ["timeOfDay"]
                                    },
                                    "evidence": {
                                      "type": "object",
                                      "properties": {
                                        "sessionIndexes": {
                                          "type": "array",
                                          "items": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "exclusiveMinimum": true
                                          }
                                        },
                                        "localTimes": {
                                          "type": "array",
                                          "items": {
                                            "type": "string"
                                          }
                                        }
                                      },
                                      "required": [
                                        "sessionIndexes",
                                        "localTimes"
                                      ]
                                    }
                                  },
                                  "required": ["code", "component", "evidence"],
                                  "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["FIRST_SESSION_LATE"]
                                    },
                                    "component": {
                                      "type": "string",
                                      "enum": ["startDate"]
                                    },
                                    "evidence": {
                                      "type": "object",
                                      "properties": {
                                        "firstSessionDate": {
                                          "type": "string"
                                        },
                                        "windowStartDate": {
                                          "type": "string"
                                        },
                                        "dayOffset": {
                                          "type": "integer",
                                          "minimum": 0
                                        },
                                        "earlierSupplyExisted": {
                                          "type": "boolean",
                                          "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                        }
                                      },
                                      "required": [
                                        "firstSessionDate",
                                        "windowStartDate",
                                        "dayOffset",
                                        "earlierSupplyExisted"
                                      ]
                                    }
                                  },
                                  "required": ["code", "component", "evidence"],
                                  "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["PACKAGE_UNDERFILLED"]
                                    },
                                    "evidence": {
                                      "type": "object",
                                      "properties": {
                                        "sessionsRequested": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true
                                        },
                                        "sessionsFilled": {
                                          "type": "integer",
                                          "minimum": 0
                                        }
                                      },
                                      "required": [
                                        "sessionsRequested",
                                        "sessionsFilled"
                                      ]
                                    }
                                  },
                                  "required": ["code", "evidence"],
                                  "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                                }
                              ]
                            },
                            "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                          },
                          "advice": {
                            "type": "object",
                            "properties": {
                              "code": {
                                "type": "string",
                                "enum": ["LATER_START_IMPROVES_CADENCE"]
                              },
                              "earliestSustainedWeek": {
                                "type": "string",
                                "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                                "example": "2026-09-14"
                              }
                            },
                            "required": ["code", "earliestSustainedWeek"],
                            "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                          },
                          "matchScore": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 1,
                            "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                            "example": 1
                          },
                          "matchComponents": {
                            "type": "object",
                            "properties": {
                              "startDate": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 1,
                                "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                              },
                              "timeOfDay": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 1,
                                "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                              },
                              "daysOfWeek": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 1,
                                "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                              },
                              "sessionsPerWeek": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 1,
                                "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                              },
                              "cadence": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 1,
                                "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                              }
                            },
                            "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                          }
                        },
                        "required": [
                          "slateId",
                          "supplierId",
                          "completeness",
                          "sessionsRequested",
                          "sessionsFilled",
                          "startTimeConsistencyPercent",
                          "totalTravelTimeMins",
                          "slots",
                          "matchNotes",
                          "matchScore"
                        ]
                      },
                      "description": "Other bookable options beyond primarySlate, ranked best first and capped at the maxAlternates you sent. Under the default supplierPolicy of SAME_SUPPLIER these are other schedules from the SAME supplier as primarySlate; under PREFERRED or ANY they are other suppliers’ best schedules, one per supplier. Two schedules from one supplier count as different options only when they run on different weekdays, or start at least 30 minutes apart — so a supplier offering 09:00 and 09:20 gives you one option, not two. Each entry’s slateId is bookable exactly like primarySlate’s."
                    },
                    "partial": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "slateId": {
                          "type": "string",
                          "description": "Pass this to POST .../package-bookings to book the whole plan.",
                          "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                        },
                        "supplierId": {
                          "type": "string"
                        },
                        "completeness": {
                          "type": "string",
                          "enum": ["COMPLETE", "PARTIAL"]
                        },
                        "sessionsRequested": {
                          "type": "integer",
                          "minimum": 0,
                          "exclusiveMinimum": true,
                          "description": "How many sessions were requested (the package's creditCount)."
                        },
                        "sessionsFilled": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "How many of the requested sessions the plan could fill."
                        },
                        "startTimeConsistencyPercent": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 100
                        },
                        "totalTravelTimeMins": {
                          "type": "number",
                          "minimum": 0
                        },
                        "slots": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "slotId": {
                                "type": "string",
                                "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                              },
                              "sessionIndex": {
                                "type": "integer",
                                "minimum": 0,
                                "exclusiveMinimum": true,
                                "description": "1-based index of this session within the slate."
                              },
                              "supplierId": {
                                "type": "string"
                              },
                              "serviceId": {
                                "type": "string"
                              },
                              "offeringId": {
                                "type": "string"
                              },
                              "bookingStartUtc": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "bookingEndUtc": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "bookingTz": {
                                "type": "string"
                              },
                              "locationType": {
                                "type": "string",
                                "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"]
                              },
                              "locationId": {
                                "type": "string",
                                "nullable": true
                              },
                              "latitude": {
                                "type": "number",
                                "nullable": true
                              },
                              "longitude": {
                                "type": "number",
                                "nullable": true
                              },
                              "address": {
                                "$ref": "#/components/schemas/Address"
                              },
                              "travelTimeMins": {
                                "type": "number",
                                "nullable": true,
                                "minimum": 0
                              },
                              "capacity": {
                                "type": "integer",
                                "minimum": 0,
                                "exclusiveMinimum": true
                              },
                              "reservationStatus": {
                                "type": "string",
                                "enum": [
                                  "FREE",
                                  "HELD",
                                  "CONVERTED",
                                  "RELEASED"
                                ]
                              }
                            },
                            "required": [
                              "slotId",
                              "sessionIndex",
                              "supplierId",
                              "serviceId",
                              "offeringId",
                              "bookingStartUtc",
                              "bookingEndUtc",
                              "bookingTz",
                              "locationType",
                              "locationId",
                              "latitude",
                              "longitude",
                              "address",
                              "travelTimeMins",
                              "capacity",
                              "reservationStatus"
                            ]
                          }
                        },
                        "position": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                          "example": 0
                        },
                        "cadenceRrule": {
                          "type": "string",
                          "nullable": true,
                          "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                          "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                        },
                        "matchesRequestedCadence": {
                          "type": "boolean",
                          "description": "True when cadenceRrule is the rrule you asked for.",
                          "example": false
                        },
                        "cadenceRelaxation": {
                          "type": "string",
                          "enum": [
                            "EXACT",
                            "INTERVAL_TIGHTENED",
                            "DAYS_ADDED",
                            "DAYS_SUBSTITUTED",
                            "ALL_WORKING_DAYS",
                            "DIRECT_FILL"
                          ],
                          "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                        },
                        "cadenceDistance": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                          "example": 2
                        },
                        "cadenceSummary": {
                          "type": "object",
                          "properties": {
                            "requested": {
                              "type": "integer",
                              "nullable": true,
                              "minimum": 0,
                              "exclusiveMinimum": true,
                              "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                              "example": 4
                            },
                            "peak": {
                              "type": "integer",
                              "minimum": 0,
                              "exclusiveMinimum": true,
                              "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                              "example": 4
                            },
                            "average": {
                              "type": "number",
                              "minimum": 0,
                              "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                              "example": 2.25
                            },
                            "byWeek": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "weekStart": {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                    "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                    "example": "2026-09-14"
                                  },
                                  "sessions": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                    "example": 0
                                  }
                                },
                                "required": ["weekStart", "sessions"]
                              },
                              "minItems": 1,
                              "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                            }
                          },
                          "required": [
                            "requested",
                            "peak",
                            "average",
                            "byWeek"
                          ],
                          "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                        },
                        "matchNotes": {
                          "type": "array",
                          "items": {
                            "oneOf": [
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["SUPPLIER_UNAVAILABLE_WEEK"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["sessionsPerWeek"]
                                  },
                                  "weekStart": {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                    "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                    "example": "2026-09-14"
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionsPlaced": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "description": "Sessions this slate placed in this week."
                                      },
                                      "sessionsTargeted": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                      },
                                      "openingsInPool": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                        "example": 2
                                      },
                                      "supplierWorkdays": {
                                        "type": "array",
                                        "items": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 6
                                        },
                                        "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                      }
                                    },
                                    "required": [
                                      "sessionsPlaced",
                                      "sessionsTargeted",
                                      "openingsInPool",
                                      "supplierWorkdays"
                                    ]
                                  }
                                },
                                "required": [
                                  "code",
                                  "component",
                                  "weekStart",
                                  "evidence"
                                ],
                                "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["WEEK_EXCLUDED_BY_FILTERS"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["sessionsPerWeek"]
                                  },
                                  "weekStart": {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                    "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                    "example": "2026-09-14"
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionsPlaced": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "description": "Sessions this slate placed in this week."
                                      },
                                      "sessionsTargeted": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                      },
                                      "filter": {
                                        "type": "string",
                                        "enum": ["daysOfWeek", "excludeDates"]
                                      },
                                      "supplierWorkdays": {
                                        "type": "array",
                                        "items": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 6
                                        },
                                        "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                      },
                                      "requestedDays": {
                                        "type": "array",
                                        "items": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 6
                                        },
                                        "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                      },
                                      "excludedDates": {
                                        "type": "array",
                                        "items": {
                                          "type": "string"
                                        }
                                      }
                                    },
                                    "required": [
                                      "sessionsPlaced",
                                      "sessionsTargeted",
                                      "filter",
                                      "supplierWorkdays"
                                    ]
                                  }
                                },
                                "required": [
                                  "code",
                                  "component",
                                  "weekStart",
                                  "evidence"
                                ],
                                "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["WEEK_SUPPLY_INSUFFICIENT"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["sessionsPerWeek"]
                                  },
                                  "weekStart": {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                    "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                    "example": "2026-09-14"
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionsPlaced": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "description": "Sessions this slate placed in this week."
                                      },
                                      "sessionsTargeted": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                      },
                                      "openingsInPool": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                        "example": 2
                                      }
                                    },
                                    "required": [
                                      "sessionsPlaced",
                                      "sessionsTargeted",
                                      "openingsInPool"
                                    ]
                                  }
                                },
                                "required": [
                                  "code",
                                  "component",
                                  "weekStart",
                                  "evidence"
                                ],
                                "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["WEEK_CAPPED"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["sessionsPerWeek"]
                                  },
                                  "weekStart": {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                    "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                    "example": "2026-09-14"
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionsPlaced": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "description": "Sessions this slate placed in this week."
                                      },
                                      "sessionsTargeted": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                      },
                                      "cap": {
                                        "type": "string",
                                        "enum": [
                                          "maxSessionsPerWeek",
                                          "minGapDays"
                                        ]
                                      },
                                      "capValue": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true
                                      }
                                    },
                                    "required": [
                                      "sessionsPlaced",
                                      "sessionsTargeted",
                                      "cap",
                                      "capValue"
                                    ]
                                  }
                                },
                                "required": [
                                  "code",
                                  "component",
                                  "weekStart",
                                  "evidence"
                                ],
                                "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["SESSIONS_EXHAUSTED"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["sessionsPerWeek"]
                                  },
                                  "weekStart": {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                    "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                    "example": "2026-09-14"
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionsRequested": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true
                                      },
                                      "sessionsPlacedBefore": {
                                        "type": "integer",
                                        "minimum": 0
                                      }
                                    },
                                    "required": [
                                      "sessionsRequested",
                                      "sessionsPlacedBefore"
                                    ]
                                  }
                                },
                                "required": [
                                  "code",
                                  "component",
                                  "weekStart",
                                  "evidence"
                                ],
                                "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["CADENCE_RELAXED"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["cadence"]
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "cadenceRelaxation": {
                                        "type": "string",
                                        "enum": [
                                          "EXACT",
                                          "INTERVAL_TIGHTENED",
                                          "DAYS_ADDED",
                                          "DAYS_SUBSTITUTED",
                                          "ALL_WORKING_DAYS",
                                          "DIRECT_FILL"
                                        ],
                                        "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                      },
                                      "requestedDays": {
                                        "type": "array",
                                        "items": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 6
                                        },
                                        "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                      },
                                      "actualDays": {
                                        "type": "array",
                                        "items": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 6
                                        },
                                        "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                      }
                                    },
                                    "required": ["cadenceRelaxation"]
                                  }
                                },
                                "required": ["code", "component", "evidence"],
                                "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["SESSIONS_OUTSIDE_PREFERRED_TIMES"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["timeOfDay"]
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionIndexes": {
                                        "type": "array",
                                        "items": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true
                                        }
                                      },
                                      "localTimes": {
                                        "type": "array",
                                        "items": {
                                          "type": "string"
                                        }
                                      }
                                    },
                                    "required": ["sessionIndexes", "localTimes"]
                                  }
                                },
                                "required": ["code", "component", "evidence"],
                                "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["FIRST_SESSION_LATE"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["startDate"]
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "firstSessionDate": {
                                        "type": "string"
                                      },
                                      "windowStartDate": {
                                        "type": "string"
                                      },
                                      "dayOffset": {
                                        "type": "integer",
                                        "minimum": 0
                                      },
                                      "earlierSupplyExisted": {
                                        "type": "boolean",
                                        "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                      }
                                    },
                                    "required": [
                                      "firstSessionDate",
                                      "windowStartDate",
                                      "dayOffset",
                                      "earlierSupplyExisted"
                                    ]
                                  }
                                },
                                "required": ["code", "component", "evidence"],
                                "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["PACKAGE_UNDERFILLED"]
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionsRequested": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true
                                      },
                                      "sessionsFilled": {
                                        "type": "integer",
                                        "minimum": 0
                                      }
                                    },
                                    "required": [
                                      "sessionsRequested",
                                      "sessionsFilled"
                                    ]
                                  }
                                },
                                "required": ["code", "evidence"],
                                "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                              }
                            ]
                          },
                          "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                        },
                        "advice": {
                          "type": "object",
                          "properties": {
                            "code": {
                              "type": "string",
                              "enum": ["LATER_START_IMPROVES_CADENCE"]
                            },
                            "earliestSustainedWeek": {
                              "type": "string",
                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                              "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                              "example": "2026-09-14"
                            }
                          },
                          "required": ["code", "earliestSustainedWeek"],
                          "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                        },
                        "matchScore": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 1,
                          "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                          "example": 1
                        },
                        "matchComponents": {
                          "type": "object",
                          "properties": {
                            "startDate": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1,
                              "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                            },
                            "timeOfDay": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1,
                              "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                            },
                            "daysOfWeek": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1,
                              "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                            },
                            "sessionsPerWeek": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1,
                              "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                            },
                            "cadence": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1,
                              "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                            }
                          },
                          "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                        }
                      },
                      "required": [
                        "slateId",
                        "supplierId",
                        "completeness",
                        "sessionsRequested",
                        "sessionsFilled",
                        "startTimeConsistencyPercent",
                        "totalTravelTimeMins",
                        "slots",
                        "matchNotes",
                        "matchScore"
                      ]
                    },
                    "cadenceAlternatives": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slateId": {
                            "type": "string",
                            "description": "Pass this to POST .../package-bookings to book the whole plan.",
                            "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                          },
                          "supplierId": {
                            "type": "string"
                          },
                          "completeness": {
                            "type": "string",
                            "enum": ["COMPLETE", "PARTIAL"]
                          },
                          "sessionsRequested": {
                            "type": "integer",
                            "minimum": 0,
                            "exclusiveMinimum": true,
                            "description": "How many sessions were requested (the package's creditCount)."
                          },
                          "sessionsFilled": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "How many of the requested sessions the plan could fill."
                          },
                          "startTimeConsistencyPercent": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 100
                          },
                          "totalTravelTimeMins": {
                            "type": "number",
                            "minimum": 0
                          },
                          "slots": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "slotId": {
                                  "type": "string",
                                  "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                                },
                                "sessionIndex": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true,
                                  "description": "1-based index of this session within the slate."
                                },
                                "supplierId": {
                                  "type": "string"
                                },
                                "serviceId": {
                                  "type": "string"
                                },
                                "offeringId": {
                                  "type": "string"
                                },
                                "bookingStartUtc": {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                "bookingEndUtc": {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                "bookingTz": {
                                  "type": "string"
                                },
                                "locationType": {
                                  "type": "string",
                                  "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"]
                                },
                                "locationId": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "latitude": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "longitude": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "address": {
                                  "$ref": "#/components/schemas/Address"
                                },
                                "travelTimeMins": {
                                  "type": "number",
                                  "nullable": true,
                                  "minimum": 0
                                },
                                "capacity": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true
                                },
                                "reservationStatus": {
                                  "type": "string",
                                  "enum": [
                                    "FREE",
                                    "HELD",
                                    "CONVERTED",
                                    "RELEASED"
                                  ]
                                }
                              },
                              "required": [
                                "slotId",
                                "sessionIndex",
                                "supplierId",
                                "serviceId",
                                "offeringId",
                                "bookingStartUtc",
                                "bookingEndUtc",
                                "bookingTz",
                                "locationType",
                                "locationId",
                                "latitude",
                                "longitude",
                                "address",
                                "travelTimeMins",
                                "capacity",
                                "reservationStatus"
                              ]
                            }
                          },
                          "position": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                            "example": 0
                          },
                          "cadenceRrule": {
                            "type": "string",
                            "nullable": true,
                            "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                            "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                          },
                          "matchesRequestedCadence": {
                            "type": "boolean",
                            "description": "True when cadenceRrule is the rrule you asked for.",
                            "example": false
                          },
                          "cadenceRelaxation": {
                            "type": "string",
                            "enum": [
                              "EXACT",
                              "INTERVAL_TIGHTENED",
                              "DAYS_ADDED",
                              "DAYS_SUBSTITUTED",
                              "ALL_WORKING_DAYS",
                              "DIRECT_FILL"
                            ],
                            "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                          },
                          "cadenceDistance": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                            "example": 2
                          },
                          "cadenceSummary": {
                            "type": "object",
                            "properties": {
                              "requested": {
                                "type": "integer",
                                "nullable": true,
                                "minimum": 0,
                                "exclusiveMinimum": true,
                                "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                                "example": 4
                              },
                              "peak": {
                                "type": "integer",
                                "minimum": 0,
                                "exclusiveMinimum": true,
                                "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                                "example": 4
                              },
                              "average": {
                                "type": "number",
                                "minimum": 0,
                                "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                                "example": 2.25
                              },
                              "byWeek": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "weekStart": {
                                      "type": "string",
                                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                      "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                      "example": "2026-09-14"
                                    },
                                    "sessions": {
                                      "type": "integer",
                                      "minimum": 0,
                                      "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                      "example": 0
                                    }
                                  },
                                  "required": ["weekStart", "sessions"]
                                },
                                "minItems": 1,
                                "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                              }
                            },
                            "required": [
                              "requested",
                              "peak",
                              "average",
                              "byWeek"
                            ],
                            "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                          },
                          "matchNotes": {
                            "type": "array",
                            "items": {
                              "oneOf": [
                                {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["SUPPLIER_UNAVAILABLE_WEEK"]
                                    },
                                    "component": {
                                      "type": "string",
                                      "enum": ["sessionsPerWeek"]
                                    },
                                    "weekStart": {
                                      "type": "string",
                                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                      "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                      "example": "2026-09-14"
                                    },
                                    "evidence": {
                                      "type": "object",
                                      "properties": {
                                        "sessionsPlaced": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "description": "Sessions this slate placed in this week."
                                        },
                                        "sessionsTargeted": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true,
                                          "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                        },
                                        "openingsInPool": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                          "example": 2
                                        },
                                        "supplierWorkdays": {
                                          "type": "array",
                                          "items": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "maximum": 6
                                          },
                                          "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                        }
                                      },
                                      "required": [
                                        "sessionsPlaced",
                                        "sessionsTargeted",
                                        "openingsInPool",
                                        "supplierWorkdays"
                                      ]
                                    }
                                  },
                                  "required": [
                                    "code",
                                    "component",
                                    "weekStart",
                                    "evidence"
                                  ],
                                  "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["WEEK_EXCLUDED_BY_FILTERS"]
                                    },
                                    "component": {
                                      "type": "string",
                                      "enum": ["sessionsPerWeek"]
                                    },
                                    "weekStart": {
                                      "type": "string",
                                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                      "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                      "example": "2026-09-14"
                                    },
                                    "evidence": {
                                      "type": "object",
                                      "properties": {
                                        "sessionsPlaced": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "description": "Sessions this slate placed in this week."
                                        },
                                        "sessionsTargeted": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true,
                                          "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                        },
                                        "filter": {
                                          "type": "string",
                                          "enum": ["daysOfWeek", "excludeDates"]
                                        },
                                        "supplierWorkdays": {
                                          "type": "array",
                                          "items": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "maximum": 6
                                          },
                                          "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                        },
                                        "requestedDays": {
                                          "type": "array",
                                          "items": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "maximum": 6
                                          },
                                          "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                        },
                                        "excludedDates": {
                                          "type": "array",
                                          "items": {
                                            "type": "string"
                                          }
                                        }
                                      },
                                      "required": [
                                        "sessionsPlaced",
                                        "sessionsTargeted",
                                        "filter",
                                        "supplierWorkdays"
                                      ]
                                    }
                                  },
                                  "required": [
                                    "code",
                                    "component",
                                    "weekStart",
                                    "evidence"
                                  ],
                                  "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["WEEK_SUPPLY_INSUFFICIENT"]
                                    },
                                    "component": {
                                      "type": "string",
                                      "enum": ["sessionsPerWeek"]
                                    },
                                    "weekStart": {
                                      "type": "string",
                                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                      "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                      "example": "2026-09-14"
                                    },
                                    "evidence": {
                                      "type": "object",
                                      "properties": {
                                        "sessionsPlaced": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "description": "Sessions this slate placed in this week."
                                        },
                                        "sessionsTargeted": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true,
                                          "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                        },
                                        "openingsInPool": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                          "example": 2
                                        }
                                      },
                                      "required": [
                                        "sessionsPlaced",
                                        "sessionsTargeted",
                                        "openingsInPool"
                                      ]
                                    }
                                  },
                                  "required": [
                                    "code",
                                    "component",
                                    "weekStart",
                                    "evidence"
                                  ],
                                  "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["WEEK_CAPPED"]
                                    },
                                    "component": {
                                      "type": "string",
                                      "enum": ["sessionsPerWeek"]
                                    },
                                    "weekStart": {
                                      "type": "string",
                                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                      "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                      "example": "2026-09-14"
                                    },
                                    "evidence": {
                                      "type": "object",
                                      "properties": {
                                        "sessionsPlaced": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "description": "Sessions this slate placed in this week."
                                        },
                                        "sessionsTargeted": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true,
                                          "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                        },
                                        "cap": {
                                          "type": "string",
                                          "enum": [
                                            "maxSessionsPerWeek",
                                            "minGapDays"
                                          ]
                                        },
                                        "capValue": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true
                                        }
                                      },
                                      "required": [
                                        "sessionsPlaced",
                                        "sessionsTargeted",
                                        "cap",
                                        "capValue"
                                      ]
                                    }
                                  },
                                  "required": [
                                    "code",
                                    "component",
                                    "weekStart",
                                    "evidence"
                                  ],
                                  "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["SESSIONS_EXHAUSTED"]
                                    },
                                    "component": {
                                      "type": "string",
                                      "enum": ["sessionsPerWeek"]
                                    },
                                    "weekStart": {
                                      "type": "string",
                                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                      "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                      "example": "2026-09-14"
                                    },
                                    "evidence": {
                                      "type": "object",
                                      "properties": {
                                        "sessionsRequested": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true
                                        },
                                        "sessionsPlacedBefore": {
                                          "type": "integer",
                                          "minimum": 0
                                        }
                                      },
                                      "required": [
                                        "sessionsRequested",
                                        "sessionsPlacedBefore"
                                      ]
                                    }
                                  },
                                  "required": [
                                    "code",
                                    "component",
                                    "weekStart",
                                    "evidence"
                                  ],
                                  "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["CADENCE_RELAXED"]
                                    },
                                    "component": {
                                      "type": "string",
                                      "enum": ["cadence"]
                                    },
                                    "evidence": {
                                      "type": "object",
                                      "properties": {
                                        "cadenceRelaxation": {
                                          "type": "string",
                                          "enum": [
                                            "EXACT",
                                            "INTERVAL_TIGHTENED",
                                            "DAYS_ADDED",
                                            "DAYS_SUBSTITUTED",
                                            "ALL_WORKING_DAYS",
                                            "DIRECT_FILL"
                                          ],
                                          "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                        },
                                        "requestedDays": {
                                          "type": "array",
                                          "items": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "maximum": 6
                                          },
                                          "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                        },
                                        "actualDays": {
                                          "type": "array",
                                          "items": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "maximum": 6
                                          },
                                          "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                        }
                                      },
                                      "required": ["cadenceRelaxation"]
                                    }
                                  },
                                  "required": ["code", "component", "evidence"],
                                  "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": [
                                        "SESSIONS_OUTSIDE_PREFERRED_TIMES"
                                      ]
                                    },
                                    "component": {
                                      "type": "string",
                                      "enum": ["timeOfDay"]
                                    },
                                    "evidence": {
                                      "type": "object",
                                      "properties": {
                                        "sessionIndexes": {
                                          "type": "array",
                                          "items": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "exclusiveMinimum": true
                                          }
                                        },
                                        "localTimes": {
                                          "type": "array",
                                          "items": {
                                            "type": "string"
                                          }
                                        }
                                      },
                                      "required": [
                                        "sessionIndexes",
                                        "localTimes"
                                      ]
                                    }
                                  },
                                  "required": ["code", "component", "evidence"],
                                  "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["FIRST_SESSION_LATE"]
                                    },
                                    "component": {
                                      "type": "string",
                                      "enum": ["startDate"]
                                    },
                                    "evidence": {
                                      "type": "object",
                                      "properties": {
                                        "firstSessionDate": {
                                          "type": "string"
                                        },
                                        "windowStartDate": {
                                          "type": "string"
                                        },
                                        "dayOffset": {
                                          "type": "integer",
                                          "minimum": 0
                                        },
                                        "earlierSupplyExisted": {
                                          "type": "boolean",
                                          "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                        }
                                      },
                                      "required": [
                                        "firstSessionDate",
                                        "windowStartDate",
                                        "dayOffset",
                                        "earlierSupplyExisted"
                                      ]
                                    }
                                  },
                                  "required": ["code", "component", "evidence"],
                                  "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                                },
                                {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["PACKAGE_UNDERFILLED"]
                                    },
                                    "evidence": {
                                      "type": "object",
                                      "properties": {
                                        "sessionsRequested": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true
                                        },
                                        "sessionsFilled": {
                                          "type": "integer",
                                          "minimum": 0
                                        }
                                      },
                                      "required": [
                                        "sessionsRequested",
                                        "sessionsFilled"
                                      ]
                                    }
                                  },
                                  "required": ["code", "evidence"],
                                  "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                                }
                              ]
                            },
                            "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                          },
                          "advice": {
                            "type": "object",
                            "properties": {
                              "code": {
                                "type": "string",
                                "enum": ["LATER_START_IMPROVES_CADENCE"]
                              },
                              "earliestSustainedWeek": {
                                "type": "string",
                                "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                                "example": "2026-09-14"
                              }
                            },
                            "required": ["code", "earliestSustainedWeek"],
                            "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                          },
                          "matchScore": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 1,
                            "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                            "example": 1
                          },
                          "matchComponents": {
                            "type": "object",
                            "properties": {
                              "startDate": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 1,
                                "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                              },
                              "timeOfDay": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 1,
                                "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                              },
                              "daysOfWeek": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 1,
                                "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                              },
                              "sessionsPerWeek": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 1,
                                "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                              },
                              "cadence": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 1,
                                "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                              }
                            },
                            "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                          }
                        },
                        "required": [
                          "slateId",
                          "supplierId",
                          "completeness",
                          "sessionsRequested",
                          "sessionsFilled",
                          "startTimeConsistencyPercent",
                          "totalTravelTimeMins",
                          "slots",
                          "matchNotes",
                          "matchScore"
                        ]
                      },
                      "default": [],
                      "description": "Complete N-session slates that fit the supplier’s real availability but do NOT follow the rrule you asked for — e.g. you requested weekly Fridays, no supplier has eight free Fridays, so this carries a Mon+Fri plan instead. Sorted by cadenceDistance, closest first, when the request carries no sessionsPerWeek target; when it does, ranked by closeness to that target first and cadenceDistance only as the tiebreaker. Always empty unless the request set cadenceFlexibility or guaranteeSlate. Each entry’s slateId is bookable exactly like primarySlate’s."
                    },
                    "requestedCadence": {
                      "type": "string",
                      "nullable": true,
                      "description": "The rrule this request asked for, echoed back so you can diff it against each slate’s cadenceRrule.",
                      "example": "FREQ=WEEKLY;BYDAY=FR;COUNT=8"
                    }
                  },
                  "required": [
                    "status",
                    "reason",
                    "suggestionRequestId",
                    "resolvableUntil",
                    "primarySlate",
                    "alternates",
                    "partial"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validation error (code: BAD_REQUEST), or a credit that cannot be planned (code: INVALID_ORDER_REFERENCE | NOT_A_PACKAGE_ITEM)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "The package, order or order item was not found (code: NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "The credit has no sessions left to plan, has expired, or is on a cancelled order (code: ORDER_ITEM_QUANTITY_UNAVAILABLE | PACKAGE_EXPIRED | ORDER_CANCELLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "422": {
            "description": "No complete or bookable slate — no primarySlate, no partial, and no cadenceAlternatives (code: NO_COMPLETE_SLATE | NO_AVAILABILITY)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/availability/package-options": {
      "post": {
        "tags": ["Availability"],
        "summary": "List a service's packages, each with a ready-to-book slate",
        "description": "Returns every ACTIVE package of a service, each with a complete N-session plan built from a supplier's real availability. The response entry carries a slateId that can be booked directly via POST /orders/{orderId}/package-bookings. Cadence defaults to FREQ=WEEKLY;COUNT={creditCount}, derived per package. Packages that cannot be planned come back with status NO_COMPLETE_SLATE or NO_AVAILABILITY and a reason — they do not fail the request.\n\nThe rrule is the PREFERRED cadence, not a hard filter — set cadenceFlexibility to FALLBACK (or ALWAYS) and it applies to every package in the response. An entry that has no complete plan on the requested days then comes back with status ALTERNATIVE_CADENCE and a non-empty cadenceAlternatives: complete slates at a denser, supplier-feasible cadence, sorted closest-first by cadenceDistance. Read the outcome from each entry's status: NO_COMPLETE_SLATE is NO LONGER the only non-OK outcome, and ALTERNATIVE_CADENCE is a success — every cadenceAlternatives entry carries a slateId that is bookable in exactly the same way as primarySlate. A caller who does not set cadenceFlexibility sees no change at all: it defaults to NONE and cadenceAlternatives comes back empty.\n\nThe response carries a `searchId` (also the `X-MB-Search-Id` header, and the correlation id of every suggestion request this call persisted) and each slate its 0-based `position` within its package. Keep `searchId` for the session if you want attribution. Two optional request headers tag the search for insights and are never acted on: `X-MB-Session-Key` (an opaque key you choose, up to 64 characters) and `X-MB-Client-Kind` (`browser`, `server`, `monitor` or `loadtest`).",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Service + location + optional supplier and cadence",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "serviceId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The service whose ACTIVE packages should be priced and planned.",
                    "example": "srv_01kq8cp17bf03t125zhakpcgyx"
                  },
                  "locationId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Discovery by a stored location id. Provide this OR lat+lng+address."
                  },
                  "lat": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "number"
                      }
                    ],
                    "description": "Client latitude (travel-zone branch).",
                    "example": 43.6532
                  },
                  "lng": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "number"
                      }
                    ],
                    "description": "Client longitude (travel-zone branch).",
                    "example": -79.3832
                  },
                  "address": {
                    "type": "object",
                    "properties": {
                      "addressOneLine": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The whole address on one line, as a person would write it.",
                        "example": "10 Main St, Toronto, ON M5V 1A1, Canada"
                      },
                      "streetNumber": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The street number.",
                        "example": "10"
                      },
                      "streetName": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The street name.",
                        "example": "Main St"
                      },
                      "city": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The city or town.",
                        "example": "Toronto"
                      },
                      "state": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The state, province or region; an ISO 3166-2 code when one matches.",
                        "example": "ON"
                      },
                      "country": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The country; ISO 3166-1 alpha-2, alpha-3 or the English name.",
                        "example": "CA"
                      },
                      "zipCode": {
                        "type": "string",
                        "minLength": 1,
                        "description": "The postal or ZIP code, in any national format.",
                        "example": "M5V 1A1"
                      },
                      "unitNumber": {
                        "type": "string",
                        "nullable": true,
                        "description": "The unit, suite or apartment, if any.",
                        "example": "4B"
                      }
                    },
                    "required": [
                      "addressOneLine",
                      "streetNumber",
                      "streetName",
                      "city",
                      "state",
                      "country",
                      "zipCode"
                    ],
                    "description": "Structured client address. Required on the lat/lng (travel-zone) branch."
                  },
                  "supplierId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Pin every slate to one supplier. Omit to consider all suppliers serving the location."
                  },
                  "timezone": {
                    "type": "string",
                    "minLength": 1,
                    "description": "IANA timezone. Defaults to the project's defaultTimezone."
                  },
                  "rrule": {
                    "type": "string",
                    "description": "Cadence for every package. Omit to default to FREQ=WEEKLY;COUNT={creditCount}, derived per package from its own credit count.",
                    "example": "FREQ=WEEKLY;BYDAY=MO"
                  },
                  "lookAheadStartDate": {
                    "type": "string",
                    "description": "ISO start of the search window. Defaults to now. When provided, MUST carry a numeric UTC offset (e.g. -04:00), NOT a Z suffix.",
                    "example": "2026-07-09T00:00:00-04:00"
                  },
                  "preferredTimes": {
                    "type": "array",
                    "nullable": true,
                    "items": {
                      "type": "object",
                      "properties": {
                        "startTime": {
                          "type": "string"
                        },
                        "endTime": {
                          "type": "string"
                        }
                      },
                      "required": ["startTime", "endTime"]
                    }
                  },
                  "daysOfWeek": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 6
                    },
                    "minItems": 1,
                    "maxItems": 7,
                    "description": "Weekdays sessions may fall on (0 = Sunday … 6 = Saturday). At least one weekday is required when this field is present — omit the field entirely for \"any day\"; an empty array is rejected. This is a HARD filter, not a preference: a weekday you leave out is removed from the supplier availability the planner sees, so no session can land on it and cadence relaxation cannot reintroduce it.",
                    "example": [1, 2]
                  },
                  "excludeDates": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                    },
                    "maxItems": 90,
                    "description": "Local calendar dates (YYYY-MM-DD) that must not carry a session — a holiday, a trip. Matched against each slot's own local calendar date as the planner buckets it, not against a UTC instant. Pass each date individually; there is no range form.",
                    "example": ["2026-08-20", "2026-08-21", "2026-08-22"]
                  },
                  "sessionsPerWeek": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 14,
                    "description": "How many sessions a week you want, independent of which weekdays. A TARGET, not a cap: distinct from maxSessionsPerWeek, which bounds sessions per Monday-anchored week and applies only to direct-fill slates. The target is always SCORED — matchComponents.sessionsPerWeek reports it on every slate — but it only STEERS which slates get built when cadence relaxation actually runs: cadenceFlexibility ALWAYS, cadenceFlexibility FALLBACK once the requested cadence yields nothing, or guaranteeSlate true, which promotes NONE to FALLBACK. On the default cadenceFlexibility of NONE your rrule fixes the schedule completely, so the target is scored and reported but changes nothing about which slates come back — send it together with cadenceFlexibility FALLBACK or ALWAYS to have it steer. Where it steers, it steers the ORDER too, and that order carries the half of your preference matchScore cannot: matchComponents.sessionsPerWeek asks for AT LEAST the target, so against a target of 2 a three-a-week slate scores exactly as well as a two-a-week one. Take the results in the order they arrive; re-sorting them by matchScore throws that preference away.",
                    "example": 3
                  },
                  "cadenceFlexibility": {
                    "type": "string",
                    "enum": ["NONE", "FALLBACK", "ALWAYS"],
                    "default": "NONE",
                    "description": "How hard to try when the supplier cannot meet your rrule exactly. NONE (default) is today’s behaviour: no cadence at the requested rrule means no slate. FALLBACK also returns cadenceAlternatives — complete slates at a DENSER, supplier-feasible cadence (you asked for weekly Fridays, we offer Mon+Fri) — but only when the requested cadence yields nothing. ALWAYS returns them alongside a successful primarySlate too, so you can show \"…or twice a week\".",
                    "example": "FALLBACK"
                  },
                  "guaranteeSlate": {
                    "type": "boolean",
                    "default": false,
                    "description": "Try harder before giving up. When every relaxed cadence also fails, fall back to a direct fill: all N sessions picked straight from the supplier’s openings with no recurrence rule, one per day, at the most consistent start time available. This guarantees flexibility of CADENCE, not of capacity — a supplier without N open days still yields no complete plan, and an under-filled plan is surfaced (or not) by the project’s allowPartialPackages setting via `partial`, exactly as it is today. Implies cadenceFlexibility FALLBACK.",
                    "example": true
                  },
                  "maxCadenceAlternatives": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 10,
                    "default": 3,
                    "description": "Max entries in cadenceAlternatives. Ignored when cadenceFlexibility is NONE.",
                    "example": 3
                  },
                  "allowWeekdaySubstitution": {
                    "type": "boolean",
                    "default": true,
                    "description": "Whether a relaxed cadence may DROP a requested weekday. Set false to keep every weekday you asked for and only ever add to them — use it when the requested day is non-negotiable (e.g. the client is only home on Fridays).",
                    "example": true
                  },
                  "minGapDays": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 90,
                    "description": "Minimum whole days between consecutive sessions in a direct-fill slate. Use it to stop a dense fallback from stacking sessions on back-to-back days. It reaches only the direct fill, not any relaxed cadence-ladder rung, so a rung can still land sessions closer together than this.",
                    "example": 2
                  },
                  "maxSessionsPerWeek": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "maximum": 14,
                    "description": "Cap on sessions per Monday-anchored calendar week in a direct-fill slate — it reaches only the direct fill, not any relaxed cadence-ladder rung, so a rung built at a denser cadence can still land more sessions in a week than this. See sessionsPerWeek for the corresponding TARGET.",
                    "example": 3
                  },
                  "maxAlternates": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Maximum entries in alternates — same-supplier schedules or other suppliers, per your supplierPolicy. 0 returns none.",
                    "example": 3
                  },
                  "persist": {
                    "type": "boolean",
                    "description": "Persist slates so primarySlate.slateId is bookable. Defaults to true."
                  }
                },
                "required": ["serviceId"],
                "description": "A service + a location (+ optionally a supplier and cadence)."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One entry per ACTIVE package",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "searchId": {
                      "type": "string",
                      "description": "The id of this search, also returned as the `X-MB-Search-Id` header. Every page of a paginated search carries the same id (the cursor keeps it). Keep it for the session if you want attribution: pass it back as `searchId` when the client books, and in the `search.rendered` event when you report what you showed.",
                      "example": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "package": {
                            "$ref": "#/components/schemas/ServicePackage"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "OK",
                              "ALTERNATIVE_CADENCE",
                              "NO_COMPLETE_SLATE",
                              "NO_AVAILABILITY"
                            ],
                            "description": "OK, ALTERNATIVE_CADENCE, NO_COMPLETE_SLATE, or NO_AVAILABILITY — for THIS package. ALTERNATIVE_CADENCE is only reachable when this request opted in via cadenceFlexibility or guaranteeSlate — a request sending today’s body (neither set) never observes it."
                          },
                          "reason": {
                            "type": "string",
                            "nullable": true,
                            "description": "Why this package is not bookable. Null when status is OK."
                          },
                          "slateId": {
                            "type": "string",
                            "nullable": true,
                            "description": "Book this package by passing this to POST .../package-bookings. Null unless OK."
                          },
                          "primarySlate": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "slateId": {
                                "type": "string",
                                "description": "Pass this to POST .../package-bookings to book the whole plan.",
                                "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                              },
                              "supplierId": {
                                "type": "string"
                              },
                              "completeness": {
                                "type": "string",
                                "enum": ["COMPLETE", "PARTIAL"]
                              },
                              "sessionsRequested": {
                                "type": "integer",
                                "minimum": 0,
                                "exclusiveMinimum": true,
                                "description": "How many sessions were requested (the package's creditCount)."
                              },
                              "sessionsFilled": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "How many of the requested sessions the plan could fill."
                              },
                              "startTimeConsistencyPercent": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 100
                              },
                              "totalTravelTimeMins": {
                                "type": "number",
                                "minimum": 0
                              },
                              "slots": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "slotId": {
                                      "type": "string",
                                      "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                                    },
                                    "sessionIndex": {
                                      "type": "integer",
                                      "minimum": 0,
                                      "exclusiveMinimum": true,
                                      "description": "1-based index of this session within the slate."
                                    },
                                    "supplierId": {
                                      "type": "string"
                                    },
                                    "serviceId": {
                                      "type": "string"
                                    },
                                    "offeringId": {
                                      "type": "string"
                                    },
                                    "bookingStartUtc": {
                                      "type": "string",
                                      "format": "date-time"
                                    },
                                    "bookingEndUtc": {
                                      "type": "string",
                                      "format": "date-time"
                                    },
                                    "bookingTz": {
                                      "type": "string"
                                    },
                                    "locationType": {
                                      "type": "string",
                                      "enum": [
                                        "PHYSICAL",
                                        "VIRTUAL",
                                        "TRAVEL_ZONE"
                                      ]
                                    },
                                    "locationId": {
                                      "type": "string",
                                      "nullable": true
                                    },
                                    "latitude": {
                                      "type": "number",
                                      "nullable": true
                                    },
                                    "longitude": {
                                      "type": "number",
                                      "nullable": true
                                    },
                                    "address": {
                                      "$ref": "#/components/schemas/Address"
                                    },
                                    "travelTimeMins": {
                                      "type": "number",
                                      "nullable": true,
                                      "minimum": 0
                                    },
                                    "capacity": {
                                      "type": "integer",
                                      "minimum": 0,
                                      "exclusiveMinimum": true
                                    },
                                    "reservationStatus": {
                                      "type": "string",
                                      "enum": [
                                        "FREE",
                                        "HELD",
                                        "CONVERTED",
                                        "RELEASED"
                                      ]
                                    }
                                  },
                                  "required": [
                                    "slotId",
                                    "sessionIndex",
                                    "supplierId",
                                    "serviceId",
                                    "offeringId",
                                    "bookingStartUtc",
                                    "bookingEndUtc",
                                    "bookingTz",
                                    "locationType",
                                    "locationId",
                                    "latitude",
                                    "longitude",
                                    "address",
                                    "travelTimeMins",
                                    "capacity",
                                    "reservationStatus"
                                  ]
                                }
                              },
                              "position": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                                "example": 0
                              },
                              "cadenceRrule": {
                                "type": "string",
                                "nullable": true,
                                "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                                "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                              },
                              "matchesRequestedCadence": {
                                "type": "boolean",
                                "description": "True when cadenceRrule is the rrule you asked for.",
                                "example": false
                              },
                              "cadenceRelaxation": {
                                "type": "string",
                                "enum": [
                                  "EXACT",
                                  "INTERVAL_TIGHTENED",
                                  "DAYS_ADDED",
                                  "DAYS_SUBSTITUTED",
                                  "ALL_WORKING_DAYS",
                                  "DIRECT_FILL"
                                ],
                                "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                              },
                              "cadenceDistance": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                                "example": 2
                              },
                              "cadenceSummary": {
                                "type": "object",
                                "properties": {
                                  "requested": {
                                    "type": "integer",
                                    "nullable": true,
                                    "minimum": 0,
                                    "exclusiveMinimum": true,
                                    "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                                    "example": 4
                                  },
                                  "peak": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "exclusiveMinimum": true,
                                    "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                                    "example": 4
                                  },
                                  "average": {
                                    "type": "number",
                                    "minimum": 0,
                                    "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                                    "example": 2.25
                                  },
                                  "byWeek": {
                                    "type": "array",
                                    "items": {
                                      "type": "object",
                                      "properties": {
                                        "weekStart": {
                                          "type": "string",
                                          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                          "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                          "example": "2026-09-14"
                                        },
                                        "sessions": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                          "example": 0
                                        }
                                      },
                                      "required": ["weekStart", "sessions"]
                                    },
                                    "minItems": 1,
                                    "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                                  }
                                },
                                "required": [
                                  "requested",
                                  "peak",
                                  "average",
                                  "byWeek"
                                ],
                                "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                              },
                              "matchNotes": {
                                "type": "array",
                                "items": {
                                  "oneOf": [
                                    {
                                      "type": "object",
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "enum": ["SUPPLIER_UNAVAILABLE_WEEK"]
                                        },
                                        "component": {
                                          "type": "string",
                                          "enum": ["sessionsPerWeek"]
                                        },
                                        "weekStart": {
                                          "type": "string",
                                          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                          "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                          "example": "2026-09-14"
                                        },
                                        "evidence": {
                                          "type": "object",
                                          "properties": {
                                            "sessionsPlaced": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "description": "Sessions this slate placed in this week."
                                            },
                                            "sessionsTargeted": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "exclusiveMinimum": true,
                                              "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                            },
                                            "openingsInPool": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                              "example": 2
                                            },
                                            "supplierWorkdays": {
                                              "type": "array",
                                              "items": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "maximum": 6
                                              },
                                              "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                            }
                                          },
                                          "required": [
                                            "sessionsPlaced",
                                            "sessionsTargeted",
                                            "openingsInPool",
                                            "supplierWorkdays"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "code",
                                        "component",
                                        "weekStart",
                                        "evidence"
                                      ],
                                      "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                                    },
                                    {
                                      "type": "object",
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "enum": ["WEEK_EXCLUDED_BY_FILTERS"]
                                        },
                                        "component": {
                                          "type": "string",
                                          "enum": ["sessionsPerWeek"]
                                        },
                                        "weekStart": {
                                          "type": "string",
                                          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                          "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                          "example": "2026-09-14"
                                        },
                                        "evidence": {
                                          "type": "object",
                                          "properties": {
                                            "sessionsPlaced": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "description": "Sessions this slate placed in this week."
                                            },
                                            "sessionsTargeted": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "exclusiveMinimum": true,
                                              "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                            },
                                            "filter": {
                                              "type": "string",
                                              "enum": [
                                                "daysOfWeek",
                                                "excludeDates"
                                              ]
                                            },
                                            "supplierWorkdays": {
                                              "type": "array",
                                              "items": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "maximum": 6
                                              },
                                              "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                            },
                                            "requestedDays": {
                                              "type": "array",
                                              "items": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "maximum": 6
                                              },
                                              "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                            },
                                            "excludedDates": {
                                              "type": "array",
                                              "items": {
                                                "type": "string"
                                              }
                                            }
                                          },
                                          "required": [
                                            "sessionsPlaced",
                                            "sessionsTargeted",
                                            "filter",
                                            "supplierWorkdays"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "code",
                                        "component",
                                        "weekStart",
                                        "evidence"
                                      ],
                                      "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                                    },
                                    {
                                      "type": "object",
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "enum": ["WEEK_SUPPLY_INSUFFICIENT"]
                                        },
                                        "component": {
                                          "type": "string",
                                          "enum": ["sessionsPerWeek"]
                                        },
                                        "weekStart": {
                                          "type": "string",
                                          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                          "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                          "example": "2026-09-14"
                                        },
                                        "evidence": {
                                          "type": "object",
                                          "properties": {
                                            "sessionsPlaced": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "description": "Sessions this slate placed in this week."
                                            },
                                            "sessionsTargeted": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "exclusiveMinimum": true,
                                              "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                            },
                                            "openingsInPool": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                              "example": 2
                                            }
                                          },
                                          "required": [
                                            "sessionsPlaced",
                                            "sessionsTargeted",
                                            "openingsInPool"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "code",
                                        "component",
                                        "weekStart",
                                        "evidence"
                                      ],
                                      "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                                    },
                                    {
                                      "type": "object",
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "enum": ["WEEK_CAPPED"]
                                        },
                                        "component": {
                                          "type": "string",
                                          "enum": ["sessionsPerWeek"]
                                        },
                                        "weekStart": {
                                          "type": "string",
                                          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                          "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                          "example": "2026-09-14"
                                        },
                                        "evidence": {
                                          "type": "object",
                                          "properties": {
                                            "sessionsPlaced": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "description": "Sessions this slate placed in this week."
                                            },
                                            "sessionsTargeted": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "exclusiveMinimum": true,
                                              "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                            },
                                            "cap": {
                                              "type": "string",
                                              "enum": [
                                                "maxSessionsPerWeek",
                                                "minGapDays"
                                              ]
                                            },
                                            "capValue": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "exclusiveMinimum": true
                                            }
                                          },
                                          "required": [
                                            "sessionsPlaced",
                                            "sessionsTargeted",
                                            "cap",
                                            "capValue"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "code",
                                        "component",
                                        "weekStart",
                                        "evidence"
                                      ],
                                      "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                                    },
                                    {
                                      "type": "object",
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "enum": ["SESSIONS_EXHAUSTED"]
                                        },
                                        "component": {
                                          "type": "string",
                                          "enum": ["sessionsPerWeek"]
                                        },
                                        "weekStart": {
                                          "type": "string",
                                          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                          "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                          "example": "2026-09-14"
                                        },
                                        "evidence": {
                                          "type": "object",
                                          "properties": {
                                            "sessionsRequested": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "exclusiveMinimum": true
                                            },
                                            "sessionsPlacedBefore": {
                                              "type": "integer",
                                              "minimum": 0
                                            }
                                          },
                                          "required": [
                                            "sessionsRequested",
                                            "sessionsPlacedBefore"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "code",
                                        "component",
                                        "weekStart",
                                        "evidence"
                                      ],
                                      "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                                    },
                                    {
                                      "type": "object",
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "enum": ["CADENCE_RELAXED"]
                                        },
                                        "component": {
                                          "type": "string",
                                          "enum": ["cadence"]
                                        },
                                        "evidence": {
                                          "type": "object",
                                          "properties": {
                                            "cadenceRelaxation": {
                                              "type": "string",
                                              "enum": [
                                                "EXACT",
                                                "INTERVAL_TIGHTENED",
                                                "DAYS_ADDED",
                                                "DAYS_SUBSTITUTED",
                                                "ALL_WORKING_DAYS",
                                                "DIRECT_FILL"
                                              ],
                                              "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                            },
                                            "requestedDays": {
                                              "type": "array",
                                              "items": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "maximum": 6
                                              },
                                              "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                            },
                                            "actualDays": {
                                              "type": "array",
                                              "items": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "maximum": 6
                                              },
                                              "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                            }
                                          },
                                          "required": ["cadenceRelaxation"]
                                        }
                                      },
                                      "required": [
                                        "code",
                                        "component",
                                        "evidence"
                                      ],
                                      "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                                    },
                                    {
                                      "type": "object",
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "enum": [
                                            "SESSIONS_OUTSIDE_PREFERRED_TIMES"
                                          ]
                                        },
                                        "component": {
                                          "type": "string",
                                          "enum": ["timeOfDay"]
                                        },
                                        "evidence": {
                                          "type": "object",
                                          "properties": {
                                            "sessionIndexes": {
                                              "type": "array",
                                              "items": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              }
                                            },
                                            "localTimes": {
                                              "type": "array",
                                              "items": {
                                                "type": "string"
                                              }
                                            }
                                          },
                                          "required": [
                                            "sessionIndexes",
                                            "localTimes"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "code",
                                        "component",
                                        "evidence"
                                      ],
                                      "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                                    },
                                    {
                                      "type": "object",
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "enum": ["FIRST_SESSION_LATE"]
                                        },
                                        "component": {
                                          "type": "string",
                                          "enum": ["startDate"]
                                        },
                                        "evidence": {
                                          "type": "object",
                                          "properties": {
                                            "firstSessionDate": {
                                              "type": "string"
                                            },
                                            "windowStartDate": {
                                              "type": "string"
                                            },
                                            "dayOffset": {
                                              "type": "integer",
                                              "minimum": 0
                                            },
                                            "earlierSupplyExisted": {
                                              "type": "boolean",
                                              "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                            }
                                          },
                                          "required": [
                                            "firstSessionDate",
                                            "windowStartDate",
                                            "dayOffset",
                                            "earlierSupplyExisted"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "code",
                                        "component",
                                        "evidence"
                                      ],
                                      "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                                    },
                                    {
                                      "type": "object",
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "enum": ["PACKAGE_UNDERFILLED"]
                                        },
                                        "evidence": {
                                          "type": "object",
                                          "properties": {
                                            "sessionsRequested": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "exclusiveMinimum": true
                                            },
                                            "sessionsFilled": {
                                              "type": "integer",
                                              "minimum": 0
                                            }
                                          },
                                          "required": [
                                            "sessionsRequested",
                                            "sessionsFilled"
                                          ]
                                        }
                                      },
                                      "required": ["code", "evidence"],
                                      "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                                    }
                                  ]
                                },
                                "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                              },
                              "advice": {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["LATER_START_IMPROVES_CADENCE"]
                                  },
                                  "earliestSustainedWeek": {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                    "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                                    "example": "2026-09-14"
                                  }
                                },
                                "required": ["code", "earliestSustainedWeek"],
                                "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                              },
                              "matchScore": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 1,
                                "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                                "example": 1
                              },
                              "matchComponents": {
                                "type": "object",
                                "properties": {
                                  "startDate": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1,
                                    "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                                  },
                                  "timeOfDay": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1,
                                    "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                                  },
                                  "daysOfWeek": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1,
                                    "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                                  },
                                  "sessionsPerWeek": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1,
                                    "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                                  },
                                  "cadence": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1,
                                    "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                                  }
                                },
                                "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                              }
                            },
                            "required": [
                              "slateId",
                              "supplierId",
                              "completeness",
                              "sessionsRequested",
                              "sessionsFilled",
                              "startTimeConsistencyPercent",
                              "totalTravelTimeMins",
                              "slots",
                              "matchNotes",
                              "matchScore"
                            ]
                          },
                          "alternates": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "slateId": {
                                  "type": "string",
                                  "description": "Pass this to POST .../package-bookings to book the whole plan.",
                                  "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                                },
                                "supplierId": {
                                  "type": "string"
                                },
                                "completeness": {
                                  "type": "string",
                                  "enum": ["COMPLETE", "PARTIAL"]
                                },
                                "sessionsRequested": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true,
                                  "description": "How many sessions were requested (the package's creditCount)."
                                },
                                "sessionsFilled": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "How many of the requested sessions the plan could fill."
                                },
                                "startTimeConsistencyPercent": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 100
                                },
                                "totalTravelTimeMins": {
                                  "type": "number",
                                  "minimum": 0
                                },
                                "slots": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "slotId": {
                                        "type": "string",
                                        "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                                      },
                                      "sessionIndex": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "1-based index of this session within the slate."
                                      },
                                      "supplierId": {
                                        "type": "string"
                                      },
                                      "serviceId": {
                                        "type": "string"
                                      },
                                      "offeringId": {
                                        "type": "string"
                                      },
                                      "bookingStartUtc": {
                                        "type": "string",
                                        "format": "date-time"
                                      },
                                      "bookingEndUtc": {
                                        "type": "string",
                                        "format": "date-time"
                                      },
                                      "bookingTz": {
                                        "type": "string"
                                      },
                                      "locationType": {
                                        "type": "string",
                                        "enum": [
                                          "PHYSICAL",
                                          "VIRTUAL",
                                          "TRAVEL_ZONE"
                                        ]
                                      },
                                      "locationId": {
                                        "type": "string",
                                        "nullable": true
                                      },
                                      "latitude": {
                                        "type": "number",
                                        "nullable": true
                                      },
                                      "longitude": {
                                        "type": "number",
                                        "nullable": true
                                      },
                                      "address": {
                                        "$ref": "#/components/schemas/Address"
                                      },
                                      "travelTimeMins": {
                                        "type": "number",
                                        "nullable": true,
                                        "minimum": 0
                                      },
                                      "capacity": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true
                                      },
                                      "reservationStatus": {
                                        "type": "string",
                                        "enum": [
                                          "FREE",
                                          "HELD",
                                          "CONVERTED",
                                          "RELEASED"
                                        ]
                                      }
                                    },
                                    "required": [
                                      "slotId",
                                      "sessionIndex",
                                      "supplierId",
                                      "serviceId",
                                      "offeringId",
                                      "bookingStartUtc",
                                      "bookingEndUtc",
                                      "bookingTz",
                                      "locationType",
                                      "locationId",
                                      "latitude",
                                      "longitude",
                                      "address",
                                      "travelTimeMins",
                                      "capacity",
                                      "reservationStatus"
                                    ]
                                  }
                                },
                                "position": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                                  "example": 0
                                },
                                "cadenceRrule": {
                                  "type": "string",
                                  "nullable": true,
                                  "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                                  "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                                },
                                "matchesRequestedCadence": {
                                  "type": "boolean",
                                  "description": "True when cadenceRrule is the rrule you asked for.",
                                  "example": false
                                },
                                "cadenceRelaxation": {
                                  "type": "string",
                                  "enum": [
                                    "EXACT",
                                    "INTERVAL_TIGHTENED",
                                    "DAYS_ADDED",
                                    "DAYS_SUBSTITUTED",
                                    "ALL_WORKING_DAYS",
                                    "DIRECT_FILL"
                                  ],
                                  "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                },
                                "cadenceDistance": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                                  "example": 2
                                },
                                "cadenceSummary": {
                                  "type": "object",
                                  "properties": {
                                    "requested": {
                                      "type": "integer",
                                      "nullable": true,
                                      "minimum": 0,
                                      "exclusiveMinimum": true,
                                      "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                                      "example": 4
                                    },
                                    "peak": {
                                      "type": "integer",
                                      "minimum": 0,
                                      "exclusiveMinimum": true,
                                      "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                                      "example": 4
                                    },
                                    "average": {
                                      "type": "number",
                                      "minimum": 0,
                                      "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                                      "example": 2.25
                                    },
                                    "byWeek": {
                                      "type": "array",
                                      "items": {
                                        "type": "object",
                                        "properties": {
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                            "example": "2026-09-14"
                                          },
                                          "sessions": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                            "example": 0
                                          }
                                        },
                                        "required": ["weekStart", "sessions"]
                                      },
                                      "minItems": 1,
                                      "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                                    }
                                  },
                                  "required": [
                                    "requested",
                                    "peak",
                                    "average",
                                    "byWeek"
                                  ],
                                  "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                                },
                                "matchNotes": {
                                  "type": "array",
                                  "items": {
                                    "oneOf": [
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": [
                                              "SUPPLIER_UNAVAILABLE_WEEK"
                                            ]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "openingsInPool": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                "example": 2
                                              },
                                              "supplierWorkdays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "openingsInPool",
                                              "supplierWorkdays"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_EXCLUDED_BY_FILTERS"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "filter": {
                                                "type": "string",
                                                "enum": [
                                                  "daysOfWeek",
                                                  "excludeDates"
                                                ]
                                              },
                                              "supplierWorkdays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "requestedDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "excludedDates": {
                                                "type": "array",
                                                "items": {
                                                  "type": "string"
                                                }
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "filter",
                                              "supplierWorkdays"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_SUPPLY_INSUFFICIENT"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "openingsInPool": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                "example": 2
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "openingsInPool"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_CAPPED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "cap": {
                                                "type": "string",
                                                "enum": [
                                                  "maxSessionsPerWeek",
                                                  "minGapDays"
                                                ]
                                              },
                                              "capValue": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "cap",
                                              "capValue"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["SESSIONS_EXHAUSTED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsRequested": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              },
                                              "sessionsPlacedBefore": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "required": [
                                              "sessionsRequested",
                                              "sessionsPlacedBefore"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["CADENCE_RELAXED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["cadence"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "cadenceRelaxation": {
                                                "type": "string",
                                                "enum": [
                                                  "EXACT",
                                                  "INTERVAL_TIGHTENED",
                                                  "DAYS_ADDED",
                                                  "DAYS_SUBSTITUTED",
                                                  "ALL_WORKING_DAYS",
                                                  "DIRECT_FILL"
                                                ],
                                                "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                              },
                                              "requestedDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "actualDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              }
                                            },
                                            "required": ["cadenceRelaxation"]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": [
                                              "SESSIONS_OUTSIDE_PREFERRED_TIMES"
                                            ]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["timeOfDay"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionIndexes": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                }
                                              },
                                              "localTimes": {
                                                "type": "array",
                                                "items": {
                                                  "type": "string"
                                                }
                                              }
                                            },
                                            "required": [
                                              "sessionIndexes",
                                              "localTimes"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["FIRST_SESSION_LATE"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["startDate"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "firstSessionDate": {
                                                "type": "string"
                                              },
                                              "windowStartDate": {
                                                "type": "string"
                                              },
                                              "dayOffset": {
                                                "type": "integer",
                                                "minimum": 0
                                              },
                                              "earlierSupplyExisted": {
                                                "type": "boolean",
                                                "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                              }
                                            },
                                            "required": [
                                              "firstSessionDate",
                                              "windowStartDate",
                                              "dayOffset",
                                              "earlierSupplyExisted"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["PACKAGE_UNDERFILLED"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsRequested": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              },
                                              "sessionsFilled": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "required": [
                                              "sessionsRequested",
                                              "sessionsFilled"
                                            ]
                                          }
                                        },
                                        "required": ["code", "evidence"],
                                        "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                                      }
                                    ]
                                  },
                                  "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                                },
                                "advice": {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["LATER_START_IMPROVES_CADENCE"]
                                    },
                                    "earliestSustainedWeek": {
                                      "type": "string",
                                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                      "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                                      "example": "2026-09-14"
                                    }
                                  },
                                  "required": ["code", "earliestSustainedWeek"],
                                  "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                                },
                                "matchScore": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 1,
                                  "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                                  "example": 1
                                },
                                "matchComponents": {
                                  "type": "object",
                                  "properties": {
                                    "startDate": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                                    },
                                    "timeOfDay": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                                    },
                                    "daysOfWeek": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                                    },
                                    "sessionsPerWeek": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                                    },
                                    "cadence": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                                    }
                                  },
                                  "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                                }
                              },
                              "required": [
                                "slateId",
                                "supplierId",
                                "completeness",
                                "sessionsRequested",
                                "sessionsFilled",
                                "startTimeConsistencyPercent",
                                "totalTravelTimeMins",
                                "slots",
                                "matchNotes",
                                "matchScore"
                              ]
                            },
                            "description": "Other bookable options beyond primarySlate, ranked best first and capped at the maxAlternates you sent. Under the default supplierPolicy of SAME_SUPPLIER these are other schedules from the SAME supplier as primarySlate; under PREFERRED or ANY they are other suppliers’ best schedules, one per supplier. Two schedules from one supplier count as different options only when they run on different weekdays, or start at least 30 minutes apart — so a supplier offering 09:00 and 09:20 gives you one option, not two. Each entry’s slateId is bookable exactly like primarySlate’s."
                          },
                          "partial": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "slateId": {
                                "type": "string",
                                "description": "Pass this to POST .../package-bookings to book the whole plan.",
                                "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                              },
                              "supplierId": {
                                "type": "string"
                              },
                              "completeness": {
                                "type": "string",
                                "enum": ["COMPLETE", "PARTIAL"]
                              },
                              "sessionsRequested": {
                                "type": "integer",
                                "minimum": 0,
                                "exclusiveMinimum": true,
                                "description": "How many sessions were requested (the package's creditCount)."
                              },
                              "sessionsFilled": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "How many of the requested sessions the plan could fill."
                              },
                              "startTimeConsistencyPercent": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 100
                              },
                              "totalTravelTimeMins": {
                                "type": "number",
                                "minimum": 0
                              },
                              "slots": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "slotId": {
                                      "type": "string",
                                      "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                                    },
                                    "sessionIndex": {
                                      "type": "integer",
                                      "minimum": 0,
                                      "exclusiveMinimum": true,
                                      "description": "1-based index of this session within the slate."
                                    },
                                    "supplierId": {
                                      "type": "string"
                                    },
                                    "serviceId": {
                                      "type": "string"
                                    },
                                    "offeringId": {
                                      "type": "string"
                                    },
                                    "bookingStartUtc": {
                                      "type": "string",
                                      "format": "date-time"
                                    },
                                    "bookingEndUtc": {
                                      "type": "string",
                                      "format": "date-time"
                                    },
                                    "bookingTz": {
                                      "type": "string"
                                    },
                                    "locationType": {
                                      "type": "string",
                                      "enum": [
                                        "PHYSICAL",
                                        "VIRTUAL",
                                        "TRAVEL_ZONE"
                                      ]
                                    },
                                    "locationId": {
                                      "type": "string",
                                      "nullable": true
                                    },
                                    "latitude": {
                                      "type": "number",
                                      "nullable": true
                                    },
                                    "longitude": {
                                      "type": "number",
                                      "nullable": true
                                    },
                                    "address": {
                                      "$ref": "#/components/schemas/Address"
                                    },
                                    "travelTimeMins": {
                                      "type": "number",
                                      "nullable": true,
                                      "minimum": 0
                                    },
                                    "capacity": {
                                      "type": "integer",
                                      "minimum": 0,
                                      "exclusiveMinimum": true
                                    },
                                    "reservationStatus": {
                                      "type": "string",
                                      "enum": [
                                        "FREE",
                                        "HELD",
                                        "CONVERTED",
                                        "RELEASED"
                                      ]
                                    }
                                  },
                                  "required": [
                                    "slotId",
                                    "sessionIndex",
                                    "supplierId",
                                    "serviceId",
                                    "offeringId",
                                    "bookingStartUtc",
                                    "bookingEndUtc",
                                    "bookingTz",
                                    "locationType",
                                    "locationId",
                                    "latitude",
                                    "longitude",
                                    "address",
                                    "travelTimeMins",
                                    "capacity",
                                    "reservationStatus"
                                  ]
                                }
                              },
                              "position": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                                "example": 0
                              },
                              "cadenceRrule": {
                                "type": "string",
                                "nullable": true,
                                "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                                "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                              },
                              "matchesRequestedCadence": {
                                "type": "boolean",
                                "description": "True when cadenceRrule is the rrule you asked for.",
                                "example": false
                              },
                              "cadenceRelaxation": {
                                "type": "string",
                                "enum": [
                                  "EXACT",
                                  "INTERVAL_TIGHTENED",
                                  "DAYS_ADDED",
                                  "DAYS_SUBSTITUTED",
                                  "ALL_WORKING_DAYS",
                                  "DIRECT_FILL"
                                ],
                                "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                              },
                              "cadenceDistance": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                                "example": 2
                              },
                              "cadenceSummary": {
                                "type": "object",
                                "properties": {
                                  "requested": {
                                    "type": "integer",
                                    "nullable": true,
                                    "minimum": 0,
                                    "exclusiveMinimum": true,
                                    "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                                    "example": 4
                                  },
                                  "peak": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "exclusiveMinimum": true,
                                    "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                                    "example": 4
                                  },
                                  "average": {
                                    "type": "number",
                                    "minimum": 0,
                                    "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                                    "example": 2.25
                                  },
                                  "byWeek": {
                                    "type": "array",
                                    "items": {
                                      "type": "object",
                                      "properties": {
                                        "weekStart": {
                                          "type": "string",
                                          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                          "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                          "example": "2026-09-14"
                                        },
                                        "sessions": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                          "example": 0
                                        }
                                      },
                                      "required": ["weekStart", "sessions"]
                                    },
                                    "minItems": 1,
                                    "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                                  }
                                },
                                "required": [
                                  "requested",
                                  "peak",
                                  "average",
                                  "byWeek"
                                ],
                                "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                              },
                              "matchNotes": {
                                "type": "array",
                                "items": {
                                  "oneOf": [
                                    {
                                      "type": "object",
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "enum": ["SUPPLIER_UNAVAILABLE_WEEK"]
                                        },
                                        "component": {
                                          "type": "string",
                                          "enum": ["sessionsPerWeek"]
                                        },
                                        "weekStart": {
                                          "type": "string",
                                          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                          "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                          "example": "2026-09-14"
                                        },
                                        "evidence": {
                                          "type": "object",
                                          "properties": {
                                            "sessionsPlaced": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "description": "Sessions this slate placed in this week."
                                            },
                                            "sessionsTargeted": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "exclusiveMinimum": true,
                                              "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                            },
                                            "openingsInPool": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                              "example": 2
                                            },
                                            "supplierWorkdays": {
                                              "type": "array",
                                              "items": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "maximum": 6
                                              },
                                              "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                            }
                                          },
                                          "required": [
                                            "sessionsPlaced",
                                            "sessionsTargeted",
                                            "openingsInPool",
                                            "supplierWorkdays"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "code",
                                        "component",
                                        "weekStart",
                                        "evidence"
                                      ],
                                      "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                                    },
                                    {
                                      "type": "object",
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "enum": ["WEEK_EXCLUDED_BY_FILTERS"]
                                        },
                                        "component": {
                                          "type": "string",
                                          "enum": ["sessionsPerWeek"]
                                        },
                                        "weekStart": {
                                          "type": "string",
                                          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                          "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                          "example": "2026-09-14"
                                        },
                                        "evidence": {
                                          "type": "object",
                                          "properties": {
                                            "sessionsPlaced": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "description": "Sessions this slate placed in this week."
                                            },
                                            "sessionsTargeted": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "exclusiveMinimum": true,
                                              "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                            },
                                            "filter": {
                                              "type": "string",
                                              "enum": [
                                                "daysOfWeek",
                                                "excludeDates"
                                              ]
                                            },
                                            "supplierWorkdays": {
                                              "type": "array",
                                              "items": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "maximum": 6
                                              },
                                              "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                            },
                                            "requestedDays": {
                                              "type": "array",
                                              "items": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "maximum": 6
                                              },
                                              "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                            },
                                            "excludedDates": {
                                              "type": "array",
                                              "items": {
                                                "type": "string"
                                              }
                                            }
                                          },
                                          "required": [
                                            "sessionsPlaced",
                                            "sessionsTargeted",
                                            "filter",
                                            "supplierWorkdays"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "code",
                                        "component",
                                        "weekStart",
                                        "evidence"
                                      ],
                                      "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                                    },
                                    {
                                      "type": "object",
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "enum": ["WEEK_SUPPLY_INSUFFICIENT"]
                                        },
                                        "component": {
                                          "type": "string",
                                          "enum": ["sessionsPerWeek"]
                                        },
                                        "weekStart": {
                                          "type": "string",
                                          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                          "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                          "example": "2026-09-14"
                                        },
                                        "evidence": {
                                          "type": "object",
                                          "properties": {
                                            "sessionsPlaced": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "description": "Sessions this slate placed in this week."
                                            },
                                            "sessionsTargeted": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "exclusiveMinimum": true,
                                              "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                            },
                                            "openingsInPool": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                              "example": 2
                                            }
                                          },
                                          "required": [
                                            "sessionsPlaced",
                                            "sessionsTargeted",
                                            "openingsInPool"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "code",
                                        "component",
                                        "weekStart",
                                        "evidence"
                                      ],
                                      "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                                    },
                                    {
                                      "type": "object",
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "enum": ["WEEK_CAPPED"]
                                        },
                                        "component": {
                                          "type": "string",
                                          "enum": ["sessionsPerWeek"]
                                        },
                                        "weekStart": {
                                          "type": "string",
                                          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                          "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                          "example": "2026-09-14"
                                        },
                                        "evidence": {
                                          "type": "object",
                                          "properties": {
                                            "sessionsPlaced": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "description": "Sessions this slate placed in this week."
                                            },
                                            "sessionsTargeted": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "exclusiveMinimum": true,
                                              "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                            },
                                            "cap": {
                                              "type": "string",
                                              "enum": [
                                                "maxSessionsPerWeek",
                                                "minGapDays"
                                              ]
                                            },
                                            "capValue": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "exclusiveMinimum": true
                                            }
                                          },
                                          "required": [
                                            "sessionsPlaced",
                                            "sessionsTargeted",
                                            "cap",
                                            "capValue"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "code",
                                        "component",
                                        "weekStart",
                                        "evidence"
                                      ],
                                      "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                                    },
                                    {
                                      "type": "object",
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "enum": ["SESSIONS_EXHAUSTED"]
                                        },
                                        "component": {
                                          "type": "string",
                                          "enum": ["sessionsPerWeek"]
                                        },
                                        "weekStart": {
                                          "type": "string",
                                          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                          "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                          "example": "2026-09-14"
                                        },
                                        "evidence": {
                                          "type": "object",
                                          "properties": {
                                            "sessionsRequested": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "exclusiveMinimum": true
                                            },
                                            "sessionsPlacedBefore": {
                                              "type": "integer",
                                              "minimum": 0
                                            }
                                          },
                                          "required": [
                                            "sessionsRequested",
                                            "sessionsPlacedBefore"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "code",
                                        "component",
                                        "weekStart",
                                        "evidence"
                                      ],
                                      "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                                    },
                                    {
                                      "type": "object",
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "enum": ["CADENCE_RELAXED"]
                                        },
                                        "component": {
                                          "type": "string",
                                          "enum": ["cadence"]
                                        },
                                        "evidence": {
                                          "type": "object",
                                          "properties": {
                                            "cadenceRelaxation": {
                                              "type": "string",
                                              "enum": [
                                                "EXACT",
                                                "INTERVAL_TIGHTENED",
                                                "DAYS_ADDED",
                                                "DAYS_SUBSTITUTED",
                                                "ALL_WORKING_DAYS",
                                                "DIRECT_FILL"
                                              ],
                                              "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                            },
                                            "requestedDays": {
                                              "type": "array",
                                              "items": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "maximum": 6
                                              },
                                              "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                            },
                                            "actualDays": {
                                              "type": "array",
                                              "items": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "maximum": 6
                                              },
                                              "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                            }
                                          },
                                          "required": ["cadenceRelaxation"]
                                        }
                                      },
                                      "required": [
                                        "code",
                                        "component",
                                        "evidence"
                                      ],
                                      "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                                    },
                                    {
                                      "type": "object",
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "enum": [
                                            "SESSIONS_OUTSIDE_PREFERRED_TIMES"
                                          ]
                                        },
                                        "component": {
                                          "type": "string",
                                          "enum": ["timeOfDay"]
                                        },
                                        "evidence": {
                                          "type": "object",
                                          "properties": {
                                            "sessionIndexes": {
                                              "type": "array",
                                              "items": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              }
                                            },
                                            "localTimes": {
                                              "type": "array",
                                              "items": {
                                                "type": "string"
                                              }
                                            }
                                          },
                                          "required": [
                                            "sessionIndexes",
                                            "localTimes"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "code",
                                        "component",
                                        "evidence"
                                      ],
                                      "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                                    },
                                    {
                                      "type": "object",
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "enum": ["FIRST_SESSION_LATE"]
                                        },
                                        "component": {
                                          "type": "string",
                                          "enum": ["startDate"]
                                        },
                                        "evidence": {
                                          "type": "object",
                                          "properties": {
                                            "firstSessionDate": {
                                              "type": "string"
                                            },
                                            "windowStartDate": {
                                              "type": "string"
                                            },
                                            "dayOffset": {
                                              "type": "integer",
                                              "minimum": 0
                                            },
                                            "earlierSupplyExisted": {
                                              "type": "boolean",
                                              "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                            }
                                          },
                                          "required": [
                                            "firstSessionDate",
                                            "windowStartDate",
                                            "dayOffset",
                                            "earlierSupplyExisted"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "code",
                                        "component",
                                        "evidence"
                                      ],
                                      "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                                    },
                                    {
                                      "type": "object",
                                      "properties": {
                                        "code": {
                                          "type": "string",
                                          "enum": ["PACKAGE_UNDERFILLED"]
                                        },
                                        "evidence": {
                                          "type": "object",
                                          "properties": {
                                            "sessionsRequested": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "exclusiveMinimum": true
                                            },
                                            "sessionsFilled": {
                                              "type": "integer",
                                              "minimum": 0
                                            }
                                          },
                                          "required": [
                                            "sessionsRequested",
                                            "sessionsFilled"
                                          ]
                                        }
                                      },
                                      "required": ["code", "evidence"],
                                      "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                                    }
                                  ]
                                },
                                "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                              },
                              "advice": {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["LATER_START_IMPROVES_CADENCE"]
                                  },
                                  "earliestSustainedWeek": {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                    "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                                    "example": "2026-09-14"
                                  }
                                },
                                "required": ["code", "earliestSustainedWeek"],
                                "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                              },
                              "matchScore": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 1,
                                "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                                "example": 1
                              },
                              "matchComponents": {
                                "type": "object",
                                "properties": {
                                  "startDate": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1,
                                    "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                                  },
                                  "timeOfDay": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1,
                                    "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                                  },
                                  "daysOfWeek": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1,
                                    "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                                  },
                                  "sessionsPerWeek": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1,
                                    "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                                  },
                                  "cadence": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1,
                                    "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                                  }
                                },
                                "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                              }
                            },
                            "required": [
                              "slateId",
                              "supplierId",
                              "completeness",
                              "sessionsRequested",
                              "sessionsFilled",
                              "startTimeConsistencyPercent",
                              "totalTravelTimeMins",
                              "slots",
                              "matchNotes",
                              "matchScore"
                            ]
                          },
                          "cadenceAlternatives": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "slateId": {
                                  "type": "string",
                                  "description": "Pass this to POST .../package-bookings to book the whole plan.",
                                  "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                                },
                                "supplierId": {
                                  "type": "string"
                                },
                                "completeness": {
                                  "type": "string",
                                  "enum": ["COMPLETE", "PARTIAL"]
                                },
                                "sessionsRequested": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true,
                                  "description": "How many sessions were requested (the package's creditCount)."
                                },
                                "sessionsFilled": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "How many of the requested sessions the plan could fill."
                                },
                                "startTimeConsistencyPercent": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 100
                                },
                                "totalTravelTimeMins": {
                                  "type": "number",
                                  "minimum": 0
                                },
                                "slots": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "slotId": {
                                        "type": "string",
                                        "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                                      },
                                      "sessionIndex": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "1-based index of this session within the slate."
                                      },
                                      "supplierId": {
                                        "type": "string"
                                      },
                                      "serviceId": {
                                        "type": "string"
                                      },
                                      "offeringId": {
                                        "type": "string"
                                      },
                                      "bookingStartUtc": {
                                        "type": "string",
                                        "format": "date-time"
                                      },
                                      "bookingEndUtc": {
                                        "type": "string",
                                        "format": "date-time"
                                      },
                                      "bookingTz": {
                                        "type": "string"
                                      },
                                      "locationType": {
                                        "type": "string",
                                        "enum": [
                                          "PHYSICAL",
                                          "VIRTUAL",
                                          "TRAVEL_ZONE"
                                        ]
                                      },
                                      "locationId": {
                                        "type": "string",
                                        "nullable": true
                                      },
                                      "latitude": {
                                        "type": "number",
                                        "nullable": true
                                      },
                                      "longitude": {
                                        "type": "number",
                                        "nullable": true
                                      },
                                      "address": {
                                        "$ref": "#/components/schemas/Address"
                                      },
                                      "travelTimeMins": {
                                        "type": "number",
                                        "nullable": true,
                                        "minimum": 0
                                      },
                                      "capacity": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true
                                      },
                                      "reservationStatus": {
                                        "type": "string",
                                        "enum": [
                                          "FREE",
                                          "HELD",
                                          "CONVERTED",
                                          "RELEASED"
                                        ]
                                      }
                                    },
                                    "required": [
                                      "slotId",
                                      "sessionIndex",
                                      "supplierId",
                                      "serviceId",
                                      "offeringId",
                                      "bookingStartUtc",
                                      "bookingEndUtc",
                                      "bookingTz",
                                      "locationType",
                                      "locationId",
                                      "latitude",
                                      "longitude",
                                      "address",
                                      "travelTimeMins",
                                      "capacity",
                                      "reservationStatus"
                                    ]
                                  }
                                },
                                "position": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                                  "example": 0
                                },
                                "cadenceRrule": {
                                  "type": "string",
                                  "nullable": true,
                                  "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                                  "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                                },
                                "matchesRequestedCadence": {
                                  "type": "boolean",
                                  "description": "True when cadenceRrule is the rrule you asked for.",
                                  "example": false
                                },
                                "cadenceRelaxation": {
                                  "type": "string",
                                  "enum": [
                                    "EXACT",
                                    "INTERVAL_TIGHTENED",
                                    "DAYS_ADDED",
                                    "DAYS_SUBSTITUTED",
                                    "ALL_WORKING_DAYS",
                                    "DIRECT_FILL"
                                  ],
                                  "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                },
                                "cadenceDistance": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                                  "example": 2
                                },
                                "cadenceSummary": {
                                  "type": "object",
                                  "properties": {
                                    "requested": {
                                      "type": "integer",
                                      "nullable": true,
                                      "minimum": 0,
                                      "exclusiveMinimum": true,
                                      "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                                      "example": 4
                                    },
                                    "peak": {
                                      "type": "integer",
                                      "minimum": 0,
                                      "exclusiveMinimum": true,
                                      "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                                      "example": 4
                                    },
                                    "average": {
                                      "type": "number",
                                      "minimum": 0,
                                      "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                                      "example": 2.25
                                    },
                                    "byWeek": {
                                      "type": "array",
                                      "items": {
                                        "type": "object",
                                        "properties": {
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                            "example": "2026-09-14"
                                          },
                                          "sessions": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                            "example": 0
                                          }
                                        },
                                        "required": ["weekStart", "sessions"]
                                      },
                                      "minItems": 1,
                                      "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                                    }
                                  },
                                  "required": [
                                    "requested",
                                    "peak",
                                    "average",
                                    "byWeek"
                                  ],
                                  "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                                },
                                "matchNotes": {
                                  "type": "array",
                                  "items": {
                                    "oneOf": [
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": [
                                              "SUPPLIER_UNAVAILABLE_WEEK"
                                            ]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "openingsInPool": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                "example": 2
                                              },
                                              "supplierWorkdays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "openingsInPool",
                                              "supplierWorkdays"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_EXCLUDED_BY_FILTERS"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "filter": {
                                                "type": "string",
                                                "enum": [
                                                  "daysOfWeek",
                                                  "excludeDates"
                                                ]
                                              },
                                              "supplierWorkdays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "requestedDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "excludedDates": {
                                                "type": "array",
                                                "items": {
                                                  "type": "string"
                                                }
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "filter",
                                              "supplierWorkdays"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_SUPPLY_INSUFFICIENT"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "openingsInPool": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                "example": 2
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "openingsInPool"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_CAPPED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "cap": {
                                                "type": "string",
                                                "enum": [
                                                  "maxSessionsPerWeek",
                                                  "minGapDays"
                                                ]
                                              },
                                              "capValue": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "cap",
                                              "capValue"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["SESSIONS_EXHAUSTED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsRequested": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              },
                                              "sessionsPlacedBefore": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "required": [
                                              "sessionsRequested",
                                              "sessionsPlacedBefore"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["CADENCE_RELAXED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["cadence"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "cadenceRelaxation": {
                                                "type": "string",
                                                "enum": [
                                                  "EXACT",
                                                  "INTERVAL_TIGHTENED",
                                                  "DAYS_ADDED",
                                                  "DAYS_SUBSTITUTED",
                                                  "ALL_WORKING_DAYS",
                                                  "DIRECT_FILL"
                                                ],
                                                "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                              },
                                              "requestedDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "actualDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              }
                                            },
                                            "required": ["cadenceRelaxation"]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": [
                                              "SESSIONS_OUTSIDE_PREFERRED_TIMES"
                                            ]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["timeOfDay"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionIndexes": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                }
                                              },
                                              "localTimes": {
                                                "type": "array",
                                                "items": {
                                                  "type": "string"
                                                }
                                              }
                                            },
                                            "required": [
                                              "sessionIndexes",
                                              "localTimes"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["FIRST_SESSION_LATE"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["startDate"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "firstSessionDate": {
                                                "type": "string"
                                              },
                                              "windowStartDate": {
                                                "type": "string"
                                              },
                                              "dayOffset": {
                                                "type": "integer",
                                                "minimum": 0
                                              },
                                              "earlierSupplyExisted": {
                                                "type": "boolean",
                                                "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                              }
                                            },
                                            "required": [
                                              "firstSessionDate",
                                              "windowStartDate",
                                              "dayOffset",
                                              "earlierSupplyExisted"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["PACKAGE_UNDERFILLED"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsRequested": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              },
                                              "sessionsFilled": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "required": [
                                              "sessionsRequested",
                                              "sessionsFilled"
                                            ]
                                          }
                                        },
                                        "required": ["code", "evidence"],
                                        "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                                      }
                                    ]
                                  },
                                  "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                                },
                                "advice": {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["LATER_START_IMPROVES_CADENCE"]
                                    },
                                    "earliestSustainedWeek": {
                                      "type": "string",
                                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                      "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                                      "example": "2026-09-14"
                                    }
                                  },
                                  "required": ["code", "earliestSustainedWeek"],
                                  "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                                },
                                "matchScore": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 1,
                                  "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                                  "example": 1
                                },
                                "matchComponents": {
                                  "type": "object",
                                  "properties": {
                                    "startDate": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                                    },
                                    "timeOfDay": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                                    },
                                    "daysOfWeek": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                                    },
                                    "sessionsPerWeek": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                                    },
                                    "cadence": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                                    }
                                  },
                                  "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                                }
                              },
                              "required": [
                                "slateId",
                                "supplierId",
                                "completeness",
                                "sessionsRequested",
                                "sessionsFilled",
                                "startTimeConsistencyPercent",
                                "totalTravelTimeMins",
                                "slots",
                                "matchNotes",
                                "matchScore"
                              ]
                            },
                            "default": [],
                            "description": "Complete slates for THIS package at a cadence other than the one requested. See PackageSlateResponse.cadenceAlternatives."
                          }
                        },
                        "required": [
                          "package",
                          "status",
                          "reason",
                          "slateId",
                          "primarySlate",
                          "alternates",
                          "partial"
                        ]
                      }
                    }
                  },
                  "required": ["searchId", "data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Service not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/suggestions/slots/{slotId}/reschedule": {
      "post": {
        "tags": ["Suggestions"],
        "summary": "Reschedule a suggested slot to a new time (server-validated), refreshing its slate",
        "description": "Moves ONE slot of a proposed slate to a time the client picked, before anything is booked. This is the \"actually, can we do Thursday instead\" step of a multi-session proposal — it does not touch bookings, which have their own reschedule route. The new time is validated against the supplier's real availability rather than trusted, and on success the parent slate's aggregates are recomputed and the whole updated slate is returned, so re-render from this response instead of patching the one slot locally.\n\nNearly everything that goes wrong is a 409, and the four causes need different handling — branch on the `code`, never on the status alone. The time may be held or booked on the supplier's calendar, in which case the body names the blocking reservation or booking. The supplier may simply not work then, though the time is valid and in the future. You may have lost a race to a concurrent hold, which returns SLOT_NO_LONGER_FREE and is worth one retry at a different time. Or the suggestion itself may have expired — and that response carries a freshly computed set of suggestions with it, so re-render those rather than starting a new availability search. A past or malformed `bookingStartUtc` is a 400.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "required": true,
            "name": "slotId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "New bookingStartUtc",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "bookingStartUtc": {
                    "type": "string",
                    "format": "date-time",
                    "description": "The slot's new start, as a UTC instant. The end keeps the slot's duration; its zone and location are unchanged.",
                    "example": "2030-07-06T20:00:00.000Z"
                  }
                },
                "required": ["bookingStartUtc"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Slot moved; updated slate returned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slotId": {
                      "type": "string"
                    },
                    "slate": {
                      "type": "object",
                      "properties": {
                        "slateId": {
                          "type": "string",
                          "description": "Pass this to POST .../package-bookings to book the whole plan.",
                          "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                        },
                        "supplierId": {
                          "type": "string"
                        },
                        "completeness": {
                          "type": "string",
                          "enum": ["COMPLETE", "PARTIAL"]
                        },
                        "sessionsRequested": {
                          "type": "integer",
                          "minimum": 0,
                          "exclusiveMinimum": true,
                          "description": "How many sessions were requested (the package's creditCount)."
                        },
                        "sessionsFilled": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "How many of the requested sessions the plan could fill."
                        },
                        "startTimeConsistencyPercent": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 100
                        },
                        "totalTravelTimeMins": {
                          "type": "number",
                          "minimum": 0
                        },
                        "slots": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "slotId": {
                                "type": "string",
                                "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                              },
                              "sessionIndex": {
                                "type": "integer",
                                "minimum": 0,
                                "exclusiveMinimum": true,
                                "description": "1-based index of this session within the slate."
                              },
                              "supplierId": {
                                "type": "string"
                              },
                              "serviceId": {
                                "type": "string"
                              },
                              "offeringId": {
                                "type": "string"
                              },
                              "bookingStartUtc": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "bookingEndUtc": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "bookingTz": {
                                "type": "string"
                              },
                              "locationType": {
                                "type": "string",
                                "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"]
                              },
                              "locationId": {
                                "type": "string",
                                "nullable": true
                              },
                              "latitude": {
                                "type": "number",
                                "nullable": true
                              },
                              "longitude": {
                                "type": "number",
                                "nullable": true
                              },
                              "address": {
                                "$ref": "#/components/schemas/Address"
                              },
                              "travelTimeMins": {
                                "type": "number",
                                "nullable": true,
                                "minimum": 0
                              },
                              "capacity": {
                                "type": "integer",
                                "minimum": 0,
                                "exclusiveMinimum": true
                              },
                              "reservationStatus": {
                                "type": "string",
                                "enum": [
                                  "FREE",
                                  "HELD",
                                  "CONVERTED",
                                  "RELEASED"
                                ]
                              }
                            },
                            "required": [
                              "slotId",
                              "sessionIndex",
                              "supplierId",
                              "serviceId",
                              "offeringId",
                              "bookingStartUtc",
                              "bookingEndUtc",
                              "bookingTz",
                              "locationType",
                              "locationId",
                              "latitude",
                              "longitude",
                              "address",
                              "travelTimeMins",
                              "capacity",
                              "reservationStatus"
                            ]
                          }
                        },
                        "position": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                          "example": 0
                        },
                        "cadenceRrule": {
                          "type": "string",
                          "nullable": true,
                          "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                          "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                        },
                        "matchesRequestedCadence": {
                          "type": "boolean",
                          "description": "True when cadenceRrule is the rrule you asked for.",
                          "example": false
                        },
                        "cadenceRelaxation": {
                          "type": "string",
                          "enum": [
                            "EXACT",
                            "INTERVAL_TIGHTENED",
                            "DAYS_ADDED",
                            "DAYS_SUBSTITUTED",
                            "ALL_WORKING_DAYS",
                            "DIRECT_FILL"
                          ],
                          "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                        },
                        "cadenceDistance": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                          "example": 2
                        },
                        "cadenceSummary": {
                          "type": "object",
                          "properties": {
                            "requested": {
                              "type": "integer",
                              "nullable": true,
                              "minimum": 0,
                              "exclusiveMinimum": true,
                              "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                              "example": 4
                            },
                            "peak": {
                              "type": "integer",
                              "minimum": 0,
                              "exclusiveMinimum": true,
                              "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                              "example": 4
                            },
                            "average": {
                              "type": "number",
                              "minimum": 0,
                              "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                              "example": 2.25
                            },
                            "byWeek": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "weekStart": {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                    "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                    "example": "2026-09-14"
                                  },
                                  "sessions": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                    "example": 0
                                  }
                                },
                                "required": ["weekStart", "sessions"]
                              },
                              "minItems": 1,
                              "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                            }
                          },
                          "required": [
                            "requested",
                            "peak",
                            "average",
                            "byWeek"
                          ],
                          "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                        },
                        "matchNotes": {
                          "type": "array",
                          "items": {
                            "oneOf": [
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["SUPPLIER_UNAVAILABLE_WEEK"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["sessionsPerWeek"]
                                  },
                                  "weekStart": {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                    "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                    "example": "2026-09-14"
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionsPlaced": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "description": "Sessions this slate placed in this week."
                                      },
                                      "sessionsTargeted": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                      },
                                      "openingsInPool": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                        "example": 2
                                      },
                                      "supplierWorkdays": {
                                        "type": "array",
                                        "items": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 6
                                        },
                                        "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                      }
                                    },
                                    "required": [
                                      "sessionsPlaced",
                                      "sessionsTargeted",
                                      "openingsInPool",
                                      "supplierWorkdays"
                                    ]
                                  }
                                },
                                "required": [
                                  "code",
                                  "component",
                                  "weekStart",
                                  "evidence"
                                ],
                                "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["WEEK_EXCLUDED_BY_FILTERS"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["sessionsPerWeek"]
                                  },
                                  "weekStart": {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                    "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                    "example": "2026-09-14"
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionsPlaced": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "description": "Sessions this slate placed in this week."
                                      },
                                      "sessionsTargeted": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                      },
                                      "filter": {
                                        "type": "string",
                                        "enum": ["daysOfWeek", "excludeDates"]
                                      },
                                      "supplierWorkdays": {
                                        "type": "array",
                                        "items": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 6
                                        },
                                        "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                      },
                                      "requestedDays": {
                                        "type": "array",
                                        "items": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 6
                                        },
                                        "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                      },
                                      "excludedDates": {
                                        "type": "array",
                                        "items": {
                                          "type": "string"
                                        }
                                      }
                                    },
                                    "required": [
                                      "sessionsPlaced",
                                      "sessionsTargeted",
                                      "filter",
                                      "supplierWorkdays"
                                    ]
                                  }
                                },
                                "required": [
                                  "code",
                                  "component",
                                  "weekStart",
                                  "evidence"
                                ],
                                "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["WEEK_SUPPLY_INSUFFICIENT"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["sessionsPerWeek"]
                                  },
                                  "weekStart": {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                    "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                    "example": "2026-09-14"
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionsPlaced": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "description": "Sessions this slate placed in this week."
                                      },
                                      "sessionsTargeted": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                      },
                                      "openingsInPool": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                        "example": 2
                                      }
                                    },
                                    "required": [
                                      "sessionsPlaced",
                                      "sessionsTargeted",
                                      "openingsInPool"
                                    ]
                                  }
                                },
                                "required": [
                                  "code",
                                  "component",
                                  "weekStart",
                                  "evidence"
                                ],
                                "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["WEEK_CAPPED"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["sessionsPerWeek"]
                                  },
                                  "weekStart": {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                    "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                    "example": "2026-09-14"
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionsPlaced": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "description": "Sessions this slate placed in this week."
                                      },
                                      "sessionsTargeted": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                      },
                                      "cap": {
                                        "type": "string",
                                        "enum": [
                                          "maxSessionsPerWeek",
                                          "minGapDays"
                                        ]
                                      },
                                      "capValue": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true
                                      }
                                    },
                                    "required": [
                                      "sessionsPlaced",
                                      "sessionsTargeted",
                                      "cap",
                                      "capValue"
                                    ]
                                  }
                                },
                                "required": [
                                  "code",
                                  "component",
                                  "weekStart",
                                  "evidence"
                                ],
                                "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["SESSIONS_EXHAUSTED"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["sessionsPerWeek"]
                                  },
                                  "weekStart": {
                                    "type": "string",
                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                    "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                    "example": "2026-09-14"
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionsRequested": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true
                                      },
                                      "sessionsPlacedBefore": {
                                        "type": "integer",
                                        "minimum": 0
                                      }
                                    },
                                    "required": [
                                      "sessionsRequested",
                                      "sessionsPlacedBefore"
                                    ]
                                  }
                                },
                                "required": [
                                  "code",
                                  "component",
                                  "weekStart",
                                  "evidence"
                                ],
                                "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["CADENCE_RELAXED"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["cadence"]
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "cadenceRelaxation": {
                                        "type": "string",
                                        "enum": [
                                          "EXACT",
                                          "INTERVAL_TIGHTENED",
                                          "DAYS_ADDED",
                                          "DAYS_SUBSTITUTED",
                                          "ALL_WORKING_DAYS",
                                          "DIRECT_FILL"
                                        ],
                                        "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                      },
                                      "requestedDays": {
                                        "type": "array",
                                        "items": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 6
                                        },
                                        "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                      },
                                      "actualDays": {
                                        "type": "array",
                                        "items": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "maximum": 6
                                        },
                                        "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                      }
                                    },
                                    "required": ["cadenceRelaxation"]
                                  }
                                },
                                "required": ["code", "component", "evidence"],
                                "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["SESSIONS_OUTSIDE_PREFERRED_TIMES"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["timeOfDay"]
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionIndexes": {
                                        "type": "array",
                                        "items": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true
                                        }
                                      },
                                      "localTimes": {
                                        "type": "array",
                                        "items": {
                                          "type": "string"
                                        }
                                      }
                                    },
                                    "required": ["sessionIndexes", "localTimes"]
                                  }
                                },
                                "required": ["code", "component", "evidence"],
                                "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["FIRST_SESSION_LATE"]
                                  },
                                  "component": {
                                    "type": "string",
                                    "enum": ["startDate"]
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "firstSessionDate": {
                                        "type": "string"
                                      },
                                      "windowStartDate": {
                                        "type": "string"
                                      },
                                      "dayOffset": {
                                        "type": "integer",
                                        "minimum": 0
                                      },
                                      "earlierSupplyExisted": {
                                        "type": "boolean",
                                        "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                      }
                                    },
                                    "required": [
                                      "firstSessionDate",
                                      "windowStartDate",
                                      "dayOffset",
                                      "earlierSupplyExisted"
                                    ]
                                  }
                                },
                                "required": ["code", "component", "evidence"],
                                "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string",
                                    "enum": ["PACKAGE_UNDERFILLED"]
                                  },
                                  "evidence": {
                                    "type": "object",
                                    "properties": {
                                      "sessionsRequested": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true
                                      },
                                      "sessionsFilled": {
                                        "type": "integer",
                                        "minimum": 0
                                      }
                                    },
                                    "required": [
                                      "sessionsRequested",
                                      "sessionsFilled"
                                    ]
                                  }
                                },
                                "required": ["code", "evidence"],
                                "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                              }
                            ]
                          },
                          "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                        },
                        "advice": {
                          "type": "object",
                          "properties": {
                            "code": {
                              "type": "string",
                              "enum": ["LATER_START_IMPROVES_CADENCE"]
                            },
                            "earliestSustainedWeek": {
                              "type": "string",
                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                              "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                              "example": "2026-09-14"
                            }
                          },
                          "required": ["code", "earliestSustainedWeek"],
                          "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                        },
                        "matchScore": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 1,
                          "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                          "example": 1
                        },
                        "matchComponents": {
                          "type": "object",
                          "properties": {
                            "startDate": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1,
                              "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                            },
                            "timeOfDay": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1,
                              "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                            },
                            "daysOfWeek": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1,
                              "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                            },
                            "sessionsPerWeek": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1,
                              "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                            },
                            "cadence": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1,
                              "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                            }
                          },
                          "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                        }
                      },
                      "required": [
                        "slateId",
                        "supplierId",
                        "completeness",
                        "sessionsRequested",
                        "sessionsFilled",
                        "startTimeConsistencyPercent",
                        "totalTravelTimeMins",
                        "slots",
                        "matchNotes",
                        "matchScore"
                      ]
                    }
                  },
                  "required": ["slotId", "slate"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error (bad/past time)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "Requested time unavailable, held/booked on the supplier calendar, or the suggestion is stale",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "statusCode": {
                          "type": "number",
                          "enum": [409],
                          "description": "The HTTP status, repeated in the body — every MarketBox error carries it, so you can branch on the body alone.",
                          "example": 409
                        },
                        "requestId": {
                          "type": "string",
                          "description": "The id of this request (also returned as the X-Request-Id header). Quote it in a support ticket.",
                          "example": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
                        },
                        "freshSuggestions": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "searchId": {
                              "type": "string",
                              "description": "The id of this search, also returned as the `X-MB-Search-Id` header. Every page of a paginated search carries the same id (the cursor keeps it). Keep it for the session if you want attribution: pass it back as `searchId` when the client books, and in the `search.rendered` event when you report what you showed.",
                              "example": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
                            },
                            "status": {
                              "type": "string",
                              "enum": [
                                "OK",
                                "ALTERNATIVE_CADENCE",
                                "NO_COMPLETE_SLATE",
                                "NO_AVAILABILITY"
                              ],
                              "description": "OK, ALTERNATIVE_CADENCE, NO_COMPLETE_SLATE, or NO_AVAILABILITY. ALTERNATIVE_CADENCE is only reachable when this request opted in via cadenceFlexibility or guaranteeSlate — a request sending today’s body (neither set) never observes it."
                            },
                            "reason": {
                              "type": "string",
                              "nullable": true
                            },
                            "suggestionRequestId": {
                              "type": "string",
                              "nullable": true,
                              "description": "Audit id for this suggestion request (present when persisted)."
                            },
                            "resolvableUntil": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "primarySlate": {
                              "type": "object",
                              "nullable": true,
                              "properties": {
                                "slateId": {
                                  "type": "string",
                                  "description": "Pass this to POST .../package-bookings to book the whole plan.",
                                  "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                                },
                                "supplierId": {
                                  "type": "string"
                                },
                                "completeness": {
                                  "type": "string",
                                  "enum": ["COMPLETE", "PARTIAL"]
                                },
                                "sessionsRequested": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true,
                                  "description": "How many sessions were requested (the package's creditCount)."
                                },
                                "sessionsFilled": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "How many of the requested sessions the plan could fill."
                                },
                                "startTimeConsistencyPercent": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 100
                                },
                                "totalTravelTimeMins": {
                                  "type": "number",
                                  "minimum": 0
                                },
                                "slots": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "slotId": {
                                        "type": "string",
                                        "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                                      },
                                      "sessionIndex": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "1-based index of this session within the slate."
                                      },
                                      "supplierId": {
                                        "type": "string"
                                      },
                                      "serviceId": {
                                        "type": "string"
                                      },
                                      "offeringId": {
                                        "type": "string"
                                      },
                                      "bookingStartUtc": {
                                        "type": "string",
                                        "format": "date-time"
                                      },
                                      "bookingEndUtc": {
                                        "type": "string",
                                        "format": "date-time"
                                      },
                                      "bookingTz": {
                                        "type": "string"
                                      },
                                      "locationType": {
                                        "type": "string",
                                        "enum": [
                                          "PHYSICAL",
                                          "VIRTUAL",
                                          "TRAVEL_ZONE"
                                        ]
                                      },
                                      "locationId": {
                                        "type": "string",
                                        "nullable": true
                                      },
                                      "latitude": {
                                        "type": "number",
                                        "nullable": true
                                      },
                                      "longitude": {
                                        "type": "number",
                                        "nullable": true
                                      },
                                      "address": {
                                        "$ref": "#/components/schemas/Address"
                                      },
                                      "travelTimeMins": {
                                        "type": "number",
                                        "nullable": true,
                                        "minimum": 0
                                      },
                                      "capacity": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true
                                      },
                                      "reservationStatus": {
                                        "type": "string",
                                        "enum": [
                                          "FREE",
                                          "HELD",
                                          "CONVERTED",
                                          "RELEASED"
                                        ]
                                      }
                                    },
                                    "required": [
                                      "slotId",
                                      "sessionIndex",
                                      "supplierId",
                                      "serviceId",
                                      "offeringId",
                                      "bookingStartUtc",
                                      "bookingEndUtc",
                                      "bookingTz",
                                      "locationType",
                                      "locationId",
                                      "latitude",
                                      "longitude",
                                      "address",
                                      "travelTimeMins",
                                      "capacity",
                                      "reservationStatus"
                                    ]
                                  }
                                },
                                "position": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                                  "example": 0
                                },
                                "cadenceRrule": {
                                  "type": "string",
                                  "nullable": true,
                                  "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                                  "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                                },
                                "matchesRequestedCadence": {
                                  "type": "boolean",
                                  "description": "True when cadenceRrule is the rrule you asked for.",
                                  "example": false
                                },
                                "cadenceRelaxation": {
                                  "type": "string",
                                  "enum": [
                                    "EXACT",
                                    "INTERVAL_TIGHTENED",
                                    "DAYS_ADDED",
                                    "DAYS_SUBSTITUTED",
                                    "ALL_WORKING_DAYS",
                                    "DIRECT_FILL"
                                  ],
                                  "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                },
                                "cadenceDistance": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                                  "example": 2
                                },
                                "cadenceSummary": {
                                  "type": "object",
                                  "properties": {
                                    "requested": {
                                      "type": "integer",
                                      "nullable": true,
                                      "minimum": 0,
                                      "exclusiveMinimum": true,
                                      "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                                      "example": 4
                                    },
                                    "peak": {
                                      "type": "integer",
                                      "minimum": 0,
                                      "exclusiveMinimum": true,
                                      "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                                      "example": 4
                                    },
                                    "average": {
                                      "type": "number",
                                      "minimum": 0,
                                      "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                                      "example": 2.25
                                    },
                                    "byWeek": {
                                      "type": "array",
                                      "items": {
                                        "type": "object",
                                        "properties": {
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                            "example": "2026-09-14"
                                          },
                                          "sessions": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                            "example": 0
                                          }
                                        },
                                        "required": ["weekStart", "sessions"]
                                      },
                                      "minItems": 1,
                                      "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                                    }
                                  },
                                  "required": [
                                    "requested",
                                    "peak",
                                    "average",
                                    "byWeek"
                                  ],
                                  "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                                },
                                "matchNotes": {
                                  "type": "array",
                                  "items": {
                                    "oneOf": [
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": [
                                              "SUPPLIER_UNAVAILABLE_WEEK"
                                            ]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "openingsInPool": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                "example": 2
                                              },
                                              "supplierWorkdays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "openingsInPool",
                                              "supplierWorkdays"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_EXCLUDED_BY_FILTERS"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "filter": {
                                                "type": "string",
                                                "enum": [
                                                  "daysOfWeek",
                                                  "excludeDates"
                                                ]
                                              },
                                              "supplierWorkdays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "requestedDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "excludedDates": {
                                                "type": "array",
                                                "items": {
                                                  "type": "string"
                                                }
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "filter",
                                              "supplierWorkdays"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_SUPPLY_INSUFFICIENT"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "openingsInPool": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                "example": 2
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "openingsInPool"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_CAPPED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "cap": {
                                                "type": "string",
                                                "enum": [
                                                  "maxSessionsPerWeek",
                                                  "minGapDays"
                                                ]
                                              },
                                              "capValue": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "cap",
                                              "capValue"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["SESSIONS_EXHAUSTED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsRequested": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              },
                                              "sessionsPlacedBefore": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "required": [
                                              "sessionsRequested",
                                              "sessionsPlacedBefore"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["CADENCE_RELAXED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["cadence"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "cadenceRelaxation": {
                                                "type": "string",
                                                "enum": [
                                                  "EXACT",
                                                  "INTERVAL_TIGHTENED",
                                                  "DAYS_ADDED",
                                                  "DAYS_SUBSTITUTED",
                                                  "ALL_WORKING_DAYS",
                                                  "DIRECT_FILL"
                                                ],
                                                "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                              },
                                              "requestedDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "actualDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              }
                                            },
                                            "required": ["cadenceRelaxation"]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": [
                                              "SESSIONS_OUTSIDE_PREFERRED_TIMES"
                                            ]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["timeOfDay"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionIndexes": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                }
                                              },
                                              "localTimes": {
                                                "type": "array",
                                                "items": {
                                                  "type": "string"
                                                }
                                              }
                                            },
                                            "required": [
                                              "sessionIndexes",
                                              "localTimes"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["FIRST_SESSION_LATE"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["startDate"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "firstSessionDate": {
                                                "type": "string"
                                              },
                                              "windowStartDate": {
                                                "type": "string"
                                              },
                                              "dayOffset": {
                                                "type": "integer",
                                                "minimum": 0
                                              },
                                              "earlierSupplyExisted": {
                                                "type": "boolean",
                                                "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                              }
                                            },
                                            "required": [
                                              "firstSessionDate",
                                              "windowStartDate",
                                              "dayOffset",
                                              "earlierSupplyExisted"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["PACKAGE_UNDERFILLED"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsRequested": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              },
                                              "sessionsFilled": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "required": [
                                              "sessionsRequested",
                                              "sessionsFilled"
                                            ]
                                          }
                                        },
                                        "required": ["code", "evidence"],
                                        "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                                      }
                                    ]
                                  },
                                  "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                                },
                                "advice": {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["LATER_START_IMPROVES_CADENCE"]
                                    },
                                    "earliestSustainedWeek": {
                                      "type": "string",
                                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                      "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                                      "example": "2026-09-14"
                                    }
                                  },
                                  "required": ["code", "earliestSustainedWeek"],
                                  "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                                },
                                "matchScore": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 1,
                                  "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                                  "example": 1
                                },
                                "matchComponents": {
                                  "type": "object",
                                  "properties": {
                                    "startDate": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                                    },
                                    "timeOfDay": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                                    },
                                    "daysOfWeek": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                                    },
                                    "sessionsPerWeek": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                                    },
                                    "cadence": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                                    }
                                  },
                                  "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                                }
                              },
                              "required": [
                                "slateId",
                                "supplierId",
                                "completeness",
                                "sessionsRequested",
                                "sessionsFilled",
                                "startTimeConsistencyPercent",
                                "totalTravelTimeMins",
                                "slots",
                                "matchNotes",
                                "matchScore"
                              ],
                              "description": "The best COMPLETE single-supplier slate; book this by slateId."
                            },
                            "alternates": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "slateId": {
                                    "type": "string",
                                    "description": "Pass this to POST .../package-bookings to book the whole plan.",
                                    "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                                  },
                                  "supplierId": {
                                    "type": "string"
                                  },
                                  "completeness": {
                                    "type": "string",
                                    "enum": ["COMPLETE", "PARTIAL"]
                                  },
                                  "sessionsRequested": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "exclusiveMinimum": true,
                                    "description": "How many sessions were requested (the package's creditCount)."
                                  },
                                  "sessionsFilled": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "How many of the requested sessions the plan could fill."
                                  },
                                  "startTimeConsistencyPercent": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 100
                                  },
                                  "totalTravelTimeMins": {
                                    "type": "number",
                                    "minimum": 0
                                  },
                                  "slots": {
                                    "type": "array",
                                    "items": {
                                      "type": "object",
                                      "properties": {
                                        "slotId": {
                                          "type": "string",
                                          "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                                        },
                                        "sessionIndex": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true,
                                          "description": "1-based index of this session within the slate."
                                        },
                                        "supplierId": {
                                          "type": "string"
                                        },
                                        "serviceId": {
                                          "type": "string"
                                        },
                                        "offeringId": {
                                          "type": "string"
                                        },
                                        "bookingStartUtc": {
                                          "type": "string",
                                          "format": "date-time"
                                        },
                                        "bookingEndUtc": {
                                          "type": "string",
                                          "format": "date-time"
                                        },
                                        "bookingTz": {
                                          "type": "string"
                                        },
                                        "locationType": {
                                          "type": "string",
                                          "enum": [
                                            "PHYSICAL",
                                            "VIRTUAL",
                                            "TRAVEL_ZONE"
                                          ]
                                        },
                                        "locationId": {
                                          "type": "string",
                                          "nullable": true
                                        },
                                        "latitude": {
                                          "type": "number",
                                          "nullable": true
                                        },
                                        "longitude": {
                                          "type": "number",
                                          "nullable": true
                                        },
                                        "address": {
                                          "$ref": "#/components/schemas/Address"
                                        },
                                        "travelTimeMins": {
                                          "type": "number",
                                          "nullable": true,
                                          "minimum": 0
                                        },
                                        "capacity": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true
                                        },
                                        "reservationStatus": {
                                          "type": "string",
                                          "enum": [
                                            "FREE",
                                            "HELD",
                                            "CONVERTED",
                                            "RELEASED"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "slotId",
                                        "sessionIndex",
                                        "supplierId",
                                        "serviceId",
                                        "offeringId",
                                        "bookingStartUtc",
                                        "bookingEndUtc",
                                        "bookingTz",
                                        "locationType",
                                        "locationId",
                                        "latitude",
                                        "longitude",
                                        "address",
                                        "travelTimeMins",
                                        "capacity",
                                        "reservationStatus"
                                      ]
                                    }
                                  },
                                  "position": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                                    "example": 0
                                  },
                                  "cadenceRrule": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                                    "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                                  },
                                  "matchesRequestedCadence": {
                                    "type": "boolean",
                                    "description": "True when cadenceRrule is the rrule you asked for.",
                                    "example": false
                                  },
                                  "cadenceRelaxation": {
                                    "type": "string",
                                    "enum": [
                                      "EXACT",
                                      "INTERVAL_TIGHTENED",
                                      "DAYS_ADDED",
                                      "DAYS_SUBSTITUTED",
                                      "ALL_WORKING_DAYS",
                                      "DIRECT_FILL"
                                    ],
                                    "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                  },
                                  "cadenceDistance": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                                    "example": 2
                                  },
                                  "cadenceSummary": {
                                    "type": "object",
                                    "properties": {
                                      "requested": {
                                        "type": "integer",
                                        "nullable": true,
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                                        "example": 4
                                      },
                                      "peak": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                                        "example": 4
                                      },
                                      "average": {
                                        "type": "number",
                                        "minimum": 0,
                                        "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                                        "example": 2.25
                                      },
                                      "byWeek": {
                                        "type": "array",
                                        "items": {
                                          "type": "object",
                                          "properties": {
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                              "example": "2026-09-14"
                                            },
                                            "sessions": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                              "example": 0
                                            }
                                          },
                                          "required": ["weekStart", "sessions"]
                                        },
                                        "minItems": 1,
                                        "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                                      }
                                    },
                                    "required": [
                                      "requested",
                                      "peak",
                                      "average",
                                      "byWeek"
                                    ],
                                    "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                                  },
                                  "matchNotes": {
                                    "type": "array",
                                    "items": {
                                      "oneOf": [
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "SUPPLIER_UNAVAILABLE_WEEK"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "openingsInPool": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                  "example": 2
                                                },
                                                "supplierWorkdays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "openingsInPool",
                                                "supplierWorkdays"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "WEEK_EXCLUDED_BY_FILTERS"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "filter": {
                                                  "type": "string",
                                                  "enum": [
                                                    "daysOfWeek",
                                                    "excludeDates"
                                                  ]
                                                },
                                                "supplierWorkdays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                },
                                                "requestedDays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                },
                                                "excludedDates": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "string"
                                                  }
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "filter",
                                                "supplierWorkdays"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "WEEK_SUPPLY_INSUFFICIENT"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "openingsInPool": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                  "example": 2
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "openingsInPool"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["WEEK_CAPPED"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "cap": {
                                                  "type": "string",
                                                  "enum": [
                                                    "maxSessionsPerWeek",
                                                    "minGapDays"
                                                  ]
                                                },
                                                "capValue": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "cap",
                                                "capValue"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["SESSIONS_EXHAUSTED"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsRequested": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                },
                                                "sessionsPlacedBefore": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                }
                                              },
                                              "required": [
                                                "sessionsRequested",
                                                "sessionsPlacedBefore"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["CADENCE_RELAXED"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["cadence"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "cadenceRelaxation": {
                                                  "type": "string",
                                                  "enum": [
                                                    "EXACT",
                                                    "INTERVAL_TIGHTENED",
                                                    "DAYS_ADDED",
                                                    "DAYS_SUBSTITUTED",
                                                    "ALL_WORKING_DAYS",
                                                    "DIRECT_FILL"
                                                  ],
                                                  "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                                },
                                                "requestedDays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                },
                                                "actualDays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                }
                                              },
                                              "required": ["cadenceRelaxation"]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "evidence"
                                          ],
                                          "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "SESSIONS_OUTSIDE_PREFERRED_TIMES"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["timeOfDay"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionIndexes": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "exclusiveMinimum": true
                                                  }
                                                },
                                                "localTimes": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "string"
                                                  }
                                                }
                                              },
                                              "required": [
                                                "sessionIndexes",
                                                "localTimes"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "evidence"
                                          ],
                                          "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["FIRST_SESSION_LATE"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["startDate"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "firstSessionDate": {
                                                  "type": "string"
                                                },
                                                "windowStartDate": {
                                                  "type": "string"
                                                },
                                                "dayOffset": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "earlierSupplyExisted": {
                                                  "type": "boolean",
                                                  "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                                }
                                              },
                                              "required": [
                                                "firstSessionDate",
                                                "windowStartDate",
                                                "dayOffset",
                                                "earlierSupplyExisted"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "evidence"
                                          ],
                                          "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["PACKAGE_UNDERFILLED"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsRequested": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                },
                                                "sessionsFilled": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                }
                                              },
                                              "required": [
                                                "sessionsRequested",
                                                "sessionsFilled"
                                              ]
                                            }
                                          },
                                          "required": ["code", "evidence"],
                                          "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                                        }
                                      ]
                                    },
                                    "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                                  },
                                  "advice": {
                                    "type": "object",
                                    "properties": {
                                      "code": {
                                        "type": "string",
                                        "enum": ["LATER_START_IMPROVES_CADENCE"]
                                      },
                                      "earliestSustainedWeek": {
                                        "type": "string",
                                        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                        "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                                        "example": "2026-09-14"
                                      }
                                    },
                                    "required": [
                                      "code",
                                      "earliestSustainedWeek"
                                    ],
                                    "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                                  },
                                  "matchScore": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1,
                                    "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                                    "example": 1
                                  },
                                  "matchComponents": {
                                    "type": "object",
                                    "properties": {
                                      "startDate": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                                      },
                                      "timeOfDay": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                                      },
                                      "daysOfWeek": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                                      },
                                      "sessionsPerWeek": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                                      },
                                      "cadence": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                                      }
                                    },
                                    "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                                  }
                                },
                                "required": [
                                  "slateId",
                                  "supplierId",
                                  "completeness",
                                  "sessionsRequested",
                                  "sessionsFilled",
                                  "startTimeConsistencyPercent",
                                  "totalTravelTimeMins",
                                  "slots",
                                  "matchNotes",
                                  "matchScore"
                                ]
                              },
                              "description": "Other bookable options beyond primarySlate, ranked best first and capped at the maxAlternates you sent. Under the default supplierPolicy of SAME_SUPPLIER these are other schedules from the SAME supplier as primarySlate; under PREFERRED or ANY they are other suppliers’ best schedules, one per supplier. Two schedules from one supplier count as different options only when they run on different weekdays, or start at least 30 minutes apart — so a supplier offering 09:00 and 09:20 gives you one option, not two. Each entry’s slateId is bookable exactly like primarySlate’s."
                            },
                            "partial": {
                              "type": "object",
                              "nullable": true,
                              "properties": {
                                "slateId": {
                                  "type": "string",
                                  "description": "Pass this to POST .../package-bookings to book the whole plan.",
                                  "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                                },
                                "supplierId": {
                                  "type": "string"
                                },
                                "completeness": {
                                  "type": "string",
                                  "enum": ["COMPLETE", "PARTIAL"]
                                },
                                "sessionsRequested": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true,
                                  "description": "How many sessions were requested (the package's creditCount)."
                                },
                                "sessionsFilled": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "How many of the requested sessions the plan could fill."
                                },
                                "startTimeConsistencyPercent": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 100
                                },
                                "totalTravelTimeMins": {
                                  "type": "number",
                                  "minimum": 0
                                },
                                "slots": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "slotId": {
                                        "type": "string",
                                        "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                                      },
                                      "sessionIndex": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "1-based index of this session within the slate."
                                      },
                                      "supplierId": {
                                        "type": "string"
                                      },
                                      "serviceId": {
                                        "type": "string"
                                      },
                                      "offeringId": {
                                        "type": "string"
                                      },
                                      "bookingStartUtc": {
                                        "type": "string",
                                        "format": "date-time"
                                      },
                                      "bookingEndUtc": {
                                        "type": "string",
                                        "format": "date-time"
                                      },
                                      "bookingTz": {
                                        "type": "string"
                                      },
                                      "locationType": {
                                        "type": "string",
                                        "enum": [
                                          "PHYSICAL",
                                          "VIRTUAL",
                                          "TRAVEL_ZONE"
                                        ]
                                      },
                                      "locationId": {
                                        "type": "string",
                                        "nullable": true
                                      },
                                      "latitude": {
                                        "type": "number",
                                        "nullable": true
                                      },
                                      "longitude": {
                                        "type": "number",
                                        "nullable": true
                                      },
                                      "address": {
                                        "$ref": "#/components/schemas/Address"
                                      },
                                      "travelTimeMins": {
                                        "type": "number",
                                        "nullable": true,
                                        "minimum": 0
                                      },
                                      "capacity": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true
                                      },
                                      "reservationStatus": {
                                        "type": "string",
                                        "enum": [
                                          "FREE",
                                          "HELD",
                                          "CONVERTED",
                                          "RELEASED"
                                        ]
                                      }
                                    },
                                    "required": [
                                      "slotId",
                                      "sessionIndex",
                                      "supplierId",
                                      "serviceId",
                                      "offeringId",
                                      "bookingStartUtc",
                                      "bookingEndUtc",
                                      "bookingTz",
                                      "locationType",
                                      "locationId",
                                      "latitude",
                                      "longitude",
                                      "address",
                                      "travelTimeMins",
                                      "capacity",
                                      "reservationStatus"
                                    ]
                                  }
                                },
                                "position": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                                  "example": 0
                                },
                                "cadenceRrule": {
                                  "type": "string",
                                  "nullable": true,
                                  "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                                  "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                                },
                                "matchesRequestedCadence": {
                                  "type": "boolean",
                                  "description": "True when cadenceRrule is the rrule you asked for.",
                                  "example": false
                                },
                                "cadenceRelaxation": {
                                  "type": "string",
                                  "enum": [
                                    "EXACT",
                                    "INTERVAL_TIGHTENED",
                                    "DAYS_ADDED",
                                    "DAYS_SUBSTITUTED",
                                    "ALL_WORKING_DAYS",
                                    "DIRECT_FILL"
                                  ],
                                  "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                },
                                "cadenceDistance": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                                  "example": 2
                                },
                                "cadenceSummary": {
                                  "type": "object",
                                  "properties": {
                                    "requested": {
                                      "type": "integer",
                                      "nullable": true,
                                      "minimum": 0,
                                      "exclusiveMinimum": true,
                                      "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                                      "example": 4
                                    },
                                    "peak": {
                                      "type": "integer",
                                      "minimum": 0,
                                      "exclusiveMinimum": true,
                                      "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                                      "example": 4
                                    },
                                    "average": {
                                      "type": "number",
                                      "minimum": 0,
                                      "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                                      "example": 2.25
                                    },
                                    "byWeek": {
                                      "type": "array",
                                      "items": {
                                        "type": "object",
                                        "properties": {
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                            "example": "2026-09-14"
                                          },
                                          "sessions": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                            "example": 0
                                          }
                                        },
                                        "required": ["weekStart", "sessions"]
                                      },
                                      "minItems": 1,
                                      "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                                    }
                                  },
                                  "required": [
                                    "requested",
                                    "peak",
                                    "average",
                                    "byWeek"
                                  ],
                                  "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                                },
                                "matchNotes": {
                                  "type": "array",
                                  "items": {
                                    "oneOf": [
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": [
                                              "SUPPLIER_UNAVAILABLE_WEEK"
                                            ]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "openingsInPool": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                "example": 2
                                              },
                                              "supplierWorkdays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "openingsInPool",
                                              "supplierWorkdays"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_EXCLUDED_BY_FILTERS"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "filter": {
                                                "type": "string",
                                                "enum": [
                                                  "daysOfWeek",
                                                  "excludeDates"
                                                ]
                                              },
                                              "supplierWorkdays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "requestedDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "excludedDates": {
                                                "type": "array",
                                                "items": {
                                                  "type": "string"
                                                }
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "filter",
                                              "supplierWorkdays"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_SUPPLY_INSUFFICIENT"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "openingsInPool": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                "example": 2
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "openingsInPool"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_CAPPED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "cap": {
                                                "type": "string",
                                                "enum": [
                                                  "maxSessionsPerWeek",
                                                  "minGapDays"
                                                ]
                                              },
                                              "capValue": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "cap",
                                              "capValue"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["SESSIONS_EXHAUSTED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsRequested": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              },
                                              "sessionsPlacedBefore": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "required": [
                                              "sessionsRequested",
                                              "sessionsPlacedBefore"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["CADENCE_RELAXED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["cadence"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "cadenceRelaxation": {
                                                "type": "string",
                                                "enum": [
                                                  "EXACT",
                                                  "INTERVAL_TIGHTENED",
                                                  "DAYS_ADDED",
                                                  "DAYS_SUBSTITUTED",
                                                  "ALL_WORKING_DAYS",
                                                  "DIRECT_FILL"
                                                ],
                                                "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                              },
                                              "requestedDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "actualDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              }
                                            },
                                            "required": ["cadenceRelaxation"]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": [
                                              "SESSIONS_OUTSIDE_PREFERRED_TIMES"
                                            ]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["timeOfDay"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionIndexes": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                }
                                              },
                                              "localTimes": {
                                                "type": "array",
                                                "items": {
                                                  "type": "string"
                                                }
                                              }
                                            },
                                            "required": [
                                              "sessionIndexes",
                                              "localTimes"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["FIRST_SESSION_LATE"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["startDate"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "firstSessionDate": {
                                                "type": "string"
                                              },
                                              "windowStartDate": {
                                                "type": "string"
                                              },
                                              "dayOffset": {
                                                "type": "integer",
                                                "minimum": 0
                                              },
                                              "earlierSupplyExisted": {
                                                "type": "boolean",
                                                "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                              }
                                            },
                                            "required": [
                                              "firstSessionDate",
                                              "windowStartDate",
                                              "dayOffset",
                                              "earlierSupplyExisted"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["PACKAGE_UNDERFILLED"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsRequested": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              },
                                              "sessionsFilled": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "required": [
                                              "sessionsRequested",
                                              "sessionsFilled"
                                            ]
                                          }
                                        },
                                        "required": ["code", "evidence"],
                                        "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                                      }
                                    ]
                                  },
                                  "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                                },
                                "advice": {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["LATER_START_IMPROVES_CADENCE"]
                                    },
                                    "earliestSustainedWeek": {
                                      "type": "string",
                                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                      "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                                      "example": "2026-09-14"
                                    }
                                  },
                                  "required": ["code", "earliestSustainedWeek"],
                                  "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                                },
                                "matchScore": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 1,
                                  "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                                  "example": 1
                                },
                                "matchComponents": {
                                  "type": "object",
                                  "properties": {
                                    "startDate": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                                    },
                                    "timeOfDay": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                                    },
                                    "daysOfWeek": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                                    },
                                    "sessionsPerWeek": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                                    },
                                    "cadence": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                                    }
                                  },
                                  "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                                }
                              },
                              "required": [
                                "slateId",
                                "supplierId",
                                "completeness",
                                "sessionsRequested",
                                "sessionsFilled",
                                "startTimeConsistencyPercent",
                                "totalTravelTimeMins",
                                "slots",
                                "matchNotes",
                                "matchScore"
                              ]
                            },
                            "cadenceAlternatives": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "slateId": {
                                    "type": "string",
                                    "description": "Pass this to POST .../package-bookings to book the whole plan.",
                                    "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                                  },
                                  "supplierId": {
                                    "type": "string"
                                  },
                                  "completeness": {
                                    "type": "string",
                                    "enum": ["COMPLETE", "PARTIAL"]
                                  },
                                  "sessionsRequested": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "exclusiveMinimum": true,
                                    "description": "How many sessions were requested (the package's creditCount)."
                                  },
                                  "sessionsFilled": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "How many of the requested sessions the plan could fill."
                                  },
                                  "startTimeConsistencyPercent": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 100
                                  },
                                  "totalTravelTimeMins": {
                                    "type": "number",
                                    "minimum": 0
                                  },
                                  "slots": {
                                    "type": "array",
                                    "items": {
                                      "type": "object",
                                      "properties": {
                                        "slotId": {
                                          "type": "string",
                                          "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                                        },
                                        "sessionIndex": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true,
                                          "description": "1-based index of this session within the slate."
                                        },
                                        "supplierId": {
                                          "type": "string"
                                        },
                                        "serviceId": {
                                          "type": "string"
                                        },
                                        "offeringId": {
                                          "type": "string"
                                        },
                                        "bookingStartUtc": {
                                          "type": "string",
                                          "format": "date-time"
                                        },
                                        "bookingEndUtc": {
                                          "type": "string",
                                          "format": "date-time"
                                        },
                                        "bookingTz": {
                                          "type": "string"
                                        },
                                        "locationType": {
                                          "type": "string",
                                          "enum": [
                                            "PHYSICAL",
                                            "VIRTUAL",
                                            "TRAVEL_ZONE"
                                          ]
                                        },
                                        "locationId": {
                                          "type": "string",
                                          "nullable": true
                                        },
                                        "latitude": {
                                          "type": "number",
                                          "nullable": true
                                        },
                                        "longitude": {
                                          "type": "number",
                                          "nullable": true
                                        },
                                        "address": {
                                          "$ref": "#/components/schemas/Address"
                                        },
                                        "travelTimeMins": {
                                          "type": "number",
                                          "nullable": true,
                                          "minimum": 0
                                        },
                                        "capacity": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true
                                        },
                                        "reservationStatus": {
                                          "type": "string",
                                          "enum": [
                                            "FREE",
                                            "HELD",
                                            "CONVERTED",
                                            "RELEASED"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "slotId",
                                        "sessionIndex",
                                        "supplierId",
                                        "serviceId",
                                        "offeringId",
                                        "bookingStartUtc",
                                        "bookingEndUtc",
                                        "bookingTz",
                                        "locationType",
                                        "locationId",
                                        "latitude",
                                        "longitude",
                                        "address",
                                        "travelTimeMins",
                                        "capacity",
                                        "reservationStatus"
                                      ]
                                    }
                                  },
                                  "position": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                                    "example": 0
                                  },
                                  "cadenceRrule": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                                    "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                                  },
                                  "matchesRequestedCadence": {
                                    "type": "boolean",
                                    "description": "True when cadenceRrule is the rrule you asked for.",
                                    "example": false
                                  },
                                  "cadenceRelaxation": {
                                    "type": "string",
                                    "enum": [
                                      "EXACT",
                                      "INTERVAL_TIGHTENED",
                                      "DAYS_ADDED",
                                      "DAYS_SUBSTITUTED",
                                      "ALL_WORKING_DAYS",
                                      "DIRECT_FILL"
                                    ],
                                    "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                  },
                                  "cadenceDistance": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                                    "example": 2
                                  },
                                  "cadenceSummary": {
                                    "type": "object",
                                    "properties": {
                                      "requested": {
                                        "type": "integer",
                                        "nullable": true,
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                                        "example": 4
                                      },
                                      "peak": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                                        "example": 4
                                      },
                                      "average": {
                                        "type": "number",
                                        "minimum": 0,
                                        "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                                        "example": 2.25
                                      },
                                      "byWeek": {
                                        "type": "array",
                                        "items": {
                                          "type": "object",
                                          "properties": {
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                              "example": "2026-09-14"
                                            },
                                            "sessions": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                              "example": 0
                                            }
                                          },
                                          "required": ["weekStart", "sessions"]
                                        },
                                        "minItems": 1,
                                        "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                                      }
                                    },
                                    "required": [
                                      "requested",
                                      "peak",
                                      "average",
                                      "byWeek"
                                    ],
                                    "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                                  },
                                  "matchNotes": {
                                    "type": "array",
                                    "items": {
                                      "oneOf": [
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "SUPPLIER_UNAVAILABLE_WEEK"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "openingsInPool": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                  "example": 2
                                                },
                                                "supplierWorkdays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "openingsInPool",
                                                "supplierWorkdays"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "WEEK_EXCLUDED_BY_FILTERS"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "filter": {
                                                  "type": "string",
                                                  "enum": [
                                                    "daysOfWeek",
                                                    "excludeDates"
                                                  ]
                                                },
                                                "supplierWorkdays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                },
                                                "requestedDays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                },
                                                "excludedDates": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "string"
                                                  }
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "filter",
                                                "supplierWorkdays"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "WEEK_SUPPLY_INSUFFICIENT"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "openingsInPool": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                  "example": 2
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "openingsInPool"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["WEEK_CAPPED"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "cap": {
                                                  "type": "string",
                                                  "enum": [
                                                    "maxSessionsPerWeek",
                                                    "minGapDays"
                                                  ]
                                                },
                                                "capValue": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "cap",
                                                "capValue"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["SESSIONS_EXHAUSTED"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsRequested": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                },
                                                "sessionsPlacedBefore": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                }
                                              },
                                              "required": [
                                                "sessionsRequested",
                                                "sessionsPlacedBefore"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["CADENCE_RELAXED"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["cadence"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "cadenceRelaxation": {
                                                  "type": "string",
                                                  "enum": [
                                                    "EXACT",
                                                    "INTERVAL_TIGHTENED",
                                                    "DAYS_ADDED",
                                                    "DAYS_SUBSTITUTED",
                                                    "ALL_WORKING_DAYS",
                                                    "DIRECT_FILL"
                                                  ],
                                                  "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                                },
                                                "requestedDays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                },
                                                "actualDays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                }
                                              },
                                              "required": ["cadenceRelaxation"]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "evidence"
                                          ],
                                          "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "SESSIONS_OUTSIDE_PREFERRED_TIMES"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["timeOfDay"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionIndexes": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "exclusiveMinimum": true
                                                  }
                                                },
                                                "localTimes": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "string"
                                                  }
                                                }
                                              },
                                              "required": [
                                                "sessionIndexes",
                                                "localTimes"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "evidence"
                                          ],
                                          "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["FIRST_SESSION_LATE"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["startDate"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "firstSessionDate": {
                                                  "type": "string"
                                                },
                                                "windowStartDate": {
                                                  "type": "string"
                                                },
                                                "dayOffset": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "earlierSupplyExisted": {
                                                  "type": "boolean",
                                                  "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                                }
                                              },
                                              "required": [
                                                "firstSessionDate",
                                                "windowStartDate",
                                                "dayOffset",
                                                "earlierSupplyExisted"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "evidence"
                                          ],
                                          "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["PACKAGE_UNDERFILLED"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsRequested": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                },
                                                "sessionsFilled": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                }
                                              },
                                              "required": [
                                                "sessionsRequested",
                                                "sessionsFilled"
                                              ]
                                            }
                                          },
                                          "required": ["code", "evidence"],
                                          "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                                        }
                                      ]
                                    },
                                    "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                                  },
                                  "advice": {
                                    "type": "object",
                                    "properties": {
                                      "code": {
                                        "type": "string",
                                        "enum": ["LATER_START_IMPROVES_CADENCE"]
                                      },
                                      "earliestSustainedWeek": {
                                        "type": "string",
                                        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                        "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                                        "example": "2026-09-14"
                                      }
                                    },
                                    "required": [
                                      "code",
                                      "earliestSustainedWeek"
                                    ],
                                    "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                                  },
                                  "matchScore": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1,
                                    "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                                    "example": 1
                                  },
                                  "matchComponents": {
                                    "type": "object",
                                    "properties": {
                                      "startDate": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                                      },
                                      "timeOfDay": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                                      },
                                      "daysOfWeek": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                                      },
                                      "sessionsPerWeek": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                                      },
                                      "cadence": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                                      }
                                    },
                                    "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                                  }
                                },
                                "required": [
                                  "slateId",
                                  "supplierId",
                                  "completeness",
                                  "sessionsRequested",
                                  "sessionsFilled",
                                  "startTimeConsistencyPercent",
                                  "totalTravelTimeMins",
                                  "slots",
                                  "matchNotes",
                                  "matchScore"
                                ]
                              },
                              "default": [],
                              "description": "Complete N-session slates that fit the supplier’s real availability but do NOT follow the rrule you asked for — e.g. you requested weekly Fridays, no supplier has eight free Fridays, so this carries a Mon+Fri plan instead. Sorted by cadenceDistance, closest first, when the request carries no sessionsPerWeek target; when it does, ranked by closeness to that target first and cadenceDistance only as the tiebreaker. Always empty unless the request set cadenceFlexibility or guaranteeSlate. Each entry’s slateId is bookable exactly like primarySlate’s."
                            },
                            "requestedCadence": {
                              "type": "string",
                              "nullable": true,
                              "description": "The rrule this request asked for, echoed back so you can diff it against each slate’s cadenceRrule.",
                              "example": "FREQ=WEEKLY;BYDAY=FR;COUNT=8"
                            }
                          },
                          "required": [
                            "status",
                            "reason",
                            "suggestionRequestId",
                            "resolvableUntil",
                            "primarySlate",
                            "alternates",
                            "partial"
                          ]
                        }
                      },
                      "required": ["code", "message", "statusCode", "requestId"]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": ["SLOT_HELD", "SLOT_BOOKED"],
                          "description": "Which kind of claim is blocking the requested time.",
                          "example": "SLOT_HELD"
                        },
                        "message": {
                          "type": "string",
                          "description": "Human-readable summary of the conflict.",
                          "example": "Supplier time is not available: HOLD resv_01kv8p20m1gnqvxl92xln6awk8 (2026-08-01T10:00:00Z–2026-08-01T11:00:00Z)"
                        },
                        "statusCode": {
                          "type": "number",
                          "enum": [409],
                          "description": "The HTTP status, repeated in the body — every MarketBox error carries it, so you can branch on the body alone.",
                          "example": 409
                        },
                        "requestId": {
                          "type": "string",
                          "description": "The id of this request (also returned as the X-Request-Id header). Quote it in a support ticket.",
                          "example": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
                        },
                        "conflicts": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "claimType": {
                                "type": "string",
                                "enum": ["BOOKING", "HOLD"],
                                "description": "Whether the blocking claim is a HOLD or a confirmed BOOKING."
                              },
                              "supplierId": {
                                "type": "string",
                                "nullable": true,
                                "description": "The supplier whose calendar is blocked, when known."
                              },
                              "startUtc": {
                                "type": "string",
                                "format": "date-time",
                                "description": "Start of the blocking claim, UTC ISO 8601.",
                                "example": "2026-08-01T10:00:00Z"
                              },
                              "endUtc": {
                                "type": "string",
                                "format": "date-time",
                                "description": "End of the blocking claim, UTC ISO 8601.",
                                "example": "2026-08-01T11:00:00Z"
                              },
                              "reservationId": {
                                "type": "string",
                                "nullable": true,
                                "description": "Present when claimType is HOLD — the reservationId to convert or release. Null for a BOOKING conflict.",
                                "example": "resv_01kv8p20m1gnqvxl92xln6awk8"
                              },
                              "bookingId": {
                                "type": "string",
                                "nullable": true,
                                "description": "Present when claimType is BOOKING — the id of the confirmed booking occupying this time. Null for a HOLD conflict.",
                                "example": null
                              },
                              "heldUntil": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time",
                                "description": "HOLD only: when the blocking hold lazily expires. Null for a BOOKING conflict.",
                                "example": "2026-08-01T10:05:00Z"
                              }
                            },
                            "required": ["claimType", "startUtc", "endUtc"]
                          },
                          "description": "Every live claim that overlaps the requested time — usually one, but can be more."
                        },
                        "hint": {
                          "type": "string",
                          "description": "What to do next: for SLOT_HELD, convert or release the named reservationId (POST .../holds/{reservationId}/convert or /release); for SLOT_BOOKED, search availability again.",
                          "example": "This time is held (reservation resv_01kv8p20m1gnqvxl92xln6awk8). Convert the hold via POST /v1/projects/{projectId}/holds/{reservationId}/convert, or release it with POST /v1/projects/{projectId}/holds/{reservationId}/release. Direct booking routes will not consume a hold — if you hold, you convert."
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "statusCode",
                        "requestId",
                        "conflicts",
                        "hint"
                      ]
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/holds": {
      "post": {
        "tags": ["Holds"],
        "summary": "Hold supplier time during checkout — a single session, or a whole package slate",
        "description": "Claims supplier time so nobody else can book it while your client pays. Provide exactly one of: intervals (explicit supplier time — this is the form that works for a SINGLE session, with no package and no slate), slateId (hold every slot of a persisted package slate), or slotIds (cherry-pick slots of a slate). Every interval is claimed in ONE transaction, so a hold is all-or-nothing — you never end up holding 3 sessions of a 5-session package. Expiry is LAZY: nothing runs at heldUntil, the hold simply stops blocking, so convert before then. To HEARTBEAT a checkout page, re-post the same intervals AND the reservationId you were given (with the same heldBy): that EXTENDS the existing hold — heldUntil moves out, the same reservationId comes back, and no second hold is minted. Omitting reservationId always mints a NEW hold. Returns 409 with code SLOT_HELD/SLOT_BOOKED — naming the blocking reservationId or bookingId — when the time is already claimed, or RESERVATION_NOT_FOUND / RESERVATION_NOT_HELD / RESERVATION_FORBIDDEN when the reservationId you asked to extend is unknown, no longer held, or not yours. A slateId/slotIds hold (new or extended) whose slots are past their resolvableUntil is 409 SUGGESTION_EXPIRED, as package-bookings answers it: the times were planned from availability that may have changed, so plan a fresh slate. An unknown slate or slot is 409 SLATE_NOT_FOUND / SLOT_NOT_FOUND.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project the hold belongs to.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project the hold belongs to.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "intervals | slateId | slotIds (+ optional reservationId to extend, heldBy, holdDurationMins)",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "intervals": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "supplierId": {
                          "type": "string",
                          "minLength": 1,
                          "description": "The supplier whose time is being held.",
                          "example": "sup_01kv60qgnef2kt3pvqgwmkbzfr"
                        },
                        "startUtc": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Session start, UTC ISO-8601 with a Z suffix.",
                          "example": "2026-07-15T14:00:00.000Z"
                        },
                        "endUtc": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Session end, UTC ISO-8601. Exclusive — a booking ending at 15:00 does not collide with one starting at 15:00.",
                          "example": "2026-07-15T15:00:00.000Z"
                        },
                        "bookingTz": {
                          "type": "string",
                          "minLength": 1,
                          "description": "IANA timezone the session occurs in. Required: it is carried onto the hold and the booking's local-time fields are derived from it at convert.",
                          "example": "America/Toronto"
                        },
                        "locationType": {
                          "type": "string",
                          "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"],
                          "description": "VIRTUAL, PHYSICAL, or TRAVEL_ZONE — same meaning as on a booking. It decides which of the fields below are required, and it is what tells convert whether locationId names a Location or a supplier travel zone.",
                          "example": "TRAVEL_ZONE"
                        },
                        "locationId": {
                          "type": "string",
                          "nullable": true,
                          "minLength": 1,
                          "description": "For PHYSICAL: the Location id. For TRAVEL_ZONE: the supplierTravelZoneId. Null for VIRTUAL. A hold WITH a location participates in travel-buffer logic exactly as a booking does.",
                          "example": "stz_01kv60qgs4e4nbjhzradnqtj0h"
                        },
                        "latitude": {
                          "type": "number",
                          "nullable": true,
                          "description": "Client latitude. Required for TRAVEL_ZONE; must be omitted for PHYSICAL/VIRTUAL (PHYSICAL coordinates come from the Location).",
                          "example": 43.6532
                        },
                        "longitude": {
                          "type": "number",
                          "nullable": true,
                          "description": "Client longitude. Required for TRAVEL_ZONE; must be omitted for PHYSICAL/VIRTUAL (PHYSICAL coordinates come from the Location).",
                          "example": -79.3832
                        },
                        "address": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "addressOneLine": {
                              "type": "string",
                              "minLength": 1,
                              "description": "The whole address on one line, as a person would write it.",
                              "example": "10 Main St, Toronto, ON M5V 1A1, Canada"
                            },
                            "streetNumber": {
                              "type": "string",
                              "minLength": 1,
                              "description": "The street number.",
                              "example": "10"
                            },
                            "streetName": {
                              "type": "string",
                              "minLength": 1,
                              "description": "The street name.",
                              "example": "Main St"
                            },
                            "city": {
                              "type": "string",
                              "minLength": 1,
                              "description": "The city or town.",
                              "example": "Toronto"
                            },
                            "state": {
                              "type": "string",
                              "minLength": 1,
                              "description": "The state, province or region; an ISO 3166-2 code when one matches.",
                              "example": "ON"
                            },
                            "country": {
                              "type": "string",
                              "minLength": 1,
                              "description": "The country; ISO 3166-1 alpha-2, alpha-3 or the English name.",
                              "example": "CA"
                            },
                            "zipCode": {
                              "type": "string",
                              "minLength": 1,
                              "description": "The postal or ZIP code, in any national format.",
                              "example": "M5V 1A1"
                            },
                            "unitNumber": {
                              "type": "string",
                              "nullable": true,
                              "description": "The unit, suite or apartment, if any.",
                              "example": "4B"
                            }
                          },
                          "required": [
                            "addressOneLine",
                            "streetNumber",
                            "streetName",
                            "city",
                            "state",
                            "country",
                            "zipCode"
                          ],
                          "description": "Structured client address. Required for TRAVEL_ZONE — the supplier travels to it, and the booking cannot be written without it."
                        }
                      },
                      "required": [
                        "supplierId",
                        "startUtc",
                        "endUtc",
                        "bookingTz",
                        "locationType"
                      ]
                    },
                    "minItems": 1,
                    "description": "Explicit supplier time to hold. Use this for a single session — no package or slate required."
                  },
                  "slateId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Hold every slot of a persisted package slate (from POST /availability/package-slate).",
                    "example": "slate_01kv7n10k0fnptwk81wkm59vj7"
                  },
                  "slotIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1
                    },
                    "minItems": 1,
                    "description": "Cherry-pick individual slots of a slate to hold."
                  },
                  "reservationId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "EXTEND an existing hold instead of minting a new one — this is the checkout HEARTBEAT. Supply the reservationId a previous POST /holds handed you: heldUntil is pushed out, the hold keeps its original createdAt, the SAME claim stays on the supplier calendar (no second hold is minted), and the SAME reservationId comes back — so the id you convert later is still the right one. The intervals you send must be the ones that hold already claims, and heldBy must match the hold's owner. A mismatch is 409 RESERVATION_FORBIDDEN; an unknown id is 409 RESERVATION_NOT_FOUND; an already converted/released hold is 409 RESERVATION_NOT_HELD. Omit this field to mint a NEW hold.",
                    "example": "resv_01kv8p20m1gnqvxl92xln6awk8"
                  },
                  "heldBy": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Who owns the hold — typically your checkout session id. Re-holding time you already hold under the same heldBy does not conflict with your own hold; to actually EXTEND that hold (the checkout heartbeat) pass its reservationId as well, otherwise a new hold is minted. Defaults to the API principal.",
                    "example": "checkout_9f2c1b"
                  },
                  "holdDurationMins": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "description": "How long to hold, in minutes. Defaults to the offering override, then the project default, then 5.",
                    "example": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Hold placed — supplier time is now claimed until heldUntil",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reservationId": {
                      "type": "string",
                      "example": "resv_01kv8p20m1gnqvxl92xln6awk8"
                    },
                    "status": {
                      "type": "string",
                      "enum": ["HELD", "CONVERTED", "RELEASED"]
                    },
                    "heldUntil": {
                      "type": "string",
                      "format": "date-time",
                      "description": "When the hold lapses. Expiry is LAZY — nothing runs at this instant; the hold simply stops blocking. Convert before this time.",
                      "example": "2026-07-10T12:05:00.000Z"
                    },
                    "intervals": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "supplierId": {
                            "type": "string"
                          },
                          "startUtc": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "endUtc": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "bookingTz": {
                            "type": "string",
                            "nullable": true,
                            "description": "IANA timezone carried onto the hold; the booking's local times are derived from it at convert.",
                            "example": "America/Toronto"
                          },
                          "locationType": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "PHYSICAL",
                              "VIRTUAL",
                              "TRAVEL_ZONE",
                              null
                            ],
                            "description": "VIRTUAL, PHYSICAL or TRAVEL_ZONE. Null only on a hold placed before location carry-through existed.",
                            "example": "TRAVEL_ZONE"
                          },
                          "locationId": {
                            "type": "string",
                            "nullable": true,
                            "description": "The Location id (PHYSICAL) or supplierTravelZoneId (TRAVEL_ZONE). Null for VIRTUAL.",
                            "example": "stz_01kv60qgs4e4nbjhzradnqtj0h"
                          },
                          "latitude": {
                            "type": "number",
                            "nullable": true,
                            "example": 43.6532
                          },
                          "longitude": {
                            "type": "number",
                            "nullable": true,
                            "example": -79.3832
                          },
                          "address": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "addressOneLine": {
                                "type": "string",
                                "minLength": 1,
                                "description": "The whole address on one line, as a person would write it.",
                                "example": "10 Main St, Toronto, ON M5V 1A1, Canada"
                              },
                              "streetNumber": {
                                "type": "string",
                                "minLength": 1,
                                "description": "The street number.",
                                "example": "10"
                              },
                              "streetName": {
                                "type": "string",
                                "minLength": 1,
                                "description": "The street name.",
                                "example": "Main St"
                              },
                              "city": {
                                "type": "string",
                                "minLength": 1,
                                "description": "The city or town.",
                                "example": "Toronto"
                              },
                              "state": {
                                "type": "string",
                                "minLength": 1,
                                "description": "The state, province or region; an ISO 3166-2 code when one matches.",
                                "example": "ON"
                              },
                              "country": {
                                "type": "string",
                                "minLength": 1,
                                "description": "The country; ISO 3166-1 alpha-2, alpha-3 or the English name.",
                                "example": "CA"
                              },
                              "zipCode": {
                                "type": "string",
                                "minLength": 1,
                                "description": "The postal or ZIP code, in any national format.",
                                "example": "M5V 1A1"
                              },
                              "unitNumber": {
                                "type": "string",
                                "nullable": true,
                                "description": "The unit, suite or apartment, if any.",
                                "example": "4B"
                              }
                            },
                            "required": [
                              "addressOneLine",
                              "streetNumber",
                              "streetName",
                              "city",
                              "state",
                              "country",
                              "zipCode"
                            ],
                            "description": "The structured client address held for a TRAVEL_ZONE session."
                          }
                        },
                        "required": ["supplierId", "startUtc", "endUtc"]
                      }
                    }
                  },
                  "required": [
                    "reservationId",
                    "status",
                    "heldUntil",
                    "intervals"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Supplier not found in this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "Supplier time already held/booked (SLOT_HELD, SLOT_BOOKED, OCCUPANCY_CONTENTION), the slate/slot is stale (SUGGESTION_EXPIRED, SLATE_NOT_FOUND, SLOT_NOT_FOUND, EMPTY_SLATE), or the hold to extend cannot be (RESERVATION_NOT_FOUND, RESERVATION_NOT_HELD, RESERVATION_FORBIDDEN)",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": ["SLOT_HELD", "SLOT_BOOKED"],
                          "description": "Which kind of claim is blocking the requested time.",
                          "example": "SLOT_HELD"
                        },
                        "message": {
                          "type": "string",
                          "description": "Human-readable summary of the conflict.",
                          "example": "Supplier time is not available: HOLD resv_01kv8p20m1gnqvxl92xln6awk8 (2026-08-01T10:00:00Z–2026-08-01T11:00:00Z)"
                        },
                        "statusCode": {
                          "type": "number",
                          "enum": [409],
                          "description": "The HTTP status, repeated in the body — every MarketBox error carries it, so you can branch on the body alone.",
                          "example": 409
                        },
                        "requestId": {
                          "type": "string",
                          "description": "The id of this request (also returned as the X-Request-Id header). Quote it in a support ticket.",
                          "example": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
                        },
                        "conflicts": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "claimType": {
                                "type": "string",
                                "enum": ["BOOKING", "HOLD"],
                                "description": "Whether the blocking claim is a HOLD or a confirmed BOOKING."
                              },
                              "supplierId": {
                                "type": "string",
                                "nullable": true,
                                "description": "The supplier whose calendar is blocked, when known."
                              },
                              "startUtc": {
                                "type": "string",
                                "format": "date-time",
                                "description": "Start of the blocking claim, UTC ISO 8601.",
                                "example": "2026-08-01T10:00:00Z"
                              },
                              "endUtc": {
                                "type": "string",
                                "format": "date-time",
                                "description": "End of the blocking claim, UTC ISO 8601.",
                                "example": "2026-08-01T11:00:00Z"
                              },
                              "reservationId": {
                                "type": "string",
                                "nullable": true,
                                "description": "Present when claimType is HOLD — the reservationId to convert or release. Null for a BOOKING conflict.",
                                "example": "resv_01kv8p20m1gnqvxl92xln6awk8"
                              },
                              "bookingId": {
                                "type": "string",
                                "nullable": true,
                                "description": "Present when claimType is BOOKING — the id of the confirmed booking occupying this time. Null for a HOLD conflict.",
                                "example": null
                              },
                              "heldUntil": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time",
                                "description": "HOLD only: when the blocking hold lazily expires. Null for a BOOKING conflict.",
                                "example": "2026-08-01T10:05:00Z"
                              }
                            },
                            "required": ["claimType", "startUtc", "endUtc"]
                          },
                          "description": "Every live claim that overlaps the requested time — usually one, but can be more."
                        },
                        "hint": {
                          "type": "string",
                          "description": "What to do next: for SLOT_HELD, convert or release the named reservationId (POST .../holds/{reservationId}/convert or /release); for SLOT_BOOKED, search availability again.",
                          "example": "This time is held (reservation resv_01kv8p20m1gnqvxl92xln6awk8). Convert the hold via POST /v1/projects/{projectId}/holds/{reservationId}/convert, or release it with POST /v1/projects/{projectId}/holds/{reservationId}/release. Direct booking routes will not consume a hold — if you hold, you convert."
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "statusCode",
                        "requestId",
                        "conflicts",
                        "hint"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "description": "Why the hold could not be used: HOLD_EXPIRED, RESERVATION_NOT_FOUND, RESERVATION_NOT_HELD, RESERVATION_FORBIDDEN, RESERVATION_MULTI_INTERVAL (a SINGLE_SESSION order item converts exactly one held interval), SLOT_NOT_FOUND, SLATE_NOT_FOUND, EMPTY_SLATE, SUGGESTION_EXPIRED (placing or extending a hold from a slate or slot past its resolvableUntil: plan a fresh slate).",
                          "example": "HOLD_EXPIRED"
                        },
                        "message": {
                          "type": "string",
                          "description": "Human-readable explanation.",
                          "example": "Reservation resv_01kv8 expired at 2026-07-10T12:05:00.000Z"
                        },
                        "statusCode": {
                          "type": "number",
                          "enum": [409],
                          "description": "The HTTP status, repeated in the body — every MarketBox error carries it, so you can branch on the body alone.",
                          "example": 409
                        },
                        "requestId": {
                          "type": "string",
                          "description": "The id of this request (also returned as the X-Request-Id header). Quote it in a support ticket.",
                          "example": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
                        }
                      },
                      "required": ["code", "message", "statusCode", "requestId"]
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/holds/{reservationId}": {
      "get": {
        "tags": ["Holds"],
        "summary": "Read a hold — its status, its heldUntil, and the supplier time it claims",
        "description": "Returns the reservation as it stands. status is HELD (live), CONVERTED (already booked — a repeated convert replays the same bookings), or RELEASED. A hold past its heldUntil may still read as HELD: expiry is lazy, so compare heldUntil against now rather than trusting status alone.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project the hold belongs to.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project the hold belongs to.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The reservationId returned by POST /holds.",
              "example": "resv_01kv8p20m1gnqvxl92xln6awk8"
            },
            "required": true,
            "description": "The reservationId returned by POST /holds.",
            "name": "reservationId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "The hold",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reservationId": {
                      "type": "string",
                      "example": "resv_01kv8p20m1gnqvxl92xln6awk8"
                    },
                    "status": {
                      "type": "string",
                      "enum": ["HELD", "CONVERTED", "RELEASED"]
                    },
                    "heldUntil": {
                      "type": "string",
                      "format": "date-time",
                      "description": "When the hold lapses. Expiry is LAZY — nothing runs at this instant; the hold simply stops blocking. Convert before this time.",
                      "example": "2026-07-10T12:05:00.000Z"
                    },
                    "intervals": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "supplierId": {
                            "type": "string"
                          },
                          "startUtc": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "endUtc": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "bookingTz": {
                            "type": "string",
                            "nullable": true,
                            "description": "IANA timezone carried onto the hold; the booking's local times are derived from it at convert.",
                            "example": "America/Toronto"
                          },
                          "locationType": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "PHYSICAL",
                              "VIRTUAL",
                              "TRAVEL_ZONE",
                              null
                            ],
                            "description": "VIRTUAL, PHYSICAL or TRAVEL_ZONE. Null only on a hold placed before location carry-through existed.",
                            "example": "TRAVEL_ZONE"
                          },
                          "locationId": {
                            "type": "string",
                            "nullable": true,
                            "description": "The Location id (PHYSICAL) or supplierTravelZoneId (TRAVEL_ZONE). Null for VIRTUAL.",
                            "example": "stz_01kv60qgs4e4nbjhzradnqtj0h"
                          },
                          "latitude": {
                            "type": "number",
                            "nullable": true,
                            "example": 43.6532
                          },
                          "longitude": {
                            "type": "number",
                            "nullable": true,
                            "example": -79.3832
                          },
                          "address": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "addressOneLine": {
                                "type": "string",
                                "minLength": 1,
                                "description": "The whole address on one line, as a person would write it.",
                                "example": "10 Main St, Toronto, ON M5V 1A1, Canada"
                              },
                              "streetNumber": {
                                "type": "string",
                                "minLength": 1,
                                "description": "The street number.",
                                "example": "10"
                              },
                              "streetName": {
                                "type": "string",
                                "minLength": 1,
                                "description": "The street name.",
                                "example": "Main St"
                              },
                              "city": {
                                "type": "string",
                                "minLength": 1,
                                "description": "The city or town.",
                                "example": "Toronto"
                              },
                              "state": {
                                "type": "string",
                                "minLength": 1,
                                "description": "The state, province or region; an ISO 3166-2 code when one matches.",
                                "example": "ON"
                              },
                              "country": {
                                "type": "string",
                                "minLength": 1,
                                "description": "The country; ISO 3166-1 alpha-2, alpha-3 or the English name.",
                                "example": "CA"
                              },
                              "zipCode": {
                                "type": "string",
                                "minLength": 1,
                                "description": "The postal or ZIP code, in any national format.",
                                "example": "M5V 1A1"
                              },
                              "unitNumber": {
                                "type": "string",
                                "nullable": true,
                                "description": "The unit, suite or apartment, if any.",
                                "example": "4B"
                              }
                            },
                            "required": [
                              "addressOneLine",
                              "streetNumber",
                              "streetName",
                              "city",
                              "state",
                              "country",
                              "zipCode"
                            ],
                            "description": "The structured client address held for a TRAVEL_ZONE session."
                          }
                        },
                        "required": ["supplierId", "startUtc", "endUtc"]
                      }
                    }
                  },
                  "required": [
                    "reservationId",
                    "status",
                    "heldUntil",
                    "intervals"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "No such reservation in this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/holds/{reservationId}/release": {
      "post": {
        "tags": ["Holds"],
        "summary": "Release a hold (HELD → RELEASED) — idempotent",
        "description": "Frees the supplier time immediately: call this when the client abandons checkout instead of waiting for lazy expiry. Idempotent — an already-released hold returns RELEASED, an already-converted hold returns CONVERTED (it is booked and cannot be released), and an unknown reservationId returns NOT_FOUND. All three are terminal states, not failures. A release that keeps losing the race for the supplier calendar to other writes is retried, then answered 409 OCCUPANCY_CONTENTION: the hold is still HELD (it still expires on its own), so retry the release.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project the hold belongs to.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project the hold belongs to.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The reservationId returned by POST /holds.",
              "example": "resv_01kv8p20m1gnqvxl92xln6awk8"
            },
            "required": true,
            "description": "The reservationId returned by POST /holds.",
            "name": "reservationId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Released (or already released / converted / not found)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reservationId": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": ["RELEASED", "CONVERTED", "NOT_FOUND"],
                      "description": "CONVERTED means the hold was already booked and cannot be released. NOT_FOUND means it never existed or has been garbage-collected. Both are terminal, not errors."
                    }
                  },
                  "required": ["reservationId", "status"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "The supplier calendar stayed under contention through every retry (OCCUPANCY_CONTENTION); the hold is still HELD",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/holds/{reservationId}/convert": {
      "post": {
        "tags": ["Holds"],
        "summary": "Convert a hold into confirmed bookings (the idempotent purchase hook)",
        "description": "Turns the held supplier time into real bookings, drawing credits from the given order item. The order item's skuType decides what is booked: a PACKAGE item books every held interval as package sessions; a SINGLE_SESSION item books the ONE held interval as an ordinary single booking — no package, and no 1-credit \"reservation vehicle\" package needed. (A SINGLE_SESSION item against a hold covering more than one interval returns 409 RESERVATION_MULTI_INTERVAL; any other skuType returns 400.) Call it once your checkout has confirmed payment (poll `GET /orders/{orderId}` for `PAID`, or convert first: convert does not require a paid order). The open API sends no webhooks. It is idempotent on the reservationId (the package booking write uses the deterministic key convert:\u003CreservationId\u003E), so a retried call replays the same bookings rather than double-booking, and a reservation already CONVERTED replays its stored result. The bookings are rebuilt from the RESERVATION and the ORDER ITEM — never by re-resolving a suggestion that may have expired — so the booked service and the credit it draws down cannot disagree. Returns 409 HOLD_EXPIRED if you converted too late (the hold no longer blocks anyone), or SLOT_HELD/SLOT_BOOKED if someone else took the time in the meantime. The order need not be paid, but a CANCELLED order converts nothing (409 ORDER_CANCELLED), not even as a replay: its cascade has released its credits and cancelled what it had booked. This response is NOT wrapped in a { data } envelope, and created[].sessionIndex is 0-based.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project the hold belongs to.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project the hold belongs to.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The reservationId returned by POST /holds.",
              "example": "resv_01kv8p20m1gnqvxl92xln6awk8"
            },
            "required": true,
            "description": "The reservationId returned by POST /holds.",
            "name": "reservationId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "orderId + orderItemId (+ optional heldBy, atomicity)",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "orderId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The order whose item the bookings draw credits from.",
                    "example": "ord_01kv7n10k0fnptwk81wkm59vj7"
                  },
                  "orderItemId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The order item to draw down. For a multi-session hold this must be a PACKAGE item with enough quantityRemaining.",
                    "example": "oi_01kv7n10k0fnptwk81wkm59vj7"
                  },
                  "heldBy": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Required to match if the hold was created with a heldBy."
                  },
                  "atomicity": {
                    "type": "string",
                    "enum": ["all_or_nothing", "best_effort"],
                    "default": "all_or_nothing",
                    "description": "all_or_nothing (default) books every session in one transaction. best_effort requires suggestionConfig.allowPartialPackages."
                  }
                },
                "required": ["orderId", "orderItemId"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Hold converted to confirmed bookings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "orderId": {
                      "type": "string"
                    },
                    "orderItemId": {
                      "type": "string"
                    },
                    "packageOrderItemId": {
                      "type": "string"
                    },
                    "atomicity": {
                      "type": "string",
                      "enum": ["all_or_nothing", "best_effort"]
                    },
                    "created": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "sessionIndex": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "bookingId": {
                            "type": "string"
                          },
                          "allocationId": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "sessionIndex",
                          "bookingId",
                          "allocationId"
                        ]
                      },
                      "description": "Bookings created, each with a 0-based sessionIndex, bookingId and allocationId."
                    },
                    "failed": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "sessionIndex": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "reason": {
                            "type": "string"
                          }
                        },
                        "required": ["sessionIndex", "reason"]
                      },
                      "description": "Per-session failures (best_effort only)."
                    },
                    "quantityRemaining": {
                      "type": "integer",
                      "minimum": 0,
                      "description": "Credits left on the order item after this call."
                    }
                  },
                  "required": [
                    "orderId",
                    "orderItemId",
                    "packageOrderItemId",
                    "atomicity",
                    "created",
                    "failed",
                    "quantityRemaining"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validation error, or a location of the wrong type / another supplier’s, or with invalid fields",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Order / order item / offering / location not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "Hold expired / not yours / already released, the time is now taken (SLOT_HELD / SLOT_BOOKED), the calendar is under contention (OCCUPANCY_CONTENTION), the order is cancelled (code: ORDER_CANCELLED), the package has expired (PACKAGE_EXPIRED), or the order item has fewer sessions left than the hold has intervals (ORDER_ITEM_QUANTITY_UNAVAILABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/ErrorMessage"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": ["SLOT_HELD", "SLOT_BOOKED"],
                          "description": "Which kind of claim is blocking the requested time.",
                          "example": "SLOT_HELD"
                        },
                        "message": {
                          "type": "string",
                          "description": "Human-readable summary of the conflict.",
                          "example": "Supplier time is not available: HOLD resv_01kv8p20m1gnqvxl92xln6awk8 (2026-08-01T10:00:00Z–2026-08-01T11:00:00Z)"
                        },
                        "statusCode": {
                          "type": "number",
                          "enum": [409],
                          "description": "The HTTP status, repeated in the body — every MarketBox error carries it, so you can branch on the body alone.",
                          "example": 409
                        },
                        "requestId": {
                          "type": "string",
                          "description": "The id of this request (also returned as the X-Request-Id header). Quote it in a support ticket.",
                          "example": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
                        },
                        "conflicts": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "claimType": {
                                "type": "string",
                                "enum": ["BOOKING", "HOLD"],
                                "description": "Whether the blocking claim is a HOLD or a confirmed BOOKING."
                              },
                              "supplierId": {
                                "type": "string",
                                "nullable": true,
                                "description": "The supplier whose calendar is blocked, when known."
                              },
                              "startUtc": {
                                "type": "string",
                                "format": "date-time",
                                "description": "Start of the blocking claim, UTC ISO 8601.",
                                "example": "2026-08-01T10:00:00Z"
                              },
                              "endUtc": {
                                "type": "string",
                                "format": "date-time",
                                "description": "End of the blocking claim, UTC ISO 8601.",
                                "example": "2026-08-01T11:00:00Z"
                              },
                              "reservationId": {
                                "type": "string",
                                "nullable": true,
                                "description": "Present when claimType is HOLD — the reservationId to convert or release. Null for a BOOKING conflict.",
                                "example": "resv_01kv8p20m1gnqvxl92xln6awk8"
                              },
                              "bookingId": {
                                "type": "string",
                                "nullable": true,
                                "description": "Present when claimType is BOOKING — the id of the confirmed booking occupying this time. Null for a HOLD conflict.",
                                "example": null
                              },
                              "heldUntil": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time",
                                "description": "HOLD only: when the blocking hold lazily expires. Null for a BOOKING conflict.",
                                "example": "2026-08-01T10:05:00Z"
                              }
                            },
                            "required": ["claimType", "startUtc", "endUtc"]
                          },
                          "description": "Every live claim that overlaps the requested time — usually one, but can be more."
                        },
                        "hint": {
                          "type": "string",
                          "description": "What to do next: for SLOT_HELD, convert or release the named reservationId (POST .../holds/{reservationId}/convert or /release); for SLOT_BOOKED, search availability again.",
                          "example": "This time is held (reservation resv_01kv8p20m1gnqvxl92xln6awk8). Convert the hold via POST /v1/projects/{projectId}/holds/{reservationId}/convert, or release it with POST /v1/projects/{projectId}/holds/{reservationId}/release. Direct booking routes will not consume a hold — if you hold, you convert."
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "statusCode",
                        "requestId",
                        "conflicts",
                        "hint"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "description": "Why the hold could not be used: HOLD_EXPIRED, RESERVATION_NOT_FOUND, RESERVATION_NOT_HELD, RESERVATION_FORBIDDEN, RESERVATION_MULTI_INTERVAL (a SINGLE_SESSION order item converts exactly one held interval), SLOT_NOT_FOUND, SLATE_NOT_FOUND, EMPTY_SLATE, SUGGESTION_EXPIRED (placing or extending a hold from a slate or slot past its resolvableUntil: plan a fresh slate).",
                          "example": "HOLD_EXPIRED"
                        },
                        "message": {
                          "type": "string",
                          "description": "Human-readable explanation.",
                          "example": "Reservation resv_01kv8 expired at 2026-07-10T12:05:00.000Z"
                        },
                        "statusCode": {
                          "type": "number",
                          "enum": [409],
                          "description": "The HTTP status, repeated in the body — every MarketBox error carries it, so you can branch on the body alone.",
                          "example": 409
                        },
                        "requestId": {
                          "type": "string",
                          "description": "The id of this request (also returned as the X-Request-Id header). Quote it in a support ticket.",
                          "example": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
                        }
                      },
                      "required": ["code", "message", "statusCode", "requestId"]
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "The hold has more intervals than an all_or_nothing booking can write at once (PACKAGE_SLATE_TOO_LARGE_FOR_ATOMIC), best_effort is not enabled for this project (BEST_EFFORT_NOT_ENABLED), the held location is a PHYSICAL Location without coordinates (UNPROCESSABLE_ENTITY), or the order item names an offering that is not ACTIVE (NOT_SELLABLE): the hold draws down an order item already bought, so only the offering is checked, and a service retired since stays bookable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/clients/me": {
      "post": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Clients"],
        "summary": "Onboard the authenticated client to a project",
        "description": "Idempotently registers the signed-in end user as a CLIENT of the project: ensures a ProjectUsers membership, creates Stripe's own Customer object on the project's connected account (when Stripe is configured, stored as stripeCustomerId), and writes the ClientProfile. Requires both an API key (`x-api-key`) and a client user JWT (`Authorization: Bearer`). Returns 201 on first onboarding, 200 if the client was already onboarded.\n\nThe body is optional; a call with no body (or `{}`) onboards without touching the name or phone. Send `firstName`, `lastName` and/or `phone` to record what your checkout collected: each provided field ALWAYS overwrites the value already stored, on every path (first onboarding, claiming an existing profile by email, or already onboarded), and is also copied to the client's Stripe customer. A blank or `null` field counts as not provided and never clears a stored value; use PATCH /clients/me to clear the phone.\n\nWithout names, the client is recorded under the names from their sign-in. A Google sign-in supplies real names, but an email/password sign-up has only the email address, so the client would appear under the part of it before the `@`. Names are trimmed and must be at most 80 characters. They are the client's record in this project only; they do not rename the person's MarketBox account. The phone is validated and stored in E.164 form (`+14165550134`). Send it as E.164, or as a national North American (NANP) number such as `(416) 555-0134`; numbers outside North America must start with `+` and the country code, or they are rejected. An invalid number is a 400 and nothing is written.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "firstName": {
                    "type": "string",
                    "nullable": true,
                    "description": "The client's first name as your checkout collected it, at most 80 characters after trimming. Overwrites the stored first name; blank or null means not provided.",
                    "example": "Emma"
                  },
                  "lastName": {
                    "type": "string",
                    "nullable": true,
                    "description": "The client's last name as your checkout collected it, at most 80 characters after trimming. Overwrites the stored last name; blank or null means not provided.",
                    "example": "Bishop"
                  },
                  "phone": {
                    "type": "string",
                    "nullable": true,
                    "description": "Phone number. Accepts E.164 or a national NANP number; stored as E.164 (e.g. +14165550134).",
                    "example": "+14165550134"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Client already onboarded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ClientProfile"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "201": {
            "description": "Client onboarded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ClientProfile"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid name or phone number",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "No access to project or unregistered user, or the membership here was deactivated (MEMBERSHIP_INACTIVE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Project not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "Email already belongs to a different linked client",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "patch": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Clients"],
        "summary": "Update the authenticated client's contact details",
        "description": "Changes the signed-in client's first name, last name and/or phone number in this project. The profile is resolved from the client user JWT, never from the URL, and requires both the API key (`x-api-key`) and the JWT (`Authorization: Bearer`). The caller must already be onboarded: POST /clients/me first, or this is a 404.\n\nSend only the fields to change; an omitted field is left unchanged, but a body with nothing to update is a 400. Names are trimmed and must be 1–80 characters: they can be changed but not cleared, so a blank or `null` name is a 400. The name is the client's record in this project only (what the business sees on orders, bookings and emails); it does not rename the person's MarketBox account. Send `phone: null` (or a blank string) to clear the stored phone. The phone is validated and stored in E.164 form (`+14165550134`). Send it as E.164, or as a national North American (NANP) number such as `(416) 555-0134`; numbers outside North America must start with `+` and the country code, or they are rejected. An invalid number is a 400 and nothing is written.\n\nCall it before creating the order (`POST /orders`) so booking and order emails use the updated name. The change is also copied to the client's Stripe customer on the project's connected account; if that copy fails, the profile is still updated and this still returns 200. Returns the whole profile, with its saved addresses.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "firstName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80,
                    "description": "The client's new first name (1–80 characters, trimmed). Omit to leave it unchanged.",
                    "example": "Emma"
                  },
                  "lastName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80,
                    "description": "The client's new last name (1–80 characters, trimmed). Omit to leave it unchanged.",
                    "example": "Bishop"
                  },
                  "phone": {
                    "type": "string",
                    "nullable": true,
                    "description": "Phone number. Accepts E.164 or a national NANP number; stored as E.164 (e.g. +14165550134).",
                    "example": "+14165550134"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Client updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ClientProfile"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid name or phone number, or nothing to update",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "No access to project or unregistered user, or the signed-in user is not an ACTIVE member of it holding the route’s permission (FORBIDDEN), or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "No client profile for this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/clients/me/credits": {
      "get": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Clients"],
        "summary": "Get the authenticated client's package credits",
        "description": "Returns the signed-in client's remaining package credits on the project. Each entry is a PACKAGE order item the client owns; `quantityRemaining` is the live, authoritative balance. Only PAID orders count, and expired or fully-drawn-down packages are omitted (pass `includeExpired=true` to keep expired ones). `quantityReturned` counts the sessions cancellations have returned to the credit, ever; they are already inside `quantityRemaining`, and a returned session may have been booked again since. Requires both an API key (`x-api-key`) and a client user JWT (`Authorization: Bearer`).",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "enum": ["true", "false"],
              "default": "false"
            },
            "required": false,
            "name": "includeExpired",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Client package credits",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "orderId": {
                            "type": "string"
                          },
                          "orderItemId": {
                            "type": "string"
                          },
                          "packageId": {
                            "type": "string",
                            "nullable": true
                          },
                          "serviceId": {
                            "type": "string"
                          },
                          "offeringId": {
                            "type": "string"
                          },
                          "quantity": {
                            "type": "integer",
                            "minimum": 0,
                            "exclusiveMinimum": true
                          },
                          "quantityAllocated": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "quantityRemaining": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "unitPrice": {
                            "$ref": "#/components/schemas/Money"
                          },
                          "expiresAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "orderStatus": {
                            "type": "string",
                            "enum": ["DRAFT", "PENDING", "PAID", "CANCELLED"]
                          },
                          "quantityReturned": {
                            "type": "integer",
                            "minimum": 0,
                            "description": "Sessions returned to this credit by cancellations, ever. Already counted in quantityRemaining; a returned session may have been booked again since."
                          }
                        },
                        "required": [
                          "orderId",
                          "orderItemId",
                          "serviceId",
                          "offeringId",
                          "quantity",
                          "quantityAllocated",
                          "quantityRemaining",
                          "unitPrice",
                          "orderStatus",
                          "quantityReturned"
                        ]
                      }
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "No access to project or unregistered user, or the signed-in user is not an ACTIVE member of it holding the route’s permission (FORBIDDEN), or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Project not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/clients/me/orders/{orderId}/package-bookings": {
      "post": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Clients"],
        "summary": "Book sessions from the authenticated client's own package credit",
        "description": "The signed-in client books their own credit. Only credits `GET /clients/me/credits` returns can be booked. Same body, response and refusals as `POST /orders/{orderId}/package-bookings` (a cancelled order is 409 `ORDER_CANCELLED` there and here), plus 404 for another client's order and 409 `CREDIT_NOT_BOOKABLE` for any other credit the credits read would not list (unpaid, used up, expired or removed). A `slateId` / `slotIds` must come from a slate planned from this credit (`POST /availability/package-slate` with this `orderId` and `orderItemId`); any other is a 404, the same body as an unknown id.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The order — the commercial record. Order items are drawn down into bookings.",
              "example": "ord_01kv8m92p4jcrywn14znp8cym0"
            },
            "required": true,
            "description": "The order — the commercial record. Order items are drawn down into bookings.",
            "name": "orderId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Order item + sessions + atomicity",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "orderItemId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The PACKAGE order item to draw down. All N sessions decrement its quantityRemaining.",
                    "example": "oi_01kx16ek2kf2fsc9x7b2n1dfc9"
                  },
                  "idempotencyKey": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Idempotency key that makes retry attempts safe; reusing it returns the original result. A slateId/slotIds retry must arrive within the slate's resolvable window; after that it is refused like a stale slate.",
                    "example": "a3f1c2e4-5b6d-4e7f-8a9b-0c1d2e3f4a5b"
                  },
                  "atomicity": {
                    "type": "string",
                    "enum": ["all_or_nothing", "best_effort"],
                    "default": "all_or_nothing",
                    "description": "all_or_nothing (default, one transaction, max 15 sessions) or best_effort (per-session; requires project opt-in).",
                    "example": "all_or_nothing"
                  },
                  "sessions": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "supplierId": {
                          "type": "string",
                          "minLength": 1,
                          "description": "The supplier who delivers the session. Must belong to this project.",
                          "example": "sup_01kx16ejb3fz2g5h8k1m4p7r9t"
                        },
                        "bookingStartUtc": {
                          "type": "string",
                          "format": "date-time",
                          "description": "When the session starts, as an ISO 8601 UTC instant.",
                          "example": "2026-11-03T20:00:00.000Z"
                        },
                        "bookingEndUtc": {
                          "type": "string",
                          "format": "date-time",
                          "description": "When the session ends, as an ISO 8601 UTC instant.",
                          "example": "2026-11-03T20:30:00.000Z"
                        },
                        "bookingTz": {
                          "type": "string",
                          "minLength": 1,
                          "description": "The session's home zone (IANA). The booking's local date and times are derived from the UTC instants in this zone.",
                          "example": "America/Toronto"
                        },
                        "locationType": {
                          "type": "string",
                          "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"],
                          "description": "Where the session happens: PHYSICAL (at a venue; locationId required), TRAVEL_ZONE (at the client's address; locationId is the supplier's travel zone, and latitude, longitude and address are required) or VIRTUAL (online; locationId must be null).",
                          "example": "VIRTUAL"
                        },
                        "locationId": {
                          "type": "string",
                          "nullable": true,
                          "minLength": 1,
                          "description": "The venue (PHYSICAL) or supplier travel zone (TRAVEL_ZONE). Null for VIRTUAL.",
                          "example": "loc_01kx16ejc7fq4r6s9v2x5z8b1d"
                        },
                        "latitude": {
                          "type": "number",
                          "nullable": true,
                          "description": "Latitude of the client's address. Required for TRAVEL_ZONE.",
                          "example": 43.6532
                        },
                        "longitude": {
                          "type": "number",
                          "nullable": true,
                          "description": "Longitude of the client's address. Required for TRAVEL_ZONE.",
                          "example": -79.3832
                        },
                        "address": {
                          "$ref": "#/components/schemas/Address"
                        },
                        "services": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "serviceId": {
                                "type": "string",
                                "minLength": 1,
                                "description": "The service this session books. Must be the order item's own service.",
                                "example": "srv_01kx16ej8wfp0b4v3x1q7m2d5c"
                              },
                              "offeringId": {
                                "type": "string",
                                "minLength": 1,
                                "description": "The offering this session books. Must be the order item's own offering.",
                                "example": "off_01kx16ej9af1c3s8t6y2w4n7hb"
                              }
                            },
                            "required": ["serviceId", "offeringId"]
                          },
                          "minItems": 1,
                          "description": "The service lines of the session: the order item's service and offering.",
                          "example": [
                            {
                              "serviceId": "srv_01kx16ej8wfp0b4v3x1q7m2d5c",
                              "offeringId": "off_01kx16ej9af1c3s8t6y2w4n7hb"
                            }
                          ]
                        }
                      },
                      "required": [
                        "supplierId",
                        "bookingStartUtc",
                        "bookingEndUtc",
                        "bookingTz",
                        "locationType",
                        "services"
                      ]
                    },
                    "minItems": 1,
                    "description": "Explicit, client-supplied sessions (advanced). Prefer slateId. Provide exactly one of sessions, slateId, or slotIds."
                  },
                  "slateId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Book an entire persisted slate by id (recommended). The server resolves every session; send no session details.",
                    "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                  },
                  "slotIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1
                    },
                    "minItems": 1,
                    "description": "Cherry-pick specific persisted slots by id. Provide exactly one of sessions, slateId, or slotIds.",
                    "example": ["slot_01kx16ejsrfs7tf3edy19wdsf8"]
                  }
                },
                "required": ["orderItemId", "idempotencyKey"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Package bookings created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "orderId": {
                      "type": "string"
                    },
                    "orderItemId": {
                      "type": "string"
                    },
                    "packageOrderItemId": {
                      "type": "string"
                    },
                    "atomicity": {
                      "type": "string",
                      "enum": ["all_or_nothing", "best_effort"]
                    },
                    "created": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "sessionIndex": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "bookingId": {
                            "type": "string"
                          },
                          "allocationId": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "sessionIndex",
                          "bookingId",
                          "allocationId"
                        ]
                      },
                      "description": "Bookings created, each with a 0-based sessionIndex, bookingId and allocationId."
                    },
                    "failed": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "sessionIndex": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "reason": {
                            "type": "string"
                          }
                        },
                        "required": ["sessionIndex", "reason"]
                      },
                      "description": "Per-session failures (best_effort only)."
                    },
                    "quantityRemaining": {
                      "type": "integer",
                      "minimum": 0,
                      "description": "Credits left on the order item after this call."
                    }
                  },
                  "required": [
                    "orderId",
                    "orderItemId",
                    "packageOrderItemId",
                    "atomicity",
                    "created",
                    "failed",
                    "quantityRemaining"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validation error, a session for another service/offering, more sessions than remain, or a location of the wrong type / another supplier’s / with invalid fields",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "No access to project or unregistered user, or the signed-in user is not an ACTIVE member of it holding the route’s permission (FORBIDDEN), or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "No client profile for this project; the order is missing or another client's (one body); a slateId/slotId is unknown or not planned from this credit (one body); or the item / offering / supplier / location was not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "ORDER_CANCELLED (a cancelled order), CREDIT_NOT_BOOKABLE (not a credit GET /clients/me/credits returns), PACKAGE_EXPIRED, ORDER_ITEM_QUANTITY_UNAVAILABLE (a concurrent booking used the credits first), IDEMPOTENCY_KEY_CONFLICT, SLOT_HELD/SLOT_BOOKED, OCCUPANCY_CONTENTION, or the slate/slot went stale (freshSuggestions returned)",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/ErrorMessage"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": ["SLOT_HELD", "SLOT_BOOKED"],
                          "description": "Which kind of claim is blocking the requested time.",
                          "example": "SLOT_HELD"
                        },
                        "message": {
                          "type": "string",
                          "description": "Human-readable summary of the conflict.",
                          "example": "Supplier time is not available: HOLD resv_01kv8p20m1gnqvxl92xln6awk8 (2026-08-01T10:00:00Z–2026-08-01T11:00:00Z)"
                        },
                        "statusCode": {
                          "type": "number",
                          "enum": [409],
                          "description": "The HTTP status, repeated in the body — every MarketBox error carries it, so you can branch on the body alone.",
                          "example": 409
                        },
                        "requestId": {
                          "type": "string",
                          "description": "The id of this request (also returned as the X-Request-Id header). Quote it in a support ticket.",
                          "example": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
                        },
                        "conflicts": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "claimType": {
                                "type": "string",
                                "enum": ["BOOKING", "HOLD"],
                                "description": "Whether the blocking claim is a HOLD or a confirmed BOOKING."
                              },
                              "supplierId": {
                                "type": "string",
                                "nullable": true,
                                "description": "The supplier whose calendar is blocked, when known."
                              },
                              "startUtc": {
                                "type": "string",
                                "format": "date-time",
                                "description": "Start of the blocking claim, UTC ISO 8601.",
                                "example": "2026-08-01T10:00:00Z"
                              },
                              "endUtc": {
                                "type": "string",
                                "format": "date-time",
                                "description": "End of the blocking claim, UTC ISO 8601.",
                                "example": "2026-08-01T11:00:00Z"
                              },
                              "reservationId": {
                                "type": "string",
                                "nullable": true,
                                "description": "Present when claimType is HOLD — the reservationId to convert or release. Null for a BOOKING conflict.",
                                "example": "resv_01kv8p20m1gnqvxl92xln6awk8"
                              },
                              "bookingId": {
                                "type": "string",
                                "nullable": true,
                                "description": "Present when claimType is BOOKING — the id of the confirmed booking occupying this time. Null for a HOLD conflict.",
                                "example": null
                              },
                              "heldUntil": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time",
                                "description": "HOLD only: when the blocking hold lazily expires. Null for a BOOKING conflict.",
                                "example": "2026-08-01T10:05:00Z"
                              }
                            },
                            "required": ["claimType", "startUtc", "endUtc"]
                          },
                          "description": "Every live claim that overlaps the requested time — usually one, but can be more."
                        },
                        "hint": {
                          "type": "string",
                          "description": "What to do next: for SLOT_HELD, convert or release the named reservationId (POST .../holds/{reservationId}/convert or /release); for SLOT_BOOKED, search availability again.",
                          "example": "This time is held (reservation resv_01kv8p20m1gnqvxl92xln6awk8). Convert the hold via POST /v1/projects/{projectId}/holds/{reservationId}/convert, or release it with POST /v1/projects/{projectId}/holds/{reservationId}/release. Direct booking routes will not consume a hold — if you hold, you convert."
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "statusCode",
                        "requestId",
                        "conflicts",
                        "hint"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "statusCode": {
                          "type": "number",
                          "enum": [409],
                          "description": "The HTTP status, repeated in the body — every MarketBox error carries it, so you can branch on the body alone.",
                          "example": 409
                        },
                        "requestId": {
                          "type": "string",
                          "description": "The id of this request (also returned as the X-Request-Id header). Quote it in a support ticket.",
                          "example": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
                        },
                        "freshSuggestions": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "searchId": {
                              "type": "string",
                              "description": "The id of this search, also returned as the `X-MB-Search-Id` header. Every page of a paginated search carries the same id (the cursor keeps it). Keep it for the session if you want attribution: pass it back as `searchId` when the client books, and in the `search.rendered` event when you report what you showed.",
                              "example": "srch_01k7q3x9h4e8rb2d6m0z5a7c1n"
                            },
                            "status": {
                              "type": "string",
                              "enum": [
                                "OK",
                                "ALTERNATIVE_CADENCE",
                                "NO_COMPLETE_SLATE",
                                "NO_AVAILABILITY"
                              ],
                              "description": "OK, ALTERNATIVE_CADENCE, NO_COMPLETE_SLATE, or NO_AVAILABILITY. ALTERNATIVE_CADENCE is only reachable when this request opted in via cadenceFlexibility or guaranteeSlate — a request sending today’s body (neither set) never observes it."
                            },
                            "reason": {
                              "type": "string",
                              "nullable": true
                            },
                            "suggestionRequestId": {
                              "type": "string",
                              "nullable": true,
                              "description": "Audit id for this suggestion request (present when persisted)."
                            },
                            "resolvableUntil": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "primarySlate": {
                              "type": "object",
                              "nullable": true,
                              "properties": {
                                "slateId": {
                                  "type": "string",
                                  "description": "Pass this to POST .../package-bookings to book the whole plan.",
                                  "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                                },
                                "supplierId": {
                                  "type": "string"
                                },
                                "completeness": {
                                  "type": "string",
                                  "enum": ["COMPLETE", "PARTIAL"]
                                },
                                "sessionsRequested": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true,
                                  "description": "How many sessions were requested (the package's creditCount)."
                                },
                                "sessionsFilled": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "How many of the requested sessions the plan could fill."
                                },
                                "startTimeConsistencyPercent": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 100
                                },
                                "totalTravelTimeMins": {
                                  "type": "number",
                                  "minimum": 0
                                },
                                "slots": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "slotId": {
                                        "type": "string",
                                        "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                                      },
                                      "sessionIndex": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "1-based index of this session within the slate."
                                      },
                                      "supplierId": {
                                        "type": "string"
                                      },
                                      "serviceId": {
                                        "type": "string"
                                      },
                                      "offeringId": {
                                        "type": "string"
                                      },
                                      "bookingStartUtc": {
                                        "type": "string",
                                        "format": "date-time"
                                      },
                                      "bookingEndUtc": {
                                        "type": "string",
                                        "format": "date-time"
                                      },
                                      "bookingTz": {
                                        "type": "string"
                                      },
                                      "locationType": {
                                        "type": "string",
                                        "enum": [
                                          "PHYSICAL",
                                          "VIRTUAL",
                                          "TRAVEL_ZONE"
                                        ]
                                      },
                                      "locationId": {
                                        "type": "string",
                                        "nullable": true
                                      },
                                      "latitude": {
                                        "type": "number",
                                        "nullable": true
                                      },
                                      "longitude": {
                                        "type": "number",
                                        "nullable": true
                                      },
                                      "address": {
                                        "$ref": "#/components/schemas/Address"
                                      },
                                      "travelTimeMins": {
                                        "type": "number",
                                        "nullable": true,
                                        "minimum": 0
                                      },
                                      "capacity": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true
                                      },
                                      "reservationStatus": {
                                        "type": "string",
                                        "enum": [
                                          "FREE",
                                          "HELD",
                                          "CONVERTED",
                                          "RELEASED"
                                        ]
                                      }
                                    },
                                    "required": [
                                      "slotId",
                                      "sessionIndex",
                                      "supplierId",
                                      "serviceId",
                                      "offeringId",
                                      "bookingStartUtc",
                                      "bookingEndUtc",
                                      "bookingTz",
                                      "locationType",
                                      "locationId",
                                      "latitude",
                                      "longitude",
                                      "address",
                                      "travelTimeMins",
                                      "capacity",
                                      "reservationStatus"
                                    ]
                                  }
                                },
                                "position": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                                  "example": 0
                                },
                                "cadenceRrule": {
                                  "type": "string",
                                  "nullable": true,
                                  "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                                  "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                                },
                                "matchesRequestedCadence": {
                                  "type": "boolean",
                                  "description": "True when cadenceRrule is the rrule you asked for.",
                                  "example": false
                                },
                                "cadenceRelaxation": {
                                  "type": "string",
                                  "enum": [
                                    "EXACT",
                                    "INTERVAL_TIGHTENED",
                                    "DAYS_ADDED",
                                    "DAYS_SUBSTITUTED",
                                    "ALL_WORKING_DAYS",
                                    "DIRECT_FILL"
                                  ],
                                  "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                },
                                "cadenceDistance": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                                  "example": 2
                                },
                                "cadenceSummary": {
                                  "type": "object",
                                  "properties": {
                                    "requested": {
                                      "type": "integer",
                                      "nullable": true,
                                      "minimum": 0,
                                      "exclusiveMinimum": true,
                                      "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                                      "example": 4
                                    },
                                    "peak": {
                                      "type": "integer",
                                      "minimum": 0,
                                      "exclusiveMinimum": true,
                                      "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                                      "example": 4
                                    },
                                    "average": {
                                      "type": "number",
                                      "minimum": 0,
                                      "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                                      "example": 2.25
                                    },
                                    "byWeek": {
                                      "type": "array",
                                      "items": {
                                        "type": "object",
                                        "properties": {
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                            "example": "2026-09-14"
                                          },
                                          "sessions": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                            "example": 0
                                          }
                                        },
                                        "required": ["weekStart", "sessions"]
                                      },
                                      "minItems": 1,
                                      "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                                    }
                                  },
                                  "required": [
                                    "requested",
                                    "peak",
                                    "average",
                                    "byWeek"
                                  ],
                                  "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                                },
                                "matchNotes": {
                                  "type": "array",
                                  "items": {
                                    "oneOf": [
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": [
                                              "SUPPLIER_UNAVAILABLE_WEEK"
                                            ]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "openingsInPool": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                "example": 2
                                              },
                                              "supplierWorkdays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "openingsInPool",
                                              "supplierWorkdays"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_EXCLUDED_BY_FILTERS"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "filter": {
                                                "type": "string",
                                                "enum": [
                                                  "daysOfWeek",
                                                  "excludeDates"
                                                ]
                                              },
                                              "supplierWorkdays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "requestedDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "excludedDates": {
                                                "type": "array",
                                                "items": {
                                                  "type": "string"
                                                }
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "filter",
                                              "supplierWorkdays"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_SUPPLY_INSUFFICIENT"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "openingsInPool": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                "example": 2
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "openingsInPool"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_CAPPED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "cap": {
                                                "type": "string",
                                                "enum": [
                                                  "maxSessionsPerWeek",
                                                  "minGapDays"
                                                ]
                                              },
                                              "capValue": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "cap",
                                              "capValue"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["SESSIONS_EXHAUSTED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsRequested": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              },
                                              "sessionsPlacedBefore": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "required": [
                                              "sessionsRequested",
                                              "sessionsPlacedBefore"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["CADENCE_RELAXED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["cadence"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "cadenceRelaxation": {
                                                "type": "string",
                                                "enum": [
                                                  "EXACT",
                                                  "INTERVAL_TIGHTENED",
                                                  "DAYS_ADDED",
                                                  "DAYS_SUBSTITUTED",
                                                  "ALL_WORKING_DAYS",
                                                  "DIRECT_FILL"
                                                ],
                                                "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                              },
                                              "requestedDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "actualDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              }
                                            },
                                            "required": ["cadenceRelaxation"]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": [
                                              "SESSIONS_OUTSIDE_PREFERRED_TIMES"
                                            ]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["timeOfDay"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionIndexes": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                }
                                              },
                                              "localTimes": {
                                                "type": "array",
                                                "items": {
                                                  "type": "string"
                                                }
                                              }
                                            },
                                            "required": [
                                              "sessionIndexes",
                                              "localTimes"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["FIRST_SESSION_LATE"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["startDate"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "firstSessionDate": {
                                                "type": "string"
                                              },
                                              "windowStartDate": {
                                                "type": "string"
                                              },
                                              "dayOffset": {
                                                "type": "integer",
                                                "minimum": 0
                                              },
                                              "earlierSupplyExisted": {
                                                "type": "boolean",
                                                "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                              }
                                            },
                                            "required": [
                                              "firstSessionDate",
                                              "windowStartDate",
                                              "dayOffset",
                                              "earlierSupplyExisted"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["PACKAGE_UNDERFILLED"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsRequested": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              },
                                              "sessionsFilled": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "required": [
                                              "sessionsRequested",
                                              "sessionsFilled"
                                            ]
                                          }
                                        },
                                        "required": ["code", "evidence"],
                                        "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                                      }
                                    ]
                                  },
                                  "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                                },
                                "advice": {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["LATER_START_IMPROVES_CADENCE"]
                                    },
                                    "earliestSustainedWeek": {
                                      "type": "string",
                                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                      "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                                      "example": "2026-09-14"
                                    }
                                  },
                                  "required": ["code", "earliestSustainedWeek"],
                                  "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                                },
                                "matchScore": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 1,
                                  "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                                  "example": 1
                                },
                                "matchComponents": {
                                  "type": "object",
                                  "properties": {
                                    "startDate": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                                    },
                                    "timeOfDay": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                                    },
                                    "daysOfWeek": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                                    },
                                    "sessionsPerWeek": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                                    },
                                    "cadence": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                                    }
                                  },
                                  "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                                }
                              },
                              "required": [
                                "slateId",
                                "supplierId",
                                "completeness",
                                "sessionsRequested",
                                "sessionsFilled",
                                "startTimeConsistencyPercent",
                                "totalTravelTimeMins",
                                "slots",
                                "matchNotes",
                                "matchScore"
                              ],
                              "description": "The best COMPLETE single-supplier slate; book this by slateId."
                            },
                            "alternates": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "slateId": {
                                    "type": "string",
                                    "description": "Pass this to POST .../package-bookings to book the whole plan.",
                                    "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                                  },
                                  "supplierId": {
                                    "type": "string"
                                  },
                                  "completeness": {
                                    "type": "string",
                                    "enum": ["COMPLETE", "PARTIAL"]
                                  },
                                  "sessionsRequested": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "exclusiveMinimum": true,
                                    "description": "How many sessions were requested (the package's creditCount)."
                                  },
                                  "sessionsFilled": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "How many of the requested sessions the plan could fill."
                                  },
                                  "startTimeConsistencyPercent": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 100
                                  },
                                  "totalTravelTimeMins": {
                                    "type": "number",
                                    "minimum": 0
                                  },
                                  "slots": {
                                    "type": "array",
                                    "items": {
                                      "type": "object",
                                      "properties": {
                                        "slotId": {
                                          "type": "string",
                                          "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                                        },
                                        "sessionIndex": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true,
                                          "description": "1-based index of this session within the slate."
                                        },
                                        "supplierId": {
                                          "type": "string"
                                        },
                                        "serviceId": {
                                          "type": "string"
                                        },
                                        "offeringId": {
                                          "type": "string"
                                        },
                                        "bookingStartUtc": {
                                          "type": "string",
                                          "format": "date-time"
                                        },
                                        "bookingEndUtc": {
                                          "type": "string",
                                          "format": "date-time"
                                        },
                                        "bookingTz": {
                                          "type": "string"
                                        },
                                        "locationType": {
                                          "type": "string",
                                          "enum": [
                                            "PHYSICAL",
                                            "VIRTUAL",
                                            "TRAVEL_ZONE"
                                          ]
                                        },
                                        "locationId": {
                                          "type": "string",
                                          "nullable": true
                                        },
                                        "latitude": {
                                          "type": "number",
                                          "nullable": true
                                        },
                                        "longitude": {
                                          "type": "number",
                                          "nullable": true
                                        },
                                        "address": {
                                          "$ref": "#/components/schemas/Address"
                                        },
                                        "travelTimeMins": {
                                          "type": "number",
                                          "nullable": true,
                                          "minimum": 0
                                        },
                                        "capacity": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true
                                        },
                                        "reservationStatus": {
                                          "type": "string",
                                          "enum": [
                                            "FREE",
                                            "HELD",
                                            "CONVERTED",
                                            "RELEASED"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "slotId",
                                        "sessionIndex",
                                        "supplierId",
                                        "serviceId",
                                        "offeringId",
                                        "bookingStartUtc",
                                        "bookingEndUtc",
                                        "bookingTz",
                                        "locationType",
                                        "locationId",
                                        "latitude",
                                        "longitude",
                                        "address",
                                        "travelTimeMins",
                                        "capacity",
                                        "reservationStatus"
                                      ]
                                    }
                                  },
                                  "position": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                                    "example": 0
                                  },
                                  "cadenceRrule": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                                    "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                                  },
                                  "matchesRequestedCadence": {
                                    "type": "boolean",
                                    "description": "True when cadenceRrule is the rrule you asked for.",
                                    "example": false
                                  },
                                  "cadenceRelaxation": {
                                    "type": "string",
                                    "enum": [
                                      "EXACT",
                                      "INTERVAL_TIGHTENED",
                                      "DAYS_ADDED",
                                      "DAYS_SUBSTITUTED",
                                      "ALL_WORKING_DAYS",
                                      "DIRECT_FILL"
                                    ],
                                    "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                  },
                                  "cadenceDistance": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                                    "example": 2
                                  },
                                  "cadenceSummary": {
                                    "type": "object",
                                    "properties": {
                                      "requested": {
                                        "type": "integer",
                                        "nullable": true,
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                                        "example": 4
                                      },
                                      "peak": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                                        "example": 4
                                      },
                                      "average": {
                                        "type": "number",
                                        "minimum": 0,
                                        "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                                        "example": 2.25
                                      },
                                      "byWeek": {
                                        "type": "array",
                                        "items": {
                                          "type": "object",
                                          "properties": {
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                              "example": "2026-09-14"
                                            },
                                            "sessions": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                              "example": 0
                                            }
                                          },
                                          "required": ["weekStart", "sessions"]
                                        },
                                        "minItems": 1,
                                        "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                                      }
                                    },
                                    "required": [
                                      "requested",
                                      "peak",
                                      "average",
                                      "byWeek"
                                    ],
                                    "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                                  },
                                  "matchNotes": {
                                    "type": "array",
                                    "items": {
                                      "oneOf": [
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "SUPPLIER_UNAVAILABLE_WEEK"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "openingsInPool": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                  "example": 2
                                                },
                                                "supplierWorkdays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "openingsInPool",
                                                "supplierWorkdays"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "WEEK_EXCLUDED_BY_FILTERS"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "filter": {
                                                  "type": "string",
                                                  "enum": [
                                                    "daysOfWeek",
                                                    "excludeDates"
                                                  ]
                                                },
                                                "supplierWorkdays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                },
                                                "requestedDays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                },
                                                "excludedDates": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "string"
                                                  }
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "filter",
                                                "supplierWorkdays"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "WEEK_SUPPLY_INSUFFICIENT"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "openingsInPool": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                  "example": 2
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "openingsInPool"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["WEEK_CAPPED"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "cap": {
                                                  "type": "string",
                                                  "enum": [
                                                    "maxSessionsPerWeek",
                                                    "minGapDays"
                                                  ]
                                                },
                                                "capValue": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "cap",
                                                "capValue"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["SESSIONS_EXHAUSTED"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsRequested": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                },
                                                "sessionsPlacedBefore": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                }
                                              },
                                              "required": [
                                                "sessionsRequested",
                                                "sessionsPlacedBefore"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["CADENCE_RELAXED"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["cadence"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "cadenceRelaxation": {
                                                  "type": "string",
                                                  "enum": [
                                                    "EXACT",
                                                    "INTERVAL_TIGHTENED",
                                                    "DAYS_ADDED",
                                                    "DAYS_SUBSTITUTED",
                                                    "ALL_WORKING_DAYS",
                                                    "DIRECT_FILL"
                                                  ],
                                                  "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                                },
                                                "requestedDays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                },
                                                "actualDays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                }
                                              },
                                              "required": ["cadenceRelaxation"]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "evidence"
                                          ],
                                          "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "SESSIONS_OUTSIDE_PREFERRED_TIMES"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["timeOfDay"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionIndexes": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "exclusiveMinimum": true
                                                  }
                                                },
                                                "localTimes": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "string"
                                                  }
                                                }
                                              },
                                              "required": [
                                                "sessionIndexes",
                                                "localTimes"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "evidence"
                                          ],
                                          "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["FIRST_SESSION_LATE"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["startDate"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "firstSessionDate": {
                                                  "type": "string"
                                                },
                                                "windowStartDate": {
                                                  "type": "string"
                                                },
                                                "dayOffset": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "earlierSupplyExisted": {
                                                  "type": "boolean",
                                                  "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                                }
                                              },
                                              "required": [
                                                "firstSessionDate",
                                                "windowStartDate",
                                                "dayOffset",
                                                "earlierSupplyExisted"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "evidence"
                                          ],
                                          "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["PACKAGE_UNDERFILLED"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsRequested": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                },
                                                "sessionsFilled": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                }
                                              },
                                              "required": [
                                                "sessionsRequested",
                                                "sessionsFilled"
                                              ]
                                            }
                                          },
                                          "required": ["code", "evidence"],
                                          "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                                        }
                                      ]
                                    },
                                    "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                                  },
                                  "advice": {
                                    "type": "object",
                                    "properties": {
                                      "code": {
                                        "type": "string",
                                        "enum": ["LATER_START_IMPROVES_CADENCE"]
                                      },
                                      "earliestSustainedWeek": {
                                        "type": "string",
                                        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                        "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                                        "example": "2026-09-14"
                                      }
                                    },
                                    "required": [
                                      "code",
                                      "earliestSustainedWeek"
                                    ],
                                    "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                                  },
                                  "matchScore": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1,
                                    "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                                    "example": 1
                                  },
                                  "matchComponents": {
                                    "type": "object",
                                    "properties": {
                                      "startDate": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                                      },
                                      "timeOfDay": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                                      },
                                      "daysOfWeek": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                                      },
                                      "sessionsPerWeek": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                                      },
                                      "cadence": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                                      }
                                    },
                                    "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                                  }
                                },
                                "required": [
                                  "slateId",
                                  "supplierId",
                                  "completeness",
                                  "sessionsRequested",
                                  "sessionsFilled",
                                  "startTimeConsistencyPercent",
                                  "totalTravelTimeMins",
                                  "slots",
                                  "matchNotes",
                                  "matchScore"
                                ]
                              },
                              "description": "Other bookable options beyond primarySlate, ranked best first and capped at the maxAlternates you sent. Under the default supplierPolicy of SAME_SUPPLIER these are other schedules from the SAME supplier as primarySlate; under PREFERRED or ANY they are other suppliers’ best schedules, one per supplier. Two schedules from one supplier count as different options only when they run on different weekdays, or start at least 30 minutes apart — so a supplier offering 09:00 and 09:20 gives you one option, not two. Each entry’s slateId is bookable exactly like primarySlate’s."
                            },
                            "partial": {
                              "type": "object",
                              "nullable": true,
                              "properties": {
                                "slateId": {
                                  "type": "string",
                                  "description": "Pass this to POST .../package-bookings to book the whole plan.",
                                  "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                                },
                                "supplierId": {
                                  "type": "string"
                                },
                                "completeness": {
                                  "type": "string",
                                  "enum": ["COMPLETE", "PARTIAL"]
                                },
                                "sessionsRequested": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true,
                                  "description": "How many sessions were requested (the package's creditCount)."
                                },
                                "sessionsFilled": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "How many of the requested sessions the plan could fill."
                                },
                                "startTimeConsistencyPercent": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 100
                                },
                                "totalTravelTimeMins": {
                                  "type": "number",
                                  "minimum": 0
                                },
                                "slots": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "slotId": {
                                        "type": "string",
                                        "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                                      },
                                      "sessionIndex": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "1-based index of this session within the slate."
                                      },
                                      "supplierId": {
                                        "type": "string"
                                      },
                                      "serviceId": {
                                        "type": "string"
                                      },
                                      "offeringId": {
                                        "type": "string"
                                      },
                                      "bookingStartUtc": {
                                        "type": "string",
                                        "format": "date-time"
                                      },
                                      "bookingEndUtc": {
                                        "type": "string",
                                        "format": "date-time"
                                      },
                                      "bookingTz": {
                                        "type": "string"
                                      },
                                      "locationType": {
                                        "type": "string",
                                        "enum": [
                                          "PHYSICAL",
                                          "VIRTUAL",
                                          "TRAVEL_ZONE"
                                        ]
                                      },
                                      "locationId": {
                                        "type": "string",
                                        "nullable": true
                                      },
                                      "latitude": {
                                        "type": "number",
                                        "nullable": true
                                      },
                                      "longitude": {
                                        "type": "number",
                                        "nullable": true
                                      },
                                      "address": {
                                        "$ref": "#/components/schemas/Address"
                                      },
                                      "travelTimeMins": {
                                        "type": "number",
                                        "nullable": true,
                                        "minimum": 0
                                      },
                                      "capacity": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true
                                      },
                                      "reservationStatus": {
                                        "type": "string",
                                        "enum": [
                                          "FREE",
                                          "HELD",
                                          "CONVERTED",
                                          "RELEASED"
                                        ]
                                      }
                                    },
                                    "required": [
                                      "slotId",
                                      "sessionIndex",
                                      "supplierId",
                                      "serviceId",
                                      "offeringId",
                                      "bookingStartUtc",
                                      "bookingEndUtc",
                                      "bookingTz",
                                      "locationType",
                                      "locationId",
                                      "latitude",
                                      "longitude",
                                      "address",
                                      "travelTimeMins",
                                      "capacity",
                                      "reservationStatus"
                                    ]
                                  }
                                },
                                "position": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                                  "example": 0
                                },
                                "cadenceRrule": {
                                  "type": "string",
                                  "nullable": true,
                                  "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                                  "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                                },
                                "matchesRequestedCadence": {
                                  "type": "boolean",
                                  "description": "True when cadenceRrule is the rrule you asked for.",
                                  "example": false
                                },
                                "cadenceRelaxation": {
                                  "type": "string",
                                  "enum": [
                                    "EXACT",
                                    "INTERVAL_TIGHTENED",
                                    "DAYS_ADDED",
                                    "DAYS_SUBSTITUTED",
                                    "ALL_WORKING_DAYS",
                                    "DIRECT_FILL"
                                  ],
                                  "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                },
                                "cadenceDistance": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                                  "example": 2
                                },
                                "cadenceSummary": {
                                  "type": "object",
                                  "properties": {
                                    "requested": {
                                      "type": "integer",
                                      "nullable": true,
                                      "minimum": 0,
                                      "exclusiveMinimum": true,
                                      "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                                      "example": 4
                                    },
                                    "peak": {
                                      "type": "integer",
                                      "minimum": 0,
                                      "exclusiveMinimum": true,
                                      "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                                      "example": 4
                                    },
                                    "average": {
                                      "type": "number",
                                      "minimum": 0,
                                      "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                                      "example": 2.25
                                    },
                                    "byWeek": {
                                      "type": "array",
                                      "items": {
                                        "type": "object",
                                        "properties": {
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                            "example": "2026-09-14"
                                          },
                                          "sessions": {
                                            "type": "integer",
                                            "minimum": 0,
                                            "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                            "example": 0
                                          }
                                        },
                                        "required": ["weekStart", "sessions"]
                                      },
                                      "minItems": 1,
                                      "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                                    }
                                  },
                                  "required": [
                                    "requested",
                                    "peak",
                                    "average",
                                    "byWeek"
                                  ],
                                  "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                                },
                                "matchNotes": {
                                  "type": "array",
                                  "items": {
                                    "oneOf": [
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": [
                                              "SUPPLIER_UNAVAILABLE_WEEK"
                                            ]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "openingsInPool": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                "example": 2
                                              },
                                              "supplierWorkdays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "openingsInPool",
                                              "supplierWorkdays"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_EXCLUDED_BY_FILTERS"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "filter": {
                                                "type": "string",
                                                "enum": [
                                                  "daysOfWeek",
                                                  "excludeDates"
                                                ]
                                              },
                                              "supplierWorkdays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "requestedDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "excludedDates": {
                                                "type": "array",
                                                "items": {
                                                  "type": "string"
                                                }
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "filter",
                                              "supplierWorkdays"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_SUPPLY_INSUFFICIENT"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "openingsInPool": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                "example": 2
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "openingsInPool"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["WEEK_CAPPED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsPlaced": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Sessions this slate placed in this week."
                                              },
                                              "sessionsTargeted": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true,
                                                "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                              },
                                              "cap": {
                                                "type": "string",
                                                "enum": [
                                                  "maxSessionsPerWeek",
                                                  "minGapDays"
                                                ]
                                              },
                                              "capValue": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              }
                                            },
                                            "required": [
                                              "sessionsPlaced",
                                              "sessionsTargeted",
                                              "cap",
                                              "capValue"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["SESSIONS_EXHAUSTED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["sessionsPerWeek"]
                                          },
                                          "weekStart": {
                                            "type": "string",
                                            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                            "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                            "example": "2026-09-14"
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsRequested": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              },
                                              "sessionsPlacedBefore": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "required": [
                                              "sessionsRequested",
                                              "sessionsPlacedBefore"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "weekStart",
                                          "evidence"
                                        ],
                                        "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["CADENCE_RELAXED"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["cadence"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "cadenceRelaxation": {
                                                "type": "string",
                                                "enum": [
                                                  "EXACT",
                                                  "INTERVAL_TIGHTENED",
                                                  "DAYS_ADDED",
                                                  "DAYS_SUBSTITUTED",
                                                  "ALL_WORKING_DAYS",
                                                  "DIRECT_FILL"
                                                ],
                                                "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                              },
                                              "requestedDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              },
                                              "actualDays": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "maximum": 6
                                                },
                                                "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                              }
                                            },
                                            "required": ["cadenceRelaxation"]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": [
                                              "SESSIONS_OUTSIDE_PREFERRED_TIMES"
                                            ]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["timeOfDay"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionIndexes": {
                                                "type": "array",
                                                "items": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                }
                                              },
                                              "localTimes": {
                                                "type": "array",
                                                "items": {
                                                  "type": "string"
                                                }
                                              }
                                            },
                                            "required": [
                                              "sessionIndexes",
                                              "localTimes"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["FIRST_SESSION_LATE"]
                                          },
                                          "component": {
                                            "type": "string",
                                            "enum": ["startDate"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "firstSessionDate": {
                                                "type": "string"
                                              },
                                              "windowStartDate": {
                                                "type": "string"
                                              },
                                              "dayOffset": {
                                                "type": "integer",
                                                "minimum": 0
                                              },
                                              "earlierSupplyExisted": {
                                                "type": "boolean",
                                                "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                              }
                                            },
                                            "required": [
                                              "firstSessionDate",
                                              "windowStartDate",
                                              "dayOffset",
                                              "earlierSupplyExisted"
                                            ]
                                          }
                                        },
                                        "required": [
                                          "code",
                                          "component",
                                          "evidence"
                                        ],
                                        "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                                      },
                                      {
                                        "type": "object",
                                        "properties": {
                                          "code": {
                                            "type": "string",
                                            "enum": ["PACKAGE_UNDERFILLED"]
                                          },
                                          "evidence": {
                                            "type": "object",
                                            "properties": {
                                              "sessionsRequested": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "exclusiveMinimum": true
                                              },
                                              "sessionsFilled": {
                                                "type": "integer",
                                                "minimum": 0
                                              }
                                            },
                                            "required": [
                                              "sessionsRequested",
                                              "sessionsFilled"
                                            ]
                                          }
                                        },
                                        "required": ["code", "evidence"],
                                        "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                                      }
                                    ]
                                  },
                                  "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                                },
                                "advice": {
                                  "type": "object",
                                  "properties": {
                                    "code": {
                                      "type": "string",
                                      "enum": ["LATER_START_IMPROVES_CADENCE"]
                                    },
                                    "earliestSustainedWeek": {
                                      "type": "string",
                                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                      "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                                      "example": "2026-09-14"
                                    }
                                  },
                                  "required": ["code", "earliestSustainedWeek"],
                                  "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                                },
                                "matchScore": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 1,
                                  "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                                  "example": 1
                                },
                                "matchComponents": {
                                  "type": "object",
                                  "properties": {
                                    "startDate": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                                    },
                                    "timeOfDay": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                                    },
                                    "daysOfWeek": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                                    },
                                    "sessionsPerWeek": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                                    },
                                    "cadence": {
                                      "type": "number",
                                      "minimum": 0,
                                      "maximum": 1,
                                      "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                                    }
                                  },
                                  "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                                }
                              },
                              "required": [
                                "slateId",
                                "supplierId",
                                "completeness",
                                "sessionsRequested",
                                "sessionsFilled",
                                "startTimeConsistencyPercent",
                                "totalTravelTimeMins",
                                "slots",
                                "matchNotes",
                                "matchScore"
                              ]
                            },
                            "cadenceAlternatives": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "slateId": {
                                    "type": "string",
                                    "description": "Pass this to POST .../package-bookings to book the whole plan.",
                                    "example": "slate_01kx16ejsqffc9rbgdcc591w2p"
                                  },
                                  "supplierId": {
                                    "type": "string"
                                  },
                                  "completeness": {
                                    "type": "string",
                                    "enum": ["COMPLETE", "PARTIAL"]
                                  },
                                  "sessionsRequested": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "exclusiveMinimum": true,
                                    "description": "How many sessions were requested (the package's creditCount)."
                                  },
                                  "sessionsFilled": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "How many of the requested sessions the plan could fill."
                                  },
                                  "startTimeConsistencyPercent": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 100
                                  },
                                  "totalTravelTimeMins": {
                                    "type": "number",
                                    "minimum": 0
                                  },
                                  "slots": {
                                    "type": "array",
                                    "items": {
                                      "type": "object",
                                      "properties": {
                                        "slotId": {
                                          "type": "string",
                                          "description": "Id of one session; pass a subset of these as slotIds to cherry-pick."
                                        },
                                        "sessionIndex": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true,
                                          "description": "1-based index of this session within the slate."
                                        },
                                        "supplierId": {
                                          "type": "string"
                                        },
                                        "serviceId": {
                                          "type": "string"
                                        },
                                        "offeringId": {
                                          "type": "string"
                                        },
                                        "bookingStartUtc": {
                                          "type": "string",
                                          "format": "date-time"
                                        },
                                        "bookingEndUtc": {
                                          "type": "string",
                                          "format": "date-time"
                                        },
                                        "bookingTz": {
                                          "type": "string"
                                        },
                                        "locationType": {
                                          "type": "string",
                                          "enum": [
                                            "PHYSICAL",
                                            "VIRTUAL",
                                            "TRAVEL_ZONE"
                                          ]
                                        },
                                        "locationId": {
                                          "type": "string",
                                          "nullable": true
                                        },
                                        "latitude": {
                                          "type": "number",
                                          "nullable": true
                                        },
                                        "longitude": {
                                          "type": "number",
                                          "nullable": true
                                        },
                                        "address": {
                                          "$ref": "#/components/schemas/Address"
                                        },
                                        "travelTimeMins": {
                                          "type": "number",
                                          "nullable": true,
                                          "minimum": 0
                                        },
                                        "capacity": {
                                          "type": "integer",
                                          "minimum": 0,
                                          "exclusiveMinimum": true
                                        },
                                        "reservationStatus": {
                                          "type": "string",
                                          "enum": [
                                            "FREE",
                                            "HELD",
                                            "CONVERTED",
                                            "RELEASED"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "slotId",
                                        "sessionIndex",
                                        "supplierId",
                                        "serviceId",
                                        "offeringId",
                                        "bookingStartUtc",
                                        "bookingEndUtc",
                                        "bookingTz",
                                        "locationType",
                                        "locationId",
                                        "latitude",
                                        "longitude",
                                        "address",
                                        "travelTimeMins",
                                        "capacity",
                                        "reservationStatus"
                                      ]
                                    }
                                  },
                                  "position": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "0-based rank of this slate across the whole response: primarySlate is 0, then alternates, then partial, then cadenceAlternatives, in the order returned. Absent on slates built before this field existed.",
                                    "example": 0
                                  },
                                  "cadenceRrule": {
                                    "type": "string",
                                    "nullable": true,
                                    "description": "The recurrence rule this slate’s sessions actually follow. Null for a direct fill (no recurrence rule at all). This is PROVENANCE — it records how the slate was generated and is NOT re-validated if a slot is later rescheduled.",
                                    "example": "FREQ=WEEKLY;BYDAY=MO,FR;COUNT=8"
                                  },
                                  "matchesRequestedCadence": {
                                    "type": "boolean",
                                    "description": "True when cadenceRrule is the rrule you asked for.",
                                    "example": false
                                  },
                                  "cadenceRelaxation": {
                                    "type": "string",
                                    "enum": [
                                      "EXACT",
                                      "INTERVAL_TIGHTENED",
                                      "DAYS_ADDED",
                                      "DAYS_SUBSTITUTED",
                                      "ALL_WORKING_DAYS",
                                      "DIRECT_FILL"
                                    ],
                                    "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                  },
                                  "cadenceDistance": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "description": "How far this slate’s cadence is from the one you requested — 0 is an exact match, lower is closer. When the request carries no sessionsPerWeek target, cadenceAlternatives is sorted by this value alone, closest first. When it does carry a target, alternatives are ranked by closeness to that target first, and this distance only breaks ties between cadences equally close to it.",
                                    "example": 2
                                  },
                                  "cadenceSummary": {
                                    "type": "object",
                                    "properties": {
                                      "requested": {
                                        "type": "integer",
                                        "nullable": true,
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "The frequency you asked for, in sessions per week. Your sessionsPerWeek target when you sent one; otherwise counted from the weekdays your own rrule named (FREQ=WEEKLY;BYDAY=MO,TU,WE,TH is 4). Null when you expressed no frequency at all, and also null when the rrule was not yours — a non-weekly FREQ, an INTERVAL other than 1, a weekly rule naming no weekdays at all, or a rule this API synthesised for you — because reporting a frequency you never asked for is worse than reporting none.",
                                        "example": 4
                                      },
                                      "peak": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "exclusiveMinimum": true,
                                        "description": "The most sessions this slate holds in any single week — the number to render as \"4×/week\". This is the honest answer to \"how often is this plan\", and it is deliberately NOT an average: when a supplier has a break mid-plan, an average reports a rate that none of the weeks actually run at (nine sessions split 1/0/4/4 averages 2.25, while the plan plainly runs at four a week wherever it runs).",
                                        "example": 4
                                      },
                                      "average": {
                                        "type": "number",
                                        "minimum": 0,
                                        "description": "Sessions divided by the number of weeks in byWeek, to 2 decimal places — so you can verify it against byWeek yourself. Weeks are counted across the PLAN’s span (first session’s week through last session’s week, gap weeks included), never across your whole lookAhead window, so a wide window does not dilute it. Prefer peak for client-facing copy; this number is for capacity and reporting.",
                                        "example": 2.25
                                      },
                                      "byWeek": {
                                        "type": "array",
                                        "items": {
                                          "type": "object",
                                          "properties": {
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) that starts this week.",
                                              "example": "2026-09-14"
                                            },
                                            "sessions": {
                                              "type": "integer",
                                              "minimum": 0,
                                              "description": "Sessions this slate holds in this week. 0 is a real value and the most informative entry in the array — it is a week inside the plan where the supplier had nothing.",
                                              "example": 0
                                            }
                                          },
                                          "required": ["weekStart", "sessions"]
                                        },
                                        "minItems": 1,
                                        "description": "Every Monday-anchored week from the first session’s week through the last session’s, ascending and contiguous, including weeks holding zero sessions. A zero week is how you show a client WHY the plan looks uneven — it is a week the supplier could not serve, not a gap in this data. Never empty: a slate with no sessions omits cadenceSummary entirely rather than publishing an empty array."
                                      }
                                    },
                                    "required": [
                                      "requested",
                                      "peak",
                                      "average",
                                      "byWeek"
                                    ],
                                    "description": "How often this slate actually runs, against the frequency you asked for. Present on every slate holding at least one session, on every request — absent only for a slate with no sessions, which has no cadence to describe. Render peak, not average: see peak’s description for why. IMPORTANT: the weeks here are Monday-anchored CALENDAR weeks, bucketed the same way as the maxSessionsPerWeek cap. matchComponents.sessionsPerWeek counts weeks differently — consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers. The two can therefore disagree, and both are right: peak can read 4 against a target of 4 while that component reads below 1, which is exactly what a supplier’s mid-plan break looks like."
                                  },
                                  "matchNotes": {
                                    "type": "array",
                                    "items": {
                                      "oneOf": [
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "SUPPLIER_UNAVAILABLE_WEEK"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "openingsInPool": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                  "example": 2
                                                },
                                                "supplierWorkdays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "The weekdays this supplier works, BEFORE your filters. Empty here — that is what makes this code distinct from WEEK_EXCLUDED_BY_FILTERS."
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "openingsInPool",
                                                "supplierWorkdays"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This supplier works NONE of the weekdays that could have served this week — supplierWorkdays is empty. Read that as a fact about their working PATTERN, not as a check of this particular calendar week: we do not expand schedule recurrence to ask whether this specific week was covered, so a supplier who works Mondays but was booked or blocked on this week’s Monday reports a different code, not this one. Sessions moved to neighbouring weeks. This is the case where \"wait a week\" is the right thing to tell a client; see the advice field, which may name the week supply resumes."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "WEEK_EXCLUDED_BY_FILTERS"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "filter": {
                                                  "type": "string",
                                                  "enum": [
                                                    "daysOfWeek",
                                                    "excludeDates"
                                                  ]
                                                },
                                                "supplierWorkdays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                },
                                                "requestedDays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                },
                                                "excludedDates": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "string"
                                                  }
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "filter",
                                                "supplierWorkdays"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "Your own daysOfWeek or excludeDates cut this week’s candidate days to fewer than you asked for, and the supplier’s working PATTERN covers enough days in this week to have met your target without that filter. Read supplierWorkdays exactly as SUPPLIER_UNAVAILABLE_WEEK asks you to read it: a fact about which weekdays this supplier works AT ALL, not a check of this particular calendar week. We do not expand schedule recurrence to ask whether those pattern days were actually free, so a Mon–Fri supplier already booked solid across this week reports this code too. Loosening the filter named in evidence.filter is therefore the LIKELY fix, not a guaranteed one — but it is the best move the data supports, because a week the supplier’s pattern could never have met is reported as WEEK_SUPPLY_INSUFFICIENT instead and is not your filter’s fault. The one exception is a daysOfWeek that names no day this supplier works at all, which leaves zero candidate days whatever your target. The opposite call to action from SUPPLIER_UNAVAILABLE_WEEK: waiting is not what this code points at, loosening your filter is."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "WEEK_SUPPLY_INSUFFICIENT"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "openingsInPool": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Days in this week that held at least one open slot for this supplier, AFTER your own daysOfWeek and excludeDates filters were applied. It counts PLACEABLE DAYS, not raw slots: a plan places at most one session per local date, so a day offering five start times counts once here. That is what makes this number directly comparable to sessionsTargeted.",
                                                  "example": 2
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "openingsInPool"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This week holds fewer sessions than you asked for and none of the more specific reasons could be ESTABLISHED. This is the RESIDUAL code, not a positive finding about supply: it says only that this supplier’s working PATTERN is not empty — a fact about which weekdays they work AT ALL, not a check of this calendar week, which is what rules out SUPPLIER_UNAVAILABLE_WEEK — and that we could not attribute the shortfall to one of your filters or to a cap you sent. It does NOT say a filter or a cap played no part. Two cases land here with one of them genuinely involved: a filter that removed a candidate day from a week the supplier’s own pattern days could never have met anyway (attribution is withheld because loosening the filter provably could not have reached your target), and a cap that applied to a week whose openings were already below your target (WEEK_CAPPED is reserved for weeks that had enough openings to make the cap the thing to raise). So compare sessionsPlaced and sessionsTargeted against openingsInPool to see what the constraint was, rather than assuming a cause. Below the target, openingsInPool says the placeable days were not there. At or above it, the days were there and the shortfall came from something other than supply — check the slate for CADENCE_RELAXED, which reports a cadence that could not use them and is then the better thing to tell a client. That pointer does not always land: CADENCE_RELAXED is emitted only when the cadence component scored below 1, and an AUTHORISED weekday substitution scores a perfect cadence, so a days-were-there week can carry no cadence note at all."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["WEEK_CAPPED"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsPlaced": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "description": "Sessions this slate placed in this week."
                                                },
                                                "sessionsTargeted": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true,
                                                  "description": "Sessions you asked for in a week — your sessionsPerWeek target."
                                                },
                                                "cap": {
                                                  "type": "string",
                                                  "enum": [
                                                    "maxSessionsPerWeek",
                                                    "minGapDays"
                                                  ]
                                                },
                                                "capValue": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                }
                                              },
                                              "required": [
                                                "sessionsPlaced",
                                                "sessionsTargeted",
                                                "cap",
                                                "capValue"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This week held at least sessionsTargeted placeable days, and a cap YOU sent — maxSessionsPerWeek or minGapDays — puts a ceiling on the week that is BELOW your target, so your target was unreachable in this week whatever the supplier had free. Raising the cap named in evidence.cap is therefore NECESSARY if you want this week to meet your target. Whether it is SUFFICIENT is not something this note can tell you: the code fires on that ceiling EXISTING, not on the plan having filled up to it, so sessionsPlaced can sit below the ceiling — when it does, all that is established is that the plan did not fill the week even to the ceiling. Do not read that either way; nothing here says what else was or was not in the way. (capValue is the number you sent. For minGapDays that is the gap, not the weekly ceiling it implies: a gap of 3 admits at most three sessions in a seven-day week.)"
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["SESSIONS_EXHAUSTED"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["sessionsPerWeek"]
                                            },
                                            "weekStart": {
                                              "type": "string",
                                              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                              "description": "The Monday (YYYY-MM-DD, local) starting the week this note is about.",
                                              "example": "2026-09-14"
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsRequested": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                },
                                                "sessionsPlacedBefore": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                }
                                              },
                                              "required": [
                                                "sessionsRequested",
                                                "sessionsPlacedBefore"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "weekStart",
                                            "evidence"
                                          ],
                                          "description": "This week is short only because the package ran out of sessions — nine sessions at four a week leaves the last week holding one. NOTHING went wrong here, and no supply code is emitted for this week: do not apologise for it in your copy."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["CADENCE_RELAXED"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["cadence"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "cadenceRelaxation": {
                                                  "type": "string",
                                                  "enum": [
                                                    "EXACT",
                                                    "INTERVAL_TIGHTENED",
                                                    "DAYS_ADDED",
                                                    "DAYS_SUBSTITUTED",
                                                    "ALL_WORKING_DAYS",
                                                    "DIRECT_FILL"
                                                  ],
                                                  "description": "How this slate’s cadence was derived from the one you requested. EXACT matches the request. INTERVAL_TIGHTENED keeps the requested weekdays but runs more often. DAYS_ADDED keeps every requested weekday and adds more. DAYS_SUBSTITUTED replaces them with weekdays the supplier actually works. ALL_WORKING_DAYS uses every weekday the supplier works. DIRECT_FILL follows no recurrence rule at all — it is the supplier’s real openings, one session per day."
                                                },
                                                "requestedDays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                },
                                                "actualDays": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "maximum": 6
                                                  },
                                                  "description": "Weekdays as 0 = Sunday … 6 = Saturday."
                                                }
                                              },
                                              "required": ["cadenceRelaxation"]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "evidence"
                                          ],
                                          "description": "This slate does not run at the rrule you sent. cadenceRelaxation says how it was derived; requestedDays and actualDays let you show the swap."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": [
                                                "SESSIONS_OUTSIDE_PREFERRED_TIMES"
                                              ]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["timeOfDay"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionIndexes": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "integer",
                                                    "minimum": 0,
                                                    "exclusiveMinimum": true
                                                  }
                                                },
                                                "localTimes": {
                                                  "type": "array",
                                                  "items": {
                                                    "type": "string"
                                                  }
                                                }
                                              },
                                              "required": [
                                                "sessionIndexes",
                                                "localTimes"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "evidence"
                                          ],
                                          "description": "These sessions (1-based, matching sessionIndex on each slot) fall outside every preferredTimes window you sent. localTimes is aligned to sessionIndexes. BOTH ARRAYS CAN BE EMPTY: when no session of this slate lands inside your requested window at all, the criterion definitely missed and this note is emitted, but there is no in-window session to name — so treat empty arrays as \"outside your preferred times, with nothing to point at\", not as an error."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["FIRST_SESSION_LATE"]
                                            },
                                            "component": {
                                              "type": "string",
                                              "enum": ["startDate"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "firstSessionDate": {
                                                  "type": "string"
                                                },
                                                "windowStartDate": {
                                                  "type": "string"
                                                },
                                                "dayOffset": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                },
                                                "earlierSupplyExisted": {
                                                  "type": "boolean",
                                                  "description": "TRUE when the supplier had open slots before the first session but the cadence could not use them — so the late start is the rrule, not a lack of availability."
                                                }
                                              },
                                              "required": [
                                                "firstSessionDate",
                                                "windowStartDate",
                                                "dayOffset",
                                                "earlierSupplyExisted"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "component",
                                            "evidence"
                                          ],
                                          "description": "The plan’s first session is evidence.dayOffset whole local days after your window start — that offset is the fact this code reports, and it is always at least one day. Whether the plan started later than it HAD to is a separate question, answered by evidence.earlierSupplyExisted: TRUE means the supplier had open days before that first session and the cadence could not use them, so an earlier start really was there to be had and loosening the cadence is the fix. FALSE means we found no opening earlier in your window, so this is simply where the supplier’s supply began — nothing was given up, and copy saying otherwise would be wrong."
                                        },
                                        {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "enum": ["PACKAGE_UNDERFILLED"]
                                            },
                                            "evidence": {
                                              "type": "object",
                                              "properties": {
                                                "sessionsRequested": {
                                                  "type": "integer",
                                                  "minimum": 0,
                                                  "exclusiveMinimum": true
                                                },
                                                "sessionsFilled": {
                                                  "type": "integer",
                                                  "minimum": 0
                                                }
                                              },
                                              "required": [
                                                "sessionsRequested",
                                                "sessionsFilled"
                                              ]
                                            }
                                          },
                                          "required": ["code", "evidence"],
                                          "description": "Fewer sessions than the package holds credits for. This slate is PARTIAL — completeness says so too, and it is not a matchScore component, so a PARTIAL slate can still score 1."
                                        }
                                      ]
                                    },
                                    "description": "Why this slate departs from what you asked for — one entry per reason, each a code plus structured evidence, and no English so you can write your own copy. ALWAYS PRESENT: empty means nothing departed, so you can read .length without a null check. NOT gated on matchScore — a DIRECT_FILL slate and a PARTIAL slate can both score 1 and still carry notes, and those are exactly the slates worth captioning. Read matchComponents for WHICH criterion missed and these for WHY. IMPORTANT: the two count weeks differently, so that pairing is a guide, not a join key. The week-level codes here bucket Monday-anchored CALENDAR weeks — the same bucketing as cadenceSummary.byWeek and the maxSessionsPerWeek cap — while matchComponents.sessionsPerWeek buckets consecutive 7-day blocks from your window’s start. The two can therefore disagree, and both are right: a note can name a short week for a criterion that component scores as met, and the reverse. Join a note to cadenceSummary.byWeek on weekStart, which does share this bucketing; treat matchComponents as the per-criterion score, not as a per-week one."
                                  },
                                  "advice": {
                                    "type": "object",
                                    "properties": {
                                      "code": {
                                        "type": "string",
                                        "enum": ["LATER_START_IMPROVES_CADENCE"]
                                      },
                                      "earliestSustainedWeek": {
                                        "type": "string",
                                        "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                                        "description": "The earliest Monday from which supply alone could sustain your requested frequency. Always STRICTLY LATER than the first week matchNotes reported as short — this field means \"start later\", so it never names a week the notes just condemned.",
                                        "example": "2026-09-14"
                                      }
                                    },
                                    "required": [
                                      "code",
                                      "earliestSustainedWeek"
                                    ],
                                    "description": "An advisory hint about a later start, present only when one applies. Read AdviceSchema’s own description first: it reports that SUPPLY exists, not that a slate was built."
                                  },
                                  "matchScore": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1,
                                    "description": "How well this slate matches the requested schedule preferences, from 0 to 1 — the mean of the components present in matchComponents. When the caller expressed no schedule preferences it is 1 and matchComponents is empty, so a caller distinguishes \"perfect match\" from \"nothing asked\" by reading matchComponents, not this score. Compare the availabilityMatch property on /availability/suppliers, which is ABSENT entirely for the \"nothing asked\" case rather than present with a null score — matchScore cannot go absent, because it is a required property on this shipped contract and dropping it would break the generated SDK types. The results are already ranked: primarySlate is the best-matching COMPLETE slate and alternates follow it in descending order, with completeness always outranking this score, so a COMPLETE slate never sits below a PARTIAL one that scored higher. (cadenceAlternatives is ordered separately, closest-cadence first.) Do NOT re-sort the slates you receive by matchScore: the order carries preferences this number cannot. matchComponents.sessionsPerWeek scores a week holding AT LEAST the sessionsPerWeek you asked for, so against a target of 2 a slate delivering three sessions a week scores identically to one delivering two, and only the order distinguishes them. Re-sorting silently discards that. This score is also not a cadence: read cadenceSummary.peak for how often the plan actually runs, and cadenceSummary.byWeek for which weeks are short and why the two numbers can differ.",
                                    "example": 1
                                  },
                                  "matchComponents": {
                                    "type": "object",
                                    "properties": {
                                      "startDate": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "How soon this slate’s first session lands in the requested window — 1 when session one lands as early as possible in the window, lower the later it lands."
                                      },
                                      "timeOfDay": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "Fraction of this slate’s sessions that fall at a preferred time of day."
                                      },
                                      "daysOfWeek": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "Fraction of this slate’s sessions that fall on a requested weekday."
                                      },
                                      "sessionsPerWeek": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "Fraction of the window’s whole weeks in which this slate holds at least the requested number of sessions — a match ratio in [0, 1], not a count. For counts see cadenceSummary, whose peak is the number to render as \"4×/week\". THE TWO COUNT WEEKS DIFFERENTLY, deliberately: this ratio buckets consecutive 7-day blocks from your window’s start, so it stays comparable with availabilityMatch on /availability/suppliers, while cadenceSummary uses Monday-anchored calendar weeks so its weekStart dates are real Mondays and agree with the maxSessionsPerWeek cap. Expect them to disagree on a plan spanning a supplier’s break — cadenceSummary.peak can read 4 against a target of 4 while this ratio reads below 1, and both are correct for what they measure. AT LEAST is literal: against a target of 2, a week holding 3 sessions counts exactly as a week holding 2, so a denser slate never scores worse here. The preference for two over three is expressed only in the ORDER slates come back in — see matchScore."
                                      },
                                      "cadence": {
                                        "type": "number",
                                        "minimum": 0,
                                        "maximum": 1,
                                        "description": "1 when this slate runs at the cadence you requested, and also 1 when the only departure from it was a weekday substitution you authorised — cadenceRelaxation of DAYS_SUBSTITUTED or ALL_WORKING_DAYS, with allowWeekdaySubstitution true and no daysOfWeek sent. 0 when the cadence changed in a way you did not authorise, which includes every change to how OFTEN sessions occur (INTERVAL_TIGHTENED, DAYS_ADDED): allowing weekday substitution does not authorise a frequency change, and sending an explicit daysOfWeek withdraws the authorisation, because naming your weekdays says the weekdays are the point. Absent rather than 0 on a slate that follows no cadence at all — a DIRECT_FILL slate and a PARTIAL slate are both greedy fills that never consult your rrule, so how well they match a requested cadence is unanswerable rather than zero, and matchScore is the mean of the components that remain. Absent too when you sent no rrule."
                                      }
                                    },
                                    "description": "How well this slate matches the requested schedule preferences, broken down by criterion. Only the criteria the caller supplied are scored here — matchScore is the mean of exactly these. Present but empty when the caller expressed no schedule preferences at all; see matchScore’s description for why that case is 1 here rather than an absent availabilityMatch. Also absent on a slate whose matchScore carries no recorded per-criterion breakdown. These names mirror the components object inside availabilityMatch on /availability/suppliers but NOT their meaning: there each ratio is measured over the supplier’s open availability, while here every ratio is measured over this slate’s own sessions — a slate of eight Friday sessions scores 1 on daysOfWeek because all eight sessions are Fridays, independent of what a supplier-level daysOfWeek would report."
                                  }
                                },
                                "required": [
                                  "slateId",
                                  "supplierId",
                                  "completeness",
                                  "sessionsRequested",
                                  "sessionsFilled",
                                  "startTimeConsistencyPercent",
                                  "totalTravelTimeMins",
                                  "slots",
                                  "matchNotes",
                                  "matchScore"
                                ]
                              },
                              "default": [],
                              "description": "Complete N-session slates that fit the supplier’s real availability but do NOT follow the rrule you asked for — e.g. you requested weekly Fridays, no supplier has eight free Fridays, so this carries a Mon+Fri plan instead. Sorted by cadenceDistance, closest first, when the request carries no sessionsPerWeek target; when it does, ranked by closeness to that target first and cadenceDistance only as the tiebreaker. Always empty unless the request set cadenceFlexibility or guaranteeSlate. Each entry’s slateId is bookable exactly like primarySlate’s."
                            },
                            "requestedCadence": {
                              "type": "string",
                              "nullable": true,
                              "description": "The rrule this request asked for, echoed back so you can diff it against each slate’s cadenceRrule.",
                              "example": "FREQ=WEEKLY;BYDAY=FR;COUNT=8"
                            }
                          },
                          "required": [
                            "status",
                            "reason",
                            "suggestionRequestId",
                            "resolvableUntil",
                            "primarySlate",
                            "alternates",
                            "partial"
                          ]
                        }
                      },
                      "required": [
                        "code",
                        "message",
                        "statusCode",
                        "requestId",
                        "freshSuggestions"
                      ]
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Slate too large, best-effort not enabled, a PHYSICAL location without coordinates (UNPROCESSABLE_ENTITY), or the credit’s offering is no longer ACTIVE (NOT_SELLABLE): a service retired since does not refuse credits already bought",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/clients/me/addresses": {
      "post": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Clients"],
        "summary": "Add a service address to the caller's client profile",
        "description": "Saves a service address for the signed-in client. Requires both the API key and the client user JWT, and the caller must already be onboarded — POST /clients/me first, or this is a 404.\n\nThe address id is derived from the address content, so this is an upsert, not an append: posting the same address twice returns the same id and leaves one record, while changing so much as a street number creates a second. The first address a client saves silently becomes their default; later ones do not displace it, so use the default route to move it rather than expecting the newest to win.\n\nThis matters beyond delivery: the default address is the last-resort source of the pricing region for an order that pins no reservation, location or explicit address. A client with no saved address resolves to no region at all and is priced at the offering's DEFAULT rule, in the DEFAULT rule's currency — which is how a client abroad ends up quoted in the wrong currency and rejected. Save the address before the first order.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Address"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Address added",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ClientProfile"
                    },
                    "address": {
                      "type": "object",
                      "properties": {
                        "addressOneLine": {
                          "type": "string",
                          "minLength": 1,
                          "description": "The whole address on one line, as a person would write it.",
                          "example": "10 Main St, Toronto, ON M5V 1A1, Canada"
                        },
                        "streetNumber": {
                          "type": "string",
                          "minLength": 1,
                          "description": "The street number.",
                          "example": "10"
                        },
                        "streetName": {
                          "type": "string",
                          "minLength": 1,
                          "description": "The street name.",
                          "example": "Main St"
                        },
                        "city": {
                          "type": "string",
                          "minLength": 1,
                          "description": "The city or town.",
                          "example": "Toronto"
                        },
                        "state": {
                          "type": "string",
                          "minLength": 1,
                          "description": "The state, province or region; an ISO 3166-2 code when one matches.",
                          "example": "ON"
                        },
                        "country": {
                          "type": "string",
                          "minLength": 1,
                          "description": "The country; ISO 3166-1 alpha-2, alpha-3 or the English name.",
                          "example": "CA"
                        },
                        "zipCode": {
                          "type": "string",
                          "minLength": 1,
                          "description": "The postal or ZIP code, in any national format.",
                          "example": "M5V 1A1"
                        },
                        "unitNumber": {
                          "type": "string",
                          "nullable": true,
                          "description": "The unit, suite or apartment, if any.",
                          "example": "4B"
                        },
                        "id": {
                          "type": "string"
                        },
                        "source": {
                          "type": "string",
                          "enum": ["BOOKING", "MANUAL"]
                        }
                      },
                      "required": [
                        "addressOneLine",
                        "streetNumber",
                        "streetName",
                        "city",
                        "state",
                        "country",
                        "zipCode",
                        "id"
                      ]
                    }
                  },
                  "required": ["data", "address"]
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "No access to project or unregistered user, or the signed-in user is not an ACTIVE member of it holding the route’s permission (FORBIDDEN), or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "No client profile for this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/clients/me/addresses/{addressId}": {
      "patch": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Clients"],
        "summary": "Update one of the caller's addresses",
        "description": "Address ids are derived from the address content, so a successful update MAY change the id — always re-read ids from the returned profile.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "One of the client's saved addresses. The id is a fingerprint of the address fields, so the same physical address always yields the same id.",
              "example": "addr_9f2c1ab77d0e4b3c85a16e2f"
            },
            "required": true,
            "description": "One of the client's saved addresses. The id is a fingerprint of the address fields, so the same physical address always yields the same id.",
            "name": "addressId",
            "in": "path"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "addressOneLine": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The whole address on one line, as a person would write it.",
                    "example": "10 Main St, Toronto, ON M5V 1A1, Canada"
                  },
                  "streetNumber": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The street number.",
                    "example": "10"
                  },
                  "streetName": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The street name.",
                    "example": "Main St"
                  },
                  "city": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The city or town.",
                    "example": "Toronto"
                  },
                  "state": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The state, province or region; an ISO 3166-2 code when one matches.",
                    "example": "ON"
                  },
                  "country": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The country; ISO 3166-1 alpha-2, alpha-3 or the English name.",
                    "example": "CA"
                  },
                  "zipCode": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The postal or ZIP code, in any national format.",
                    "example": "M5V 1A1"
                  },
                  "unitNumber": {
                    "type": "string",
                    "nullable": true,
                    "description": "The unit, suite or apartment, if any.",
                    "example": "4B"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Address updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ClientProfile"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Unresolvable country on the merged address. `state` is not rejected here — a value ISO 3166-2 does not index for the country is stored as sent, and only errors at pricing time if the offering prices by subdivision there.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "No access to project or unregistered user, or the signed-in user is not an ACTIVE member of it holding the route’s permission (FORBIDDEN), or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Client or address not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "delete": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Clients"],
        "summary": "Remove one of the caller's addresses",
        "description": "Deletes one saved address and returns the client profile as it now stands. The removal is permanent — there is no soft delete — but bookings already placed against that address are unaffected, since they captured it at the time.\n\nDeleting the default is allowed and quietly reassigns it: the oldest remaining address is promoted, and `defaultAddressId` is dropped entirely when nothing is left. So a client can silently end up defaulting to an address you did not choose, and a client with no addresses left has no pricing region to fall back on — read `defaultAddressId` off the returned profile rather than assuming it survived. An unknown `addressId` is a 404.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "One of the client's saved addresses. The id is a fingerprint of the address fields, so the same physical address always yields the same id.",
              "example": "addr_9f2c1ab77d0e4b3c85a16e2f"
            },
            "required": true,
            "description": "One of the client's saved addresses. The id is a fingerprint of the address fields, so the same physical address always yields the same id.",
            "name": "addressId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Address removed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ClientProfile"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "No access to project or unregistered user, or the signed-in user is not an ACTIVE member of it holding the route’s permission (FORBIDDEN), or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Client or address not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/clients/me/addresses/{addressId}/default": {
      "put": {
        "security": [
          {
            "ApiKeyAuth": [],
            "EndUserBearer": []
          }
        ],
        "tags": ["Clients"],
        "summary": "Set the caller's default address",
        "description": "Points the client's `defaultAddressId` at an address they have already saved; it does not create one, so add the address first or this is a 404. Returns the whole updated profile.\n\nWorth doing deliberately rather than leaving to chance, because the default is not just a delivery preference: it is the fallback the pricing engine uses to pick a region when an order names no reservation, location or address of its own. Moving the default across a country or subdivision border therefore changes what that client is quoted for the same offering. It does not touch orders already placed, which snapshot their region at creation, so repointing it fixes future orders only.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "One of the client's saved addresses. The id is a fingerprint of the address fields, so the same physical address always yields the same id.",
              "example": "addr_9f2c1ab77d0e4b3c85a16e2f"
            },
            "required": true,
            "description": "One of the client's saved addresses. The id is a fingerprint of the address fields, so the same physical address always yields the same id.",
            "name": "addressId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Default set",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ClientProfile"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid user token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "No access to project or unregistered user, or the signed-in user is not an ACTIVE member of it holding the route’s permission (FORBIDDEN), or X-MB-Acting-Role names a role they do not hold (ACTING_ROLE_NOT_HELD)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Client or address not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/services": {
      "post": {
        "tags": ["Services"],
        "summary": "Create a new service",
        "description": "A service is the umbrella record; the sellable variants hang off it as offerings, and only an offering carries price and duration. So a service on its own sells nothing — create at least one offering before publishing. The new service is always DRAFT regardless of what you send; publish it with POST /services/{serviceId}/status. Names must be unique within the project per language, compared with case, accents and punctuation normalised away, so a near-duplicate is a 409 rather than a second service. `businessModels` and `attributes` can be supplied inline here instead of as follow-up calls. `bufferBeforeStartMinutes` (0-120, default 0) is spacing before the service starts, for suggestions and checks only. `newCategory` is written in a separate transaction BEFORE the service, and is not rolled back if the service write then fails — after any error here, retry with `categoryId` pointing at the category that was already created, not `newCategory` again.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Service data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "description": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    },
                    "default": {}
                  },
                  "primaryLanguage": {
                    "type": "string",
                    "minLength": 1
                  },
                  "categoryId": {
                    "type": "string"
                  },
                  "newCategory": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "string"
                        }
                      },
                      "primaryLanguage": {
                        "type": "string",
                        "minLength": 1
                      }
                    },
                    "required": ["name", "primaryLanguage"]
                  },
                  "taxSettings": {
                    "type": "object",
                    "properties": {
                      "taxable": {
                        "type": "boolean"
                      },
                      "taxPercentage": {
                        "type": "number",
                        "minimum": 0
                      }
                    },
                    "default": {
                      "taxable": false
                    },
                    "required": ["taxable"]
                  },
                  "participantSettings": {
                    "$ref": "#/components/schemas/ParticipantSettings"
                  },
                  "bufferBeforeStartMinutes": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 120,
                    "default": 0,
                    "description": "Minutes a supplier needs free before this service starts. Used for suggestions and checks only, never as busy time.",
                    "example": 10
                  },
                  "businessModels": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "SINGLE_BOOKING",
                            "PACKAGE",
                            "SCHEDULED_PACKAGE",
                            "SCHEDULED_SUBSCRIPTION",
                            "FLEXIBLE_SUBSCRIPTION"
                          ],
                          "description": "How the service is sold. SINGLE_BOOKING is one booking at a time; PACKAGE sells prepaid credits drawn down by later bookings; the SCHEDULED_* and FLEXIBLE_* variants add recurrence and subscription billing. This drives which order item skuType applies."
                        },
                        "paymentOptions": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": [
                              "PAY_WHILE_BOOKING",
                              "PAY_AFTER_SERVICE_DELIVERED",
                              "NO_PAYMENT",
                              "PAY_FULL_PRICE_WHILE_PURCHASING",
                              "PAY_BEGINNING_OF_MONTH",
                              "PAY_END_OF_MONTH"
                            ]
                          },
                          "minItems": 1
                        },
                        "fees": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "feeId": {
                                "type": "string",
                                "minLength": 1,
                                "description": "Stable identifier for this fee, unique within the business model.",
                                "example": "fee_booking"
                              },
                              "name": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                },
                                "description": "Buyer-facing label, rendered as its own line on the order summary.",
                                "example": {
                                  "en": "Booking fee"
                                }
                              },
                              "calculation": {
                                "type": "string",
                                "enum": ["FLAT", "PERCENT"],
                                "description": "How a service fee is calculated. FLAT charges a fixed amount; PERCENT charges a percentage of the pre-tax total of the lines the fee governs.",
                                "example": "FLAT"
                              },
                              "amount": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "FLAT fees only. Integer minor units, charged in whatever currency the order is placed in — 2500 is CA$25.00 on a CAD order and US$25.00 on a USD one. Use a PERCENT fee if you need it to scale.",
                                "example": 2500
                              },
                              "percentage": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 100,
                                "description": "PERCENT fees only. Applied to the pre-tax total of this business model's lines on the order.",
                                "example": 5
                              },
                              "taxable": {
                                "type": "boolean",
                                "default": false,
                                "description": "When true, the fee is taxed at the rate of the order lines it is charged alongside (sessions or packages sold under this business model) that are taxed at a positive rate. Lines that are not taxable or taxed at 0% lend no rate; if none of the lines is taxed, the fee is not taxed either.",
                                "example": false
                              }
                            },
                            "required": ["feeId", "name", "calculation"]
                          },
                          "maxItems": 20,
                          "default": [],
                          "description": "Service fees — additional charges attached to this business model, applied to any order line sold under it. Each fee applies once per order regardless of how many lines it governs, and appears as its own entry on the order summary rather than being folded into tax.",
                          "example": [
                            {
                              "feeId": "fee_booking",
                              "name": {
                                "en": "Booking fee"
                              },
                              "calculation": "FLAT",
                              "amount": 2500,
                              "taxable": false
                            },
                            {
                              "feeId": "fee_admin",
                              "name": {
                                "en": "Admin fee"
                              },
                              "calculation": "PERCENT",
                              "percentage": 5,
                              "taxable": true
                            }
                          ]
                        },
                        "config": {
                          "type": "object",
                          "properties": {},
                          "default": {},
                          "additionalProperties": {
                            "nullable": true
                          }
                        }
                      },
                      "required": ["type", "paymentOptions"]
                    },
                    "default": []
                  },
                  "attributes": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "attributeType": {
                          "type": "string",
                          "enum": ["STRING", "NUMBER", "ENUM"],
                          "description": "Value type of a service attribute. ENUM attributes carry an allowed-values list."
                        },
                        "enumValues": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "valueId": {
                                "type": "string",
                                "minLength": 1
                              },
                              "label": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              }
                            },
                            "required": ["valueId", "label"]
                          }
                        },
                        "sortOrder": {
                          "type": "integer",
                          "minimum": 0,
                          "default": 0
                        }
                      },
                      "required": ["name", "attributeType"]
                    },
                    "default": []
                  }
                },
                "required": ["name", "primaryLanguage"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Service created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "entityType": {
                          "type": "string",
                          "enum": ["SERVICE"]
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "serviceId": {
                          "type": "string"
                        },
                        "categoryId": {
                          "type": "string"
                        },
                        "categorySnapshot": {
                          "type": "object",
                          "properties": {
                            "categoryId": {
                              "type": "string"
                            },
                            "primaryName": {
                              "type": "string"
                            },
                            "primaryNameNormalized": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "categoryId",
                            "primaryName",
                            "primaryNameNormalized"
                          ]
                        },
                        "name": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "description": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "primaryLanguage": {
                          "type": "string"
                        },
                        "primaryName": {
                          "type": "string"
                        },
                        "primaryNameNormalized": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": ["DRAFT", "LIVE", "INACTIVE"],
                          "description": "Lifecycle of the service. Only LIVE services are bookable; DRAFT is unpublished and INACTIVE is retired."
                        },
                        "taxSettings": {
                          "type": "object",
                          "properties": {
                            "taxable": {
                              "type": "boolean"
                            },
                            "taxPercentage": {
                              "type": "number",
                              "minimum": 0
                            }
                          },
                          "required": ["taxable"]
                        },
                        "participantSettings": {
                          "$ref": "#/components/schemas/ParticipantSettings"
                        },
                        "bufferBeforeStartMinutes": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 120
                        },
                        "counts": {
                          "type": "object",
                          "properties": {
                            "offerings": {
                              "type": "integer",
                              "minimum": 0
                            }
                          },
                          "required": ["offerings"]
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "entityType",
                        "projectId",
                        "serviceId",
                        "categoryId",
                        "categorySnapshot",
                        "name",
                        "description",
                        "primaryLanguage",
                        "primaryName",
                        "primaryNameNormalized",
                        "status",
                        "taxSettings",
                        "counts",
                        "deleted",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "Duplicate name",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": ["Services"],
        "summary": "List services for a project",
        "description": "The project catalogue, sorted by name within each status. Unlike most list endpoints this one is not paginated: a project holds few enough services to return in one response, so `nextCursor` is always null and there is no `limit`. All three statuses are included unless you filter — pass `status=LIVE` for anything client-facing, or DRAFT services that were never meant to be public will appear in your storefront. Soft-deleted services are never returned.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "enum": ["DRAFT", "LIVE", "INACTIVE"],
              "description": "Lifecycle of the service. Only LIVE services are bookable; DRAFT is unpublished and INACTIVE is retired."
            },
            "required": false,
            "description": "Lifecycle of the service. Only LIVE services are bookable; DRAFT is unpublished and INACTIVE is retired.",
            "name": "status",
            "in": "query"
          },
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "categoryId",
            "in": "query"
          },
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "search",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Services list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "entityType": {
                            "type": "string",
                            "enum": ["SERVICE"]
                          },
                          "projectId": {
                            "type": "string"
                          },
                          "serviceId": {
                            "type": "string"
                          },
                          "categoryId": {
                            "type": "string"
                          },
                          "categorySnapshot": {
                            "type": "object",
                            "properties": {
                              "categoryId": {
                                "type": "string"
                              },
                              "primaryName": {
                                "type": "string"
                              },
                              "primaryNameNormalized": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "categoryId",
                              "primaryName",
                              "primaryNameNormalized"
                            ]
                          },
                          "name": {
                            "type": "object",
                            "additionalProperties": {
                              "type": "string"
                            }
                          },
                          "description": {
                            "type": "object",
                            "additionalProperties": {
                              "type": "string"
                            }
                          },
                          "primaryLanguage": {
                            "type": "string"
                          },
                          "primaryName": {
                            "type": "string"
                          },
                          "primaryNameNormalized": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": ["DRAFT", "LIVE", "INACTIVE"],
                            "description": "Lifecycle of the service. Only LIVE services are bookable; DRAFT is unpublished and INACTIVE is retired."
                          },
                          "taxSettings": {
                            "type": "object",
                            "properties": {
                              "taxable": {
                                "type": "boolean"
                              },
                              "taxPercentage": {
                                "type": "number",
                                "minimum": 0
                              }
                            },
                            "required": ["taxable"]
                          },
                          "participantSettings": {
                            "$ref": "#/components/schemas/ParticipantSettings"
                          },
                          "bufferBeforeStartMinutes": {
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 120
                          },
                          "counts": {
                            "type": "object",
                            "properties": {
                              "offerings": {
                                "type": "integer",
                                "minimum": 0
                              }
                            },
                            "required": ["offerings"]
                          },
                          "deleted": {
                            "type": "boolean"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "createdBy": {
                            "type": "string"
                          },
                          "updatedBy": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "entityType",
                          "projectId",
                          "serviceId",
                          "categoryId",
                          "categorySnapshot",
                          "name",
                          "description",
                          "primaryLanguage",
                          "primaryName",
                          "primaryNameNormalized",
                          "status",
                          "taxSettings",
                          "counts",
                          "deleted",
                          "createdAt",
                          "updatedAt",
                          "createdBy",
                          "updatedBy"
                        ]
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": ["data", "nextCursor"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/services/{serviceId}": {
      "get": {
        "tags": ["Services"],
        "summary": "Get a service by ID",
        "description": "The service header on its own — its offerings, business models and attributes are separate resources and are not embedded here, so pricing and duration require a second call to the offerings endpoint. `counts.offerings` tells you whether that call is worth making. A soft-deleted service is a 404, not a tombstone.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
              "example": "srv_01kv60qg12e82acr78edfnjhvv"
            },
            "required": true,
            "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
            "name": "serviceId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Service",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "entityType": {
                          "type": "string",
                          "enum": ["SERVICE"]
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "serviceId": {
                          "type": "string"
                        },
                        "categoryId": {
                          "type": "string"
                        },
                        "categorySnapshot": {
                          "type": "object",
                          "properties": {
                            "categoryId": {
                              "type": "string"
                            },
                            "primaryName": {
                              "type": "string"
                            },
                            "primaryNameNormalized": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "categoryId",
                            "primaryName",
                            "primaryNameNormalized"
                          ]
                        },
                        "name": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "description": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "primaryLanguage": {
                          "type": "string"
                        },
                        "primaryName": {
                          "type": "string"
                        },
                        "primaryNameNormalized": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": ["DRAFT", "LIVE", "INACTIVE"],
                          "description": "Lifecycle of the service. Only LIVE services are bookable; DRAFT is unpublished and INACTIVE is retired."
                        },
                        "taxSettings": {
                          "type": "object",
                          "properties": {
                            "taxable": {
                              "type": "boolean"
                            },
                            "taxPercentage": {
                              "type": "number",
                              "minimum": 0
                            }
                          },
                          "required": ["taxable"]
                        },
                        "participantSettings": {
                          "$ref": "#/components/schemas/ParticipantSettings"
                        },
                        "bufferBeforeStartMinutes": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 120
                        },
                        "counts": {
                          "type": "object",
                          "properties": {
                            "offerings": {
                              "type": "integer",
                              "minimum": 0
                            }
                          },
                          "required": ["offerings"]
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "entityType",
                        "projectId",
                        "serviceId",
                        "categoryId",
                        "categorySnapshot",
                        "name",
                        "description",
                        "primaryLanguage",
                        "primaryName",
                        "primaryNameNormalized",
                        "status",
                        "taxSettings",
                        "counts",
                        "deleted",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": ["Services"],
        "summary": "Update a service",
        "description": "Edits the descriptive fields only. `name` and `description` are whole-map replacements, not merges: send every language you want to keep or the ones you omit are dropped. Renaming re-runs the uniqueness check and returns 409 if the new name is taken, so read the error before retrying — the rest of the update did not apply either. `participantSettings` is also a whole-object replacement: send every field, or omit it to leave the settings unchanged. `bufferBeforeStartMinutes` (0-120) is the spacing a supplier needs before this service starts; it is used for suggestions and checks only, never as busy time. Status is not settable here; use POST /services/{serviceId}/status.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
              "example": "srv_01kv60qg12e82acr78edfnjhvv"
            },
            "required": true,
            "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
            "name": "serviceId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Update data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "description": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "primaryLanguage": {
                    "type": "string",
                    "minLength": 1
                  },
                  "categoryId": {
                    "type": "string"
                  },
                  "taxSettings": {
                    "type": "object",
                    "properties": {
                      "taxable": {
                        "type": "boolean"
                      },
                      "taxPercentage": {
                        "type": "number",
                        "minimum": 0
                      }
                    },
                    "required": ["taxable"]
                  },
                  "participantSettings": {
                    "$ref": "#/components/schemas/ParticipantSettings"
                  },
                  "bufferBeforeStartMinutes": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 120,
                    "description": "Minutes a supplier needs free before this service starts. Used for suggestions and checks only, never as busy time.",
                    "example": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated service",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "entityType": {
                          "type": "string",
                          "enum": ["SERVICE"]
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "serviceId": {
                          "type": "string"
                        },
                        "categoryId": {
                          "type": "string"
                        },
                        "categorySnapshot": {
                          "type": "object",
                          "properties": {
                            "categoryId": {
                              "type": "string"
                            },
                            "primaryName": {
                              "type": "string"
                            },
                            "primaryNameNormalized": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "categoryId",
                            "primaryName",
                            "primaryNameNormalized"
                          ]
                        },
                        "name": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "description": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "primaryLanguage": {
                          "type": "string"
                        },
                        "primaryName": {
                          "type": "string"
                        },
                        "primaryNameNormalized": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": ["DRAFT", "LIVE", "INACTIVE"],
                          "description": "Lifecycle of the service. Only LIVE services are bookable; DRAFT is unpublished and INACTIVE is retired."
                        },
                        "taxSettings": {
                          "type": "object",
                          "properties": {
                            "taxable": {
                              "type": "boolean"
                            },
                            "taxPercentage": {
                              "type": "number",
                              "minimum": 0
                            }
                          },
                          "required": ["taxable"]
                        },
                        "participantSettings": {
                          "$ref": "#/components/schemas/ParticipantSettings"
                        },
                        "bufferBeforeStartMinutes": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 120
                        },
                        "counts": {
                          "type": "object",
                          "properties": {
                            "offerings": {
                              "type": "integer",
                              "minimum": 0
                            }
                          },
                          "required": ["offerings"]
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "entityType",
                        "projectId",
                        "serviceId",
                        "categoryId",
                        "categorySnapshot",
                        "name",
                        "description",
                        "primaryLanguage",
                        "primaryName",
                        "primaryNameNormalized",
                        "status",
                        "taxSettings",
                        "counts",
                        "deleted",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "Duplicate name",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Services"],
        "summary": "Soft delete a service",
        "description": "Marks the service deleted and flips it to INACTIVE. It disappears from lists and GETs while the record is retained, so bookings and orders already placed against it still resolve. The name reservation is released in the same write, meaning the name is immediately reusable by a new service — deleting is therefore how you free up a name you typed wrong. Offerings are not cascaded: they keep their own status and stay individually readable, so deactivate them first if anything of yours reads offerings without checking the parent.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
              "example": "srv_01kv60qg12e82acr78edfnjhvv"
            },
            "required": true,
            "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
            "name": "serviceId",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/services/{serviceId}/status": {
      "post": {
        "tags": ["Services"],
        "summary": "Change service status",
        "description": "The publish switch: only LIVE services are bookable. Allowed transitions are DRAFT to LIVE, DRAFT to INACTIVE, LIVE to INACTIVE and INACTIVE to LIVE; anything else is a 400. Note there is no route back to DRAFT once published, so a service you want to keep working on privately should go to INACTIVE, not be published early. INACTIVE stops new bookings and leaves existing ones intact.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
              "example": "srv_01kv60qg12e82acr78edfnjhvv"
            },
            "required": true,
            "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
            "name": "serviceId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "New status",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": ["DRAFT", "LIVE", "INACTIVE"],
                    "description": "Lifecycle of the service. Only LIVE services are bookable; DRAFT is unpublished and INACTIVE is retired."
                  }
                },
                "required": ["status"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated service",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "entityType": {
                          "type": "string",
                          "enum": ["SERVICE"]
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "serviceId": {
                          "type": "string"
                        },
                        "categoryId": {
                          "type": "string"
                        },
                        "categorySnapshot": {
                          "type": "object",
                          "properties": {
                            "categoryId": {
                              "type": "string"
                            },
                            "primaryName": {
                              "type": "string"
                            },
                            "primaryNameNormalized": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "categoryId",
                            "primaryName",
                            "primaryNameNormalized"
                          ]
                        },
                        "name": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "description": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "primaryLanguage": {
                          "type": "string"
                        },
                        "primaryName": {
                          "type": "string"
                        },
                        "primaryNameNormalized": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": ["DRAFT", "LIVE", "INACTIVE"],
                          "description": "Lifecycle of the service. Only LIVE services are bookable; DRAFT is unpublished and INACTIVE is retired."
                        },
                        "taxSettings": {
                          "type": "object",
                          "properties": {
                            "taxable": {
                              "type": "boolean"
                            },
                            "taxPercentage": {
                              "type": "number",
                              "minimum": 0
                            }
                          },
                          "required": ["taxable"]
                        },
                        "participantSettings": {
                          "$ref": "#/components/schemas/ParticipantSettings"
                        },
                        "bufferBeforeStartMinutes": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 120
                        },
                        "counts": {
                          "type": "object",
                          "properties": {
                            "offerings": {
                              "type": "integer",
                              "minimum": 0
                            }
                          },
                          "required": ["offerings"]
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "entityType",
                        "projectId",
                        "serviceId",
                        "categoryId",
                        "categorySnapshot",
                        "name",
                        "description",
                        "primaryLanguage",
                        "primaryName",
                        "primaryNameNormalized",
                        "status",
                        "taxSettings",
                        "counts",
                        "deleted",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid transition",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/services/{serviceId}/business-models": {
      "get": {
        "tags": ["ServiceBusinessModels"],
        "summary": "List business models for a service",
        "description": "How this service may be sold, and on what payment terms. Check here first when a package create returns 400: creating packages requires an entry with `type: \"PACKAGE\"` and `active: true`, and this is the only way to see whether the service has one. Inactive models are returned too — read `active`, do not assume presence means enabled. Not paginated; `nextCursor` is always null.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
              "example": "srv_01kv60qg12e82acr78edfnjhvv"
            },
            "required": true,
            "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
            "name": "serviceId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Business models",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "entityType": {
                            "type": "string",
                            "enum": ["SERVICE_BUSINESS_MODEL"]
                          },
                          "projectId": {
                            "type": "string"
                          },
                          "serviceId": {
                            "type": "string"
                          },
                          "businessModelId": {
                            "type": "string"
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "SINGLE_BOOKING",
                              "PACKAGE",
                              "SCHEDULED_PACKAGE",
                              "SCHEDULED_SUBSCRIPTION",
                              "FLEXIBLE_SUBSCRIPTION"
                            ],
                            "description": "How the service is sold. SINGLE_BOOKING is one booking at a time; PACKAGE sells prepaid credits drawn down by later bookings; the SCHEDULED_* and FLEXIBLE_* variants add recurrence and subscription billing. This drives which order item skuType applies."
                          },
                          "paymentOptions": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "enum": [
                                "PAY_WHILE_BOOKING",
                                "PAY_AFTER_SERVICE_DELIVERED",
                                "NO_PAYMENT",
                                "PAY_FULL_PRICE_WHILE_PURCHASING",
                                "PAY_BEGINNING_OF_MONTH",
                                "PAY_END_OF_MONTH"
                              ]
                            }
                          },
                          "fees": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "feeId": {
                                  "type": "string",
                                  "minLength": 1,
                                  "description": "Stable identifier for this fee, unique within the business model.",
                                  "example": "fee_booking"
                                },
                                "name": {
                                  "type": "object",
                                  "additionalProperties": {
                                    "type": "string"
                                  },
                                  "description": "Buyer-facing label, rendered as its own line on the order summary.",
                                  "example": {
                                    "en": "Booking fee"
                                  }
                                },
                                "calculation": {
                                  "type": "string",
                                  "enum": ["FLAT", "PERCENT"],
                                  "description": "How a service fee is calculated. FLAT charges a fixed amount; PERCENT charges a percentage of the pre-tax total of the lines the fee governs.",
                                  "example": "FLAT"
                                },
                                "amount": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "description": "FLAT fees only. Integer minor units, charged in whatever currency the order is placed in — 2500 is CA$25.00 on a CAD order and US$25.00 on a USD one. Use a PERCENT fee if you need it to scale.",
                                  "example": 2500
                                },
                                "percentage": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 100,
                                  "description": "PERCENT fees only. Applied to the pre-tax total of this business model's lines on the order.",
                                  "example": 5
                                },
                                "taxable": {
                                  "type": "boolean",
                                  "default": false,
                                  "description": "When true, the fee is taxed at the rate of the order lines it is charged alongside (sessions or packages sold under this business model) that are taxed at a positive rate. Lines that are not taxable or taxed at 0% lend no rate; if none of the lines is taxed, the fee is not taxed either.",
                                  "example": false
                                }
                              },
                              "required": ["feeId", "name", "calculation"]
                            },
                            "maxItems": 20,
                            "description": "Service fees — additional charges attached to this business model, applied to any order line sold under it. Each fee applies once per order regardless of how many lines it governs, and appears as its own entry on the order summary rather than being folded into tax.",
                            "example": [
                              {
                                "feeId": "fee_booking",
                                "name": {
                                  "en": "Booking fee"
                                },
                                "calculation": "FLAT",
                                "amount": 2500,
                                "taxable": false
                              },
                              {
                                "feeId": "fee_admin",
                                "name": {
                                  "en": "Admin fee"
                                },
                                "calculation": "PERCENT",
                                "percentage": 5,
                                "taxable": true
                              }
                            ]
                          },
                          "config": {
                            "type": "object",
                            "properties": {},
                            "additionalProperties": {
                              "nullable": true
                            }
                          },
                          "active": {
                            "type": "boolean"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "createdBy": {
                            "type": "string"
                          },
                          "updatedBy": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "entityType",
                          "projectId",
                          "serviceId",
                          "businessModelId",
                          "type",
                          "paymentOptions",
                          "config",
                          "active",
                          "createdAt",
                          "updatedAt",
                          "createdBy",
                          "updatedBy"
                        ]
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": ["data", "nextCursor"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["ServiceBusinessModels"],
        "summary": "Add a business model to a service",
        "description": "Declares a way the service can be sold, and gates what you can build on it — a service cannot have packages created against it until it carries an active PACKAGE model, so this call usually comes before the first package. The model is created active. Nothing here is deduplicated: posting the same `type` twice leaves two rows, both live, so list before you add. `type` cannot be changed afterwards, only deactivated, so pick it deliberately. `paymentOptions` sets when money is taken and must hold at least one option. `fees` are additional charges — a booking fee, an admin fee — attached to this business model and applied automatically to any order line sold under it. Each fee is charged once per order however many lines it governs, and surfaces as its own entry in the order summary rather than being folded into tax. A FLAT fee is a bare minor-unit figure that takes the currency of whatever order it lands on; use a PERCENT fee if you need it to scale.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
              "example": "srv_01kv60qg12e82acr78edfnjhvv"
            },
            "required": true,
            "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
            "name": "serviceId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Business model data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "SINGLE_BOOKING",
                      "PACKAGE",
                      "SCHEDULED_PACKAGE",
                      "SCHEDULED_SUBSCRIPTION",
                      "FLEXIBLE_SUBSCRIPTION"
                    ],
                    "description": "How the service is sold. SINGLE_BOOKING is one booking at a time; PACKAGE sells prepaid credits drawn down by later bookings; the SCHEDULED_* and FLEXIBLE_* variants add recurrence and subscription billing. This drives which order item skuType applies."
                  },
                  "paymentOptions": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "PAY_WHILE_BOOKING",
                        "PAY_AFTER_SERVICE_DELIVERED",
                        "NO_PAYMENT",
                        "PAY_FULL_PRICE_WHILE_PURCHASING",
                        "PAY_BEGINNING_OF_MONTH",
                        "PAY_END_OF_MONTH"
                      ]
                    },
                    "minItems": 1
                  },
                  "fees": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "feeId": {
                          "type": "string",
                          "minLength": 1,
                          "description": "Stable identifier for this fee, unique within the business model.",
                          "example": "fee_booking"
                        },
                        "name": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          },
                          "description": "Buyer-facing label, rendered as its own line on the order summary.",
                          "example": {
                            "en": "Booking fee"
                          }
                        },
                        "calculation": {
                          "type": "string",
                          "enum": ["FLAT", "PERCENT"],
                          "description": "How a service fee is calculated. FLAT charges a fixed amount; PERCENT charges a percentage of the pre-tax total of the lines the fee governs.",
                          "example": "FLAT"
                        },
                        "amount": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "FLAT fees only. Integer minor units, charged in whatever currency the order is placed in — 2500 is CA$25.00 on a CAD order and US$25.00 on a USD one. Use a PERCENT fee if you need it to scale.",
                          "example": 2500
                        },
                        "percentage": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 100,
                          "description": "PERCENT fees only. Applied to the pre-tax total of this business model's lines on the order.",
                          "example": 5
                        },
                        "taxable": {
                          "type": "boolean",
                          "default": false,
                          "description": "When true, the fee is taxed at the rate of the order lines it is charged alongside (sessions or packages sold under this business model) that are taxed at a positive rate. Lines that are not taxable or taxed at 0% lend no rate; if none of the lines is taxed, the fee is not taxed either.",
                          "example": false
                        }
                      },
                      "required": ["feeId", "name", "calculation"]
                    },
                    "maxItems": 20,
                    "default": [],
                    "description": "Service fees — additional charges attached to this business model, applied to any order line sold under it. Each fee applies once per order regardless of how many lines it governs, and appears as its own entry on the order summary rather than being folded into tax.",
                    "example": [
                      {
                        "feeId": "fee_booking",
                        "name": {
                          "en": "Booking fee"
                        },
                        "calculation": "FLAT",
                        "amount": 2500,
                        "taxable": false
                      },
                      {
                        "feeId": "fee_admin",
                        "name": {
                          "en": "Admin fee"
                        },
                        "calculation": "PERCENT",
                        "percentage": 5,
                        "taxable": true
                      }
                    ]
                  },
                  "config": {
                    "type": "object",
                    "properties": {},
                    "default": {},
                    "additionalProperties": {
                      "nullable": true
                    }
                  }
                },
                "required": ["type", "paymentOptions"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Business model created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "entityType": {
                          "type": "string",
                          "enum": ["SERVICE_BUSINESS_MODEL"]
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "serviceId": {
                          "type": "string"
                        },
                        "businessModelId": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "SINGLE_BOOKING",
                            "PACKAGE",
                            "SCHEDULED_PACKAGE",
                            "SCHEDULED_SUBSCRIPTION",
                            "FLEXIBLE_SUBSCRIPTION"
                          ],
                          "description": "How the service is sold. SINGLE_BOOKING is one booking at a time; PACKAGE sells prepaid credits drawn down by later bookings; the SCHEDULED_* and FLEXIBLE_* variants add recurrence and subscription billing. This drives which order item skuType applies."
                        },
                        "paymentOptions": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": [
                              "PAY_WHILE_BOOKING",
                              "PAY_AFTER_SERVICE_DELIVERED",
                              "NO_PAYMENT",
                              "PAY_FULL_PRICE_WHILE_PURCHASING",
                              "PAY_BEGINNING_OF_MONTH",
                              "PAY_END_OF_MONTH"
                            ]
                          }
                        },
                        "fees": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "feeId": {
                                "type": "string",
                                "minLength": 1,
                                "description": "Stable identifier for this fee, unique within the business model.",
                                "example": "fee_booking"
                              },
                              "name": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                },
                                "description": "Buyer-facing label, rendered as its own line on the order summary.",
                                "example": {
                                  "en": "Booking fee"
                                }
                              },
                              "calculation": {
                                "type": "string",
                                "enum": ["FLAT", "PERCENT"],
                                "description": "How a service fee is calculated. FLAT charges a fixed amount; PERCENT charges a percentage of the pre-tax total of the lines the fee governs.",
                                "example": "FLAT"
                              },
                              "amount": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "FLAT fees only. Integer minor units, charged in whatever currency the order is placed in — 2500 is CA$25.00 on a CAD order and US$25.00 on a USD one. Use a PERCENT fee if you need it to scale.",
                                "example": 2500
                              },
                              "percentage": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 100,
                                "description": "PERCENT fees only. Applied to the pre-tax total of this business model's lines on the order.",
                                "example": 5
                              },
                              "taxable": {
                                "type": "boolean",
                                "default": false,
                                "description": "When true, the fee is taxed at the rate of the order lines it is charged alongside (sessions or packages sold under this business model) that are taxed at a positive rate. Lines that are not taxable or taxed at 0% lend no rate; if none of the lines is taxed, the fee is not taxed either.",
                                "example": false
                              }
                            },
                            "required": ["feeId", "name", "calculation"]
                          },
                          "maxItems": 20,
                          "description": "Service fees — additional charges attached to this business model, applied to any order line sold under it. Each fee applies once per order regardless of how many lines it governs, and appears as its own entry on the order summary rather than being folded into tax.",
                          "example": [
                            {
                              "feeId": "fee_booking",
                              "name": {
                                "en": "Booking fee"
                              },
                              "calculation": "FLAT",
                              "amount": 2500,
                              "taxable": false
                            },
                            {
                              "feeId": "fee_admin",
                              "name": {
                                "en": "Admin fee"
                              },
                              "calculation": "PERCENT",
                              "percentage": 5,
                              "taxable": true
                            }
                          ]
                        },
                        "config": {
                          "type": "object",
                          "properties": {},
                          "additionalProperties": {
                            "nullable": true
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "entityType",
                        "projectId",
                        "serviceId",
                        "businessModelId",
                        "type",
                        "paymentOptions",
                        "config",
                        "active",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/services/{serviceId}/business-models/{businessModelId}": {
      "put": {
        "tags": ["ServiceBusinessModels"],
        "summary": "Update a business model",
        "description": "Edits `paymentOptions`, `fees`, and `config` only. `type` is fixed at creation and there is no way to change it — to switch a service from one selling model to another, deactivate this one and add the model you want. All three fields are whole-value replacements: sending `paymentOptions` discards the previous list rather than merging into it, and sending `config` replaces the whole object. Omit a field entirely to leave it untouched. Sending `fees` likewise replaces the entire list: omit the field to leave configured fees untouched, send `[]` to clear them. An unknown `businessModelId` is a 404, and nothing is written.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
              "example": "srv_01kv60qg12e82acr78edfnjhvv"
            },
            "required": true,
            "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
            "name": "serviceId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service business model — how the service is sold (per session, package, subscription) and what fees apply.",
              "example": "bm_01kv60qgr5m2xkp4n8b9gh6wqv"
            },
            "required": true,
            "description": "The service business model — how the service is sold (per session, package, subscription) and what fees apply.",
            "name": "businessModelId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Update data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "paymentOptions": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "PAY_WHILE_BOOKING",
                        "PAY_AFTER_SERVICE_DELIVERED",
                        "NO_PAYMENT",
                        "PAY_FULL_PRICE_WHILE_PURCHASING",
                        "PAY_BEGINNING_OF_MONTH",
                        "PAY_END_OF_MONTH"
                      ]
                    },
                    "minItems": 1
                  },
                  "fees": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "feeId": {
                          "type": "string",
                          "minLength": 1,
                          "description": "Stable identifier for this fee, unique within the business model.",
                          "example": "fee_booking"
                        },
                        "name": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          },
                          "description": "Buyer-facing label, rendered as its own line on the order summary.",
                          "example": {
                            "en": "Booking fee"
                          }
                        },
                        "calculation": {
                          "type": "string",
                          "enum": ["FLAT", "PERCENT"],
                          "description": "How a service fee is calculated. FLAT charges a fixed amount; PERCENT charges a percentage of the pre-tax total of the lines the fee governs.",
                          "example": "FLAT"
                        },
                        "amount": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "FLAT fees only. Integer minor units, charged in whatever currency the order is placed in — 2500 is CA$25.00 on a CAD order and US$25.00 on a USD one. Use a PERCENT fee if you need it to scale.",
                          "example": 2500
                        },
                        "percentage": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 100,
                          "description": "PERCENT fees only. Applied to the pre-tax total of this business model's lines on the order.",
                          "example": 5
                        },
                        "taxable": {
                          "type": "boolean",
                          "default": false,
                          "description": "When true, the fee is taxed at the rate of the order lines it is charged alongside (sessions or packages sold under this business model) that are taxed at a positive rate. Lines that are not taxable or taxed at 0% lend no rate; if none of the lines is taxed, the fee is not taxed either.",
                          "example": false
                        }
                      },
                      "required": ["feeId", "name", "calculation"]
                    },
                    "maxItems": 20,
                    "description": "Service fees — additional charges attached to this business model, applied to any order line sold under it. Each fee applies once per order regardless of how many lines it governs, and appears as its own entry on the order summary rather than being folded into tax.",
                    "example": [
                      {
                        "feeId": "fee_booking",
                        "name": {
                          "en": "Booking fee"
                        },
                        "calculation": "FLAT",
                        "amount": 2500,
                        "taxable": false
                      },
                      {
                        "feeId": "fee_admin",
                        "name": {
                          "en": "Admin fee"
                        },
                        "calculation": "PERCENT",
                        "percentage": 5,
                        "taxable": true
                      }
                    ]
                  },
                  "config": {
                    "type": "object",
                    "properties": {},
                    "additionalProperties": {
                      "nullable": true
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "entityType": {
                          "type": "string",
                          "enum": ["SERVICE_BUSINESS_MODEL"]
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "serviceId": {
                          "type": "string"
                        },
                        "businessModelId": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "SINGLE_BOOKING",
                            "PACKAGE",
                            "SCHEDULED_PACKAGE",
                            "SCHEDULED_SUBSCRIPTION",
                            "FLEXIBLE_SUBSCRIPTION"
                          ],
                          "description": "How the service is sold. SINGLE_BOOKING is one booking at a time; PACKAGE sells prepaid credits drawn down by later bookings; the SCHEDULED_* and FLEXIBLE_* variants add recurrence and subscription billing. This drives which order item skuType applies."
                        },
                        "paymentOptions": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": [
                              "PAY_WHILE_BOOKING",
                              "PAY_AFTER_SERVICE_DELIVERED",
                              "NO_PAYMENT",
                              "PAY_FULL_PRICE_WHILE_PURCHASING",
                              "PAY_BEGINNING_OF_MONTH",
                              "PAY_END_OF_MONTH"
                            ]
                          }
                        },
                        "fees": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "feeId": {
                                "type": "string",
                                "minLength": 1,
                                "description": "Stable identifier for this fee, unique within the business model.",
                                "example": "fee_booking"
                              },
                              "name": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                },
                                "description": "Buyer-facing label, rendered as its own line on the order summary.",
                                "example": {
                                  "en": "Booking fee"
                                }
                              },
                              "calculation": {
                                "type": "string",
                                "enum": ["FLAT", "PERCENT"],
                                "description": "How a service fee is calculated. FLAT charges a fixed amount; PERCENT charges a percentage of the pre-tax total of the lines the fee governs.",
                                "example": "FLAT"
                              },
                              "amount": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "FLAT fees only. Integer minor units, charged in whatever currency the order is placed in — 2500 is CA$25.00 on a CAD order and US$25.00 on a USD one. Use a PERCENT fee if you need it to scale.",
                                "example": 2500
                              },
                              "percentage": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 100,
                                "description": "PERCENT fees only. Applied to the pre-tax total of this business model's lines on the order.",
                                "example": 5
                              },
                              "taxable": {
                                "type": "boolean",
                                "default": false,
                                "description": "When true, the fee is taxed at the rate of the order lines it is charged alongside (sessions or packages sold under this business model) that are taxed at a positive rate. Lines that are not taxable or taxed at 0% lend no rate; if none of the lines is taxed, the fee is not taxed either.",
                                "example": false
                              }
                            },
                            "required": ["feeId", "name", "calculation"]
                          },
                          "maxItems": 20,
                          "description": "Service fees — additional charges attached to this business model, applied to any order line sold under it. Each fee applies once per order regardless of how many lines it governs, and appears as its own entry on the order summary rather than being folded into tax.",
                          "example": [
                            {
                              "feeId": "fee_booking",
                              "name": {
                                "en": "Booking fee"
                              },
                              "calculation": "FLAT",
                              "amount": 2500,
                              "taxable": false
                            },
                            {
                              "feeId": "fee_admin",
                              "name": {
                                "en": "Admin fee"
                              },
                              "calculation": "PERCENT",
                              "percentage": 5,
                              "taxable": true
                            }
                          ]
                        },
                        "config": {
                          "type": "object",
                          "properties": {},
                          "additionalProperties": {
                            "nullable": true
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "entityType",
                        "projectId",
                        "serviceId",
                        "businessModelId",
                        "type",
                        "paymentOptions",
                        "config",
                        "active",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Business model not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/services/{serviceId}/business-models/{businessModelId}/status": {
      "post": {
        "tags": ["ServiceBusinessModels"],
        "summary": "Toggle business model active status",
        "description": "Turns a selling model on or off without deleting it, which is how you retire one while keeping its history. Deactivating the PACKAGE model blocks NEW packages from being created against the service, but does nothing to packages that already exist — they keep selling until you archive them individually, so do both if you mean to stop package sales entirely. Toggling status never modifies the model itself: `type`, `paymentOptions` and `fees` are all left exactly as they were, so deactivating preserves configured fees and reactivating restores creation with them intact. Note a fee on an inactive model is stored but never charged, because order lines only resolve against ACTIVE business models. An unknown `businessModelId` is a 404, and nothing is written.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
              "example": "srv_01kv60qg12e82acr78edfnjhvv"
            },
            "required": true,
            "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
            "name": "serviceId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service business model — how the service is sold (per session, package, subscription) and what fees apply.",
              "example": "bm_01kv60qgr5m2xkp4n8b9gh6wqv"
            },
            "required": true,
            "description": "The service business model — how the service is sold (per session, package, subscription) and what fees apply.",
            "name": "businessModelId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Status",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "active": {
                    "type": "boolean"
                  }
                },
                "required": ["active"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "entityType": {
                          "type": "string",
                          "enum": ["SERVICE_BUSINESS_MODEL"]
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "serviceId": {
                          "type": "string"
                        },
                        "businessModelId": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "SINGLE_BOOKING",
                            "PACKAGE",
                            "SCHEDULED_PACKAGE",
                            "SCHEDULED_SUBSCRIPTION",
                            "FLEXIBLE_SUBSCRIPTION"
                          ],
                          "description": "How the service is sold. SINGLE_BOOKING is one booking at a time; PACKAGE sells prepaid credits drawn down by later bookings; the SCHEDULED_* and FLEXIBLE_* variants add recurrence and subscription billing. This drives which order item skuType applies."
                        },
                        "paymentOptions": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": [
                              "PAY_WHILE_BOOKING",
                              "PAY_AFTER_SERVICE_DELIVERED",
                              "NO_PAYMENT",
                              "PAY_FULL_PRICE_WHILE_PURCHASING",
                              "PAY_BEGINNING_OF_MONTH",
                              "PAY_END_OF_MONTH"
                            ]
                          }
                        },
                        "fees": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "feeId": {
                                "type": "string",
                                "minLength": 1,
                                "description": "Stable identifier for this fee, unique within the business model.",
                                "example": "fee_booking"
                              },
                              "name": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                },
                                "description": "Buyer-facing label, rendered as its own line on the order summary.",
                                "example": {
                                  "en": "Booking fee"
                                }
                              },
                              "calculation": {
                                "type": "string",
                                "enum": ["FLAT", "PERCENT"],
                                "description": "How a service fee is calculated. FLAT charges a fixed amount; PERCENT charges a percentage of the pre-tax total of the lines the fee governs.",
                                "example": "FLAT"
                              },
                              "amount": {
                                "type": "integer",
                                "minimum": 0,
                                "description": "FLAT fees only. Integer minor units, charged in whatever currency the order is placed in — 2500 is CA$25.00 on a CAD order and US$25.00 on a USD one. Use a PERCENT fee if you need it to scale.",
                                "example": 2500
                              },
                              "percentage": {
                                "type": "number",
                                "minimum": 0,
                                "maximum": 100,
                                "description": "PERCENT fees only. Applied to the pre-tax total of this business model's lines on the order.",
                                "example": 5
                              },
                              "taxable": {
                                "type": "boolean",
                                "default": false,
                                "description": "When true, the fee is taxed at the rate of the order lines it is charged alongside (sessions or packages sold under this business model) that are taxed at a positive rate. Lines that are not taxable or taxed at 0% lend no rate; if none of the lines is taxed, the fee is not taxed either.",
                                "example": false
                              }
                            },
                            "required": ["feeId", "name", "calculation"]
                          },
                          "maxItems": 20,
                          "description": "Service fees — additional charges attached to this business model, applied to any order line sold under it. Each fee applies once per order regardless of how many lines it governs, and appears as its own entry on the order summary rather than being folded into tax.",
                          "example": [
                            {
                              "feeId": "fee_booking",
                              "name": {
                                "en": "Booking fee"
                              },
                              "calculation": "FLAT",
                              "amount": 2500,
                              "taxable": false
                            },
                            {
                              "feeId": "fee_admin",
                              "name": {
                                "en": "Admin fee"
                              },
                              "calculation": "PERCENT",
                              "percentage": 5,
                              "taxable": true
                            }
                          ]
                        },
                        "config": {
                          "type": "object",
                          "properties": {},
                          "additionalProperties": {
                            "nullable": true
                          }
                        },
                        "active": {
                          "type": "boolean"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "entityType",
                        "projectId",
                        "serviceId",
                        "businessModelId",
                        "type",
                        "paymentOptions",
                        "config",
                        "active",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Business model not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/services/{serviceId}/offerings": {
      "post": {
        "tags": ["ServiceOfferings"],
        "summary": "Add an offering to a service",
        "description": "The offering is the sellable variant — price and duration live here, not on the service, so this is the call that makes a service purchasable. It is created ACTIVE; there is no draft step. `pricing` is a rule hierarchy, not a single amount: exactly one DEFAULT rule is required, a STATE rule is rejected without a COUNTRY rule for the same country, and a POSTAL rule is rejected without the matching STATE rule. `country` and `state` accept full names and are stored as ISO codes (\"Canada\" becomes \"CA\", \"Ontario\" becomes \"ON\"), so read back what you wrote rather than assuming your spelling survived. Anything an order cannot match a region rule for falls through to DEFAULT — including its currency, which is why a catalogue sold abroad needs a COUNTRY rule per currency and not just a translated name. Every id in `skillIds` and `locationIds` must already exist and be active in the project, or the whole call is a 400.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
              "example": "srv_01kv60qg12e82acr78edfnjhvv"
            },
            "required": true,
            "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
            "name": "serviceId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Offering data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "pricing": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "ruleId": {
                          "type": "string",
                          "minLength": 1
                        },
                        "scope": {
                          "type": "string",
                          "enum": ["DEFAULT", "COUNTRY", "STATE", "POSTAL"],
                          "description": "How specifically a price rule targets a region. Resolution picks the most specific match: POSTAL beats STATE beats COUNTRY beats DEFAULT. DEFAULT is the fallback every offering must define (\"any region\"). On an order item, `priceScope` reports which one actually applied — seeing DEFAULT where you expected a regional price means the region did not resolve."
                        },
                        "country": {
                          "type": "string",
                          "minLength": 1
                        },
                        "state": {
                          "type": "string",
                          "minLength": 1
                        },
                        "postalCodes": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "minLength": 1
                          }
                        },
                        "price": {
                          "$ref": "#/components/schemas/Money"
                        },
                        "tax": {
                          "type": "object",
                          "properties": {
                            "taxable": {
                              "type": "boolean"
                            },
                            "taxPercentage": {
                              "type": "number",
                              "minimum": 0
                            }
                          },
                          "required": ["taxable"]
                        }
                      },
                      "required": ["ruleId", "scope", "price"]
                    },
                    "minItems": 1
                  },
                  "duration": {
                    "oneOf": [
                      {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string",
                            "enum": ["FIXED"]
                          },
                          "minutes": {
                            "type": "integer",
                            "minimum": 0,
                            "exclusiveMinimum": true
                          }
                        },
                        "required": ["type", "minutes"]
                      },
                      {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string",
                            "enum": ["FLEXIBLE"]
                          },
                          "defaultMinutes": {
                            "type": "integer",
                            "minimum": 0,
                            "exclusiveMinimum": true
                          },
                          "minMinutes": {
                            "type": "integer",
                            "minimum": 0,
                            "exclusiveMinimum": true
                          },
                          "stepMinutes": {
                            "type": "integer",
                            "minimum": 0,
                            "exclusiveMinimum": true
                          },
                          "pricePerStep": {
                            "$ref": "#/components/schemas/Money"
                          }
                        },
                        "required": [
                          "type",
                          "defaultMinutes",
                          "minMinutes",
                          "stepMinutes"
                        ]
                      }
                    ]
                  },
                  "attributeValues": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "attributeId": {
                          "type": "string",
                          "minLength": 1
                        },
                        "attributeNameSnapshot": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "attributeType": {
                          "type": "string",
                          "enum": ["STRING", "NUMBER", "ENUM"],
                          "description": "Value type of a service attribute. ENUM attributes carry an allowed-values list."
                        },
                        "value": {
                          "anyOf": [
                            {
                              "type": "object",
                              "additionalProperties": {
                                "type": "string"
                              }
                            },
                            {
                              "type": "number"
                            },
                            {
                              "type": "string"
                            }
                          ]
                        },
                        "valueId": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "attributeId",
                        "attributeNameSnapshot",
                        "attributeType"
                      ]
                    },
                    "default": []
                  },
                  "skillIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "default": []
                  },
                  "locationIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "default": []
                  },
                  "holdDurationMinsOverride": {
                    "type": "integer",
                    "nullable": true,
                    "minimum": 0,
                    "exclusiveMinimum": true
                  }
                },
                "required": ["pricing", "duration"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Offering created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "entityType": {
                          "type": "string",
                          "enum": ["SERVICE_OFFERING"]
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "serviceId": {
                          "type": "string"
                        },
                        "offeringId": {
                          "type": "string"
                        },
                        "name": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "pricing": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "ruleId": {
                                "type": "string",
                                "minLength": 1
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "DEFAULT",
                                  "COUNTRY",
                                  "STATE",
                                  "POSTAL"
                                ],
                                "description": "How specifically a price rule targets a region. Resolution picks the most specific match: POSTAL beats STATE beats COUNTRY beats DEFAULT. DEFAULT is the fallback every offering must define (\"any region\"). On an order item, `priceScope` reports which one actually applied — seeing DEFAULT where you expected a regional price means the region did not resolve."
                              },
                              "country": {
                                "type": "string",
                                "minLength": 1
                              },
                              "state": {
                                "type": "string",
                                "minLength": 1
                              },
                              "postalCodes": {
                                "type": "array",
                                "items": {
                                  "type": "string",
                                  "minLength": 1
                                }
                              },
                              "price": {
                                "$ref": "#/components/schemas/Money"
                              },
                              "tax": {
                                "type": "object",
                                "properties": {
                                  "taxable": {
                                    "type": "boolean"
                                  },
                                  "taxPercentage": {
                                    "type": "number",
                                    "minimum": 0
                                  }
                                },
                                "required": ["taxable"]
                              }
                            },
                            "required": ["ruleId", "scope", "price"]
                          },
                          "minItems": 1
                        },
                        "duration": {
                          "oneOf": [
                            {
                              "type": "object",
                              "properties": {
                                "type": {
                                  "type": "string",
                                  "enum": ["FIXED"]
                                },
                                "minutes": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true
                                }
                              },
                              "required": ["type", "minutes"]
                            },
                            {
                              "type": "object",
                              "properties": {
                                "type": {
                                  "type": "string",
                                  "enum": ["FLEXIBLE"]
                                },
                                "defaultMinutes": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true
                                },
                                "minMinutes": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true
                                },
                                "stepMinutes": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true
                                },
                                "pricePerStep": {
                                  "$ref": "#/components/schemas/Money"
                                }
                              },
                              "required": [
                                "type",
                                "defaultMinutes",
                                "minMinutes",
                                "stepMinutes"
                              ]
                            }
                          ]
                        },
                        "attributeValues": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "attributeId": {
                                "type": "string",
                                "minLength": 1
                              },
                              "attributeNameSnapshot": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              },
                              "attributeType": {
                                "type": "string",
                                "enum": ["STRING", "NUMBER", "ENUM"],
                                "description": "Value type of a service attribute. ENUM attributes carry an allowed-values list."
                              },
                              "value": {
                                "anyOf": [
                                  {
                                    "type": "object",
                                    "additionalProperties": {
                                      "type": "string"
                                    }
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "string"
                                  }
                                ]
                              },
                              "valueId": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "attributeId",
                              "attributeNameSnapshot",
                              "attributeType"
                            ]
                          }
                        },
                        "status": {
                          "type": "string",
                          "enum": ["ACTIVE", "INACTIVE"],
                          "description": "Whether this offering can be booked. An INACTIVE offering rejects new bookings but existing ones stand."
                        },
                        "skillIds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "default": []
                        },
                        "locationIds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "default": []
                        },
                        "holdDurationMinsOverride": {
                          "type": "integer",
                          "nullable": true,
                          "minimum": 0,
                          "exclusiveMinimum": true
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "entityType",
                        "projectId",
                        "serviceId",
                        "offeringId",
                        "pricing",
                        "duration",
                        "attributeValues",
                        "status",
                        "deleted",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Service not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": ["ServiceOfferings"],
        "summary": "List offerings for a service",
        "description": "Every offering on the service, each already hydrated with the full `skills` and `locations` records behind its `skillIds`/`locationIds` — so rendering a service page needs no second round-trip per offering. Not paginated: `nextCursor` is always null and the whole set comes back at once. Soft-deleted offerings are excluded; INACTIVE ones are included unless you pass `status=ACTIVE`. An id that no longer resolves is dropped from the enriched arrays rather than erroring, so `skills` can be shorter than `skillIds`.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
              "example": "srv_01kv60qg12e82acr78edfnjhvv"
            },
            "required": true,
            "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
            "name": "serviceId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "enum": ["ACTIVE", "INACTIVE"],
              "description": "Whether this offering can be booked. An INACTIVE offering rejects new bookings but existing ones stand."
            },
            "required": false,
            "description": "Whether this offering can be booked. An INACTIVE offering rejects new bookings but existing ones stand.",
            "name": "status",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Offerings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "entityType": {
                            "type": "string",
                            "enum": ["SERVICE_OFFERING"]
                          },
                          "projectId": {
                            "type": "string"
                          },
                          "serviceId": {
                            "type": "string"
                          },
                          "offeringId": {
                            "type": "string"
                          },
                          "name": {
                            "type": "object",
                            "additionalProperties": {
                              "type": "string"
                            }
                          },
                          "pricing": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "ruleId": {
                                  "type": "string",
                                  "minLength": 1
                                },
                                "scope": {
                                  "type": "string",
                                  "enum": [
                                    "DEFAULT",
                                    "COUNTRY",
                                    "STATE",
                                    "POSTAL"
                                  ],
                                  "description": "How specifically a price rule targets a region. Resolution picks the most specific match: POSTAL beats STATE beats COUNTRY beats DEFAULT. DEFAULT is the fallback every offering must define (\"any region\"). On an order item, `priceScope` reports which one actually applied — seeing DEFAULT where you expected a regional price means the region did not resolve."
                                },
                                "country": {
                                  "type": "string",
                                  "minLength": 1
                                },
                                "state": {
                                  "type": "string",
                                  "minLength": 1
                                },
                                "postalCodes": {
                                  "type": "array",
                                  "items": {
                                    "type": "string",
                                    "minLength": 1
                                  }
                                },
                                "price": {
                                  "$ref": "#/components/schemas/Money"
                                },
                                "tax": {
                                  "type": "object",
                                  "properties": {
                                    "taxable": {
                                      "type": "boolean"
                                    },
                                    "taxPercentage": {
                                      "type": "number",
                                      "minimum": 0
                                    }
                                  },
                                  "required": ["taxable"]
                                }
                              },
                              "required": ["ruleId", "scope", "price"]
                            },
                            "minItems": 1
                          },
                          "duration": {
                            "oneOf": [
                              {
                                "type": "object",
                                "properties": {
                                  "type": {
                                    "type": "string",
                                    "enum": ["FIXED"]
                                  },
                                  "minutes": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "exclusiveMinimum": true
                                  }
                                },
                                "required": ["type", "minutes"]
                              },
                              {
                                "type": "object",
                                "properties": {
                                  "type": {
                                    "type": "string",
                                    "enum": ["FLEXIBLE"]
                                  },
                                  "defaultMinutes": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "exclusiveMinimum": true
                                  },
                                  "minMinutes": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "exclusiveMinimum": true
                                  },
                                  "stepMinutes": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "exclusiveMinimum": true
                                  },
                                  "pricePerStep": {
                                    "$ref": "#/components/schemas/Money"
                                  }
                                },
                                "required": [
                                  "type",
                                  "defaultMinutes",
                                  "minMinutes",
                                  "stepMinutes"
                                ]
                              }
                            ]
                          },
                          "attributeValues": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "attributeId": {
                                  "type": "string",
                                  "minLength": 1
                                },
                                "attributeNameSnapshot": {
                                  "type": "object",
                                  "additionalProperties": {
                                    "type": "string"
                                  }
                                },
                                "attributeType": {
                                  "type": "string",
                                  "enum": ["STRING", "NUMBER", "ENUM"],
                                  "description": "Value type of a service attribute. ENUM attributes carry an allowed-values list."
                                },
                                "value": {
                                  "anyOf": [
                                    {
                                      "type": "object",
                                      "additionalProperties": {
                                        "type": "string"
                                      }
                                    },
                                    {
                                      "type": "number"
                                    },
                                    {
                                      "type": "string"
                                    }
                                  ]
                                },
                                "valueId": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "attributeId",
                                "attributeNameSnapshot",
                                "attributeType"
                              ]
                            }
                          },
                          "status": {
                            "type": "string",
                            "enum": ["ACTIVE", "INACTIVE"],
                            "description": "Whether this offering can be booked. An INACTIVE offering rejects new bookings but existing ones stand."
                          },
                          "skillIds": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "default": []
                          },
                          "locationIds": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "default": []
                          },
                          "holdDurationMinsOverride": {
                            "type": "integer",
                            "nullable": true,
                            "minimum": 0,
                            "exclusiveMinimum": true
                          },
                          "deleted": {
                            "type": "boolean"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "createdBy": {
                            "type": "string"
                          },
                          "updatedBy": {
                            "type": "string"
                          },
                          "skills": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "skillId": {
                                  "type": "string"
                                },
                                "name": {
                                  "type": "string"
                                }
                              },
                              "required": ["skillId", "name"]
                            },
                            "default": []
                          },
                          "locations": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "locationId": {
                                  "type": "string"
                                },
                                "name": {
                                  "type": "string"
                                },
                                "addressOneLine": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "street": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "city": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "state": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "country": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "postalCode": {
                                  "type": "string",
                                  "nullable": true
                                }
                              },
                              "required": ["locationId", "name"]
                            },
                            "default": []
                          }
                        },
                        "required": [
                          "entityType",
                          "projectId",
                          "serviceId",
                          "offeringId",
                          "pricing",
                          "duration",
                          "attributeValues",
                          "status",
                          "deleted",
                          "createdAt",
                          "updatedAt",
                          "createdBy",
                          "updatedBy"
                        ]
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": ["data", "nextCursor"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}": {
      "get": {
        "tags": ["ServiceOfferings"],
        "summary": "Get an offering",
        "description": "One offering with its `skills` and `locations` resolved to full records, the same shape the list endpoint returns. This is where you read `pricing` and `duration` back after a write — the geo coercion means what you sent is not always what is stored. Offerings created before regional pricing existed report a single synthesised DEFAULT rule with `ruleId: \"r_legacy_default\"`; treat it as real pricing, but note it is derived at read time and is not what an update would preserve. A soft-deleted offering is a 404.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
              "example": "srv_01kv60qg12e82acr78edfnjhvv"
            },
            "required": true,
            "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
            "name": "serviceId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The offering — one bookable variant of a service, carrying its own duration and regional pricing rules.",
              "example": "off_01kv60qge5eh59ap0gw0pqrrys"
            },
            "required": true,
            "description": "The offering — one bookable variant of a service, carrying its own duration and regional pricing rules.",
            "name": "offeringId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Offering",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "entityType": {
                          "type": "string",
                          "enum": ["SERVICE_OFFERING"]
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "serviceId": {
                          "type": "string"
                        },
                        "offeringId": {
                          "type": "string"
                        },
                        "name": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "pricing": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "ruleId": {
                                "type": "string",
                                "minLength": 1
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "DEFAULT",
                                  "COUNTRY",
                                  "STATE",
                                  "POSTAL"
                                ],
                                "description": "How specifically a price rule targets a region. Resolution picks the most specific match: POSTAL beats STATE beats COUNTRY beats DEFAULT. DEFAULT is the fallback every offering must define (\"any region\"). On an order item, `priceScope` reports which one actually applied — seeing DEFAULT where you expected a regional price means the region did not resolve."
                              },
                              "country": {
                                "type": "string",
                                "minLength": 1
                              },
                              "state": {
                                "type": "string",
                                "minLength": 1
                              },
                              "postalCodes": {
                                "type": "array",
                                "items": {
                                  "type": "string",
                                  "minLength": 1
                                }
                              },
                              "price": {
                                "$ref": "#/components/schemas/Money"
                              },
                              "tax": {
                                "type": "object",
                                "properties": {
                                  "taxable": {
                                    "type": "boolean"
                                  },
                                  "taxPercentage": {
                                    "type": "number",
                                    "minimum": 0
                                  }
                                },
                                "required": ["taxable"]
                              }
                            },
                            "required": ["ruleId", "scope", "price"]
                          },
                          "minItems": 1
                        },
                        "duration": {
                          "oneOf": [
                            {
                              "type": "object",
                              "properties": {
                                "type": {
                                  "type": "string",
                                  "enum": ["FIXED"]
                                },
                                "minutes": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true
                                }
                              },
                              "required": ["type", "minutes"]
                            },
                            {
                              "type": "object",
                              "properties": {
                                "type": {
                                  "type": "string",
                                  "enum": ["FLEXIBLE"]
                                },
                                "defaultMinutes": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true
                                },
                                "minMinutes": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true
                                },
                                "stepMinutes": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true
                                },
                                "pricePerStep": {
                                  "$ref": "#/components/schemas/Money"
                                }
                              },
                              "required": [
                                "type",
                                "defaultMinutes",
                                "minMinutes",
                                "stepMinutes"
                              ]
                            }
                          ]
                        },
                        "attributeValues": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "attributeId": {
                                "type": "string",
                                "minLength": 1
                              },
                              "attributeNameSnapshot": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              },
                              "attributeType": {
                                "type": "string",
                                "enum": ["STRING", "NUMBER", "ENUM"],
                                "description": "Value type of a service attribute. ENUM attributes carry an allowed-values list."
                              },
                              "value": {
                                "anyOf": [
                                  {
                                    "type": "object",
                                    "additionalProperties": {
                                      "type": "string"
                                    }
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "string"
                                  }
                                ]
                              },
                              "valueId": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "attributeId",
                              "attributeNameSnapshot",
                              "attributeType"
                            ]
                          }
                        },
                        "status": {
                          "type": "string",
                          "enum": ["ACTIVE", "INACTIVE"],
                          "description": "Whether this offering can be booked. An INACTIVE offering rejects new bookings but existing ones stand."
                        },
                        "skillIds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "default": []
                        },
                        "locationIds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "default": []
                        },
                        "holdDurationMinsOverride": {
                          "type": "integer",
                          "nullable": true,
                          "minimum": 0,
                          "exclusiveMinimum": true
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        },
                        "skills": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "skillId": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              }
                            },
                            "required": ["skillId", "name"]
                          },
                          "default": []
                        },
                        "locations": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "locationId": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "addressOneLine": {
                                "type": "string",
                                "nullable": true
                              },
                              "street": {
                                "type": "string",
                                "nullable": true
                              },
                              "city": {
                                "type": "string",
                                "nullable": true
                              },
                              "state": {
                                "type": "string",
                                "nullable": true
                              },
                              "country": {
                                "type": "string",
                                "nullable": true
                              },
                              "postalCode": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": ["locationId", "name"]
                          },
                          "default": []
                        }
                      },
                      "required": [
                        "entityType",
                        "projectId",
                        "serviceId",
                        "offeringId",
                        "pricing",
                        "duration",
                        "attributeValues",
                        "status",
                        "deleted",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": ["ServiceOfferings"],
        "summary": "Update an offering",
        "description": "A partial update despite the verb: only the fields you send are written and the rest are left alone. Where a field is an array — `pricing`, `skillIds`, `locationIds`, `attributeValues` — sending it replaces the whole array, so add to a set by sending the full new one, never just the delta. Supplying `pricing` re-runs the same hierarchy and ISO coercion rules as create, so a partial rule set that drops the DEFAULT rule is a 400. An unknown or soft-deleted `offeringId` is a 404, and nothing is written.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
              "example": "srv_01kv60qg12e82acr78edfnjhvv"
            },
            "required": true,
            "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
            "name": "serviceId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The offering — one bookable variant of a service, carrying its own duration and regional pricing rules.",
              "example": "off_01kv60qge5eh59ap0gw0pqrrys"
            },
            "required": true,
            "description": "The offering — one bookable variant of a service, carrying its own duration and regional pricing rules.",
            "name": "offeringId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Update data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "pricing": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "ruleId": {
                          "type": "string",
                          "minLength": 1
                        },
                        "scope": {
                          "type": "string",
                          "enum": ["DEFAULT", "COUNTRY", "STATE", "POSTAL"],
                          "description": "How specifically a price rule targets a region. Resolution picks the most specific match: POSTAL beats STATE beats COUNTRY beats DEFAULT. DEFAULT is the fallback every offering must define (\"any region\"). On an order item, `priceScope` reports which one actually applied — seeing DEFAULT where you expected a regional price means the region did not resolve."
                        },
                        "country": {
                          "type": "string",
                          "minLength": 1
                        },
                        "state": {
                          "type": "string",
                          "minLength": 1
                        },
                        "postalCodes": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "minLength": 1
                          }
                        },
                        "price": {
                          "$ref": "#/components/schemas/Money"
                        },
                        "tax": {
                          "type": "object",
                          "properties": {
                            "taxable": {
                              "type": "boolean"
                            },
                            "taxPercentage": {
                              "type": "number",
                              "minimum": 0
                            }
                          },
                          "required": ["taxable"]
                        }
                      },
                      "required": ["ruleId", "scope", "price"]
                    },
                    "minItems": 1
                  },
                  "duration": {
                    "oneOf": [
                      {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string",
                            "enum": ["FIXED"]
                          },
                          "minutes": {
                            "type": "integer",
                            "minimum": 0,
                            "exclusiveMinimum": true
                          }
                        },
                        "required": ["type", "minutes"]
                      },
                      {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string",
                            "enum": ["FLEXIBLE"]
                          },
                          "defaultMinutes": {
                            "type": "integer",
                            "minimum": 0,
                            "exclusiveMinimum": true
                          },
                          "minMinutes": {
                            "type": "integer",
                            "minimum": 0,
                            "exclusiveMinimum": true
                          },
                          "stepMinutes": {
                            "type": "integer",
                            "minimum": 0,
                            "exclusiveMinimum": true
                          },
                          "pricePerStep": {
                            "$ref": "#/components/schemas/Money"
                          }
                        },
                        "required": [
                          "type",
                          "defaultMinutes",
                          "minMinutes",
                          "stepMinutes"
                        ]
                      }
                    ]
                  },
                  "attributeValues": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "attributeId": {
                          "type": "string",
                          "minLength": 1
                        },
                        "attributeNameSnapshot": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "attributeType": {
                          "type": "string",
                          "enum": ["STRING", "NUMBER", "ENUM"],
                          "description": "Value type of a service attribute. ENUM attributes carry an allowed-values list."
                        },
                        "value": {
                          "anyOf": [
                            {
                              "type": "object",
                              "additionalProperties": {
                                "type": "string"
                              }
                            },
                            {
                              "type": "number"
                            },
                            {
                              "type": "string"
                            }
                          ]
                        },
                        "valueId": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "attributeId",
                        "attributeNameSnapshot",
                        "attributeType"
                      ]
                    }
                  },
                  "skillIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "locationIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "holdDurationMinsOverride": {
                    "type": "integer",
                    "nullable": true,
                    "minimum": 0,
                    "exclusiveMinimum": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "entityType": {
                          "type": "string",
                          "enum": ["SERVICE_OFFERING"]
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "serviceId": {
                          "type": "string"
                        },
                        "offeringId": {
                          "type": "string"
                        },
                        "name": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "pricing": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "ruleId": {
                                "type": "string",
                                "minLength": 1
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "DEFAULT",
                                  "COUNTRY",
                                  "STATE",
                                  "POSTAL"
                                ],
                                "description": "How specifically a price rule targets a region. Resolution picks the most specific match: POSTAL beats STATE beats COUNTRY beats DEFAULT. DEFAULT is the fallback every offering must define (\"any region\"). On an order item, `priceScope` reports which one actually applied — seeing DEFAULT where you expected a regional price means the region did not resolve."
                              },
                              "country": {
                                "type": "string",
                                "minLength": 1
                              },
                              "state": {
                                "type": "string",
                                "minLength": 1
                              },
                              "postalCodes": {
                                "type": "array",
                                "items": {
                                  "type": "string",
                                  "minLength": 1
                                }
                              },
                              "price": {
                                "$ref": "#/components/schemas/Money"
                              },
                              "tax": {
                                "type": "object",
                                "properties": {
                                  "taxable": {
                                    "type": "boolean"
                                  },
                                  "taxPercentage": {
                                    "type": "number",
                                    "minimum": 0
                                  }
                                },
                                "required": ["taxable"]
                              }
                            },
                            "required": ["ruleId", "scope", "price"]
                          },
                          "minItems": 1
                        },
                        "duration": {
                          "oneOf": [
                            {
                              "type": "object",
                              "properties": {
                                "type": {
                                  "type": "string",
                                  "enum": ["FIXED"]
                                },
                                "minutes": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true
                                }
                              },
                              "required": ["type", "minutes"]
                            },
                            {
                              "type": "object",
                              "properties": {
                                "type": {
                                  "type": "string",
                                  "enum": ["FLEXIBLE"]
                                },
                                "defaultMinutes": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true
                                },
                                "minMinutes": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true
                                },
                                "stepMinutes": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true
                                },
                                "pricePerStep": {
                                  "$ref": "#/components/schemas/Money"
                                }
                              },
                              "required": [
                                "type",
                                "defaultMinutes",
                                "minMinutes",
                                "stepMinutes"
                              ]
                            }
                          ]
                        },
                        "attributeValues": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "attributeId": {
                                "type": "string",
                                "minLength": 1
                              },
                              "attributeNameSnapshot": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              },
                              "attributeType": {
                                "type": "string",
                                "enum": ["STRING", "NUMBER", "ENUM"],
                                "description": "Value type of a service attribute. ENUM attributes carry an allowed-values list."
                              },
                              "value": {
                                "anyOf": [
                                  {
                                    "type": "object",
                                    "additionalProperties": {
                                      "type": "string"
                                    }
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "string"
                                  }
                                ]
                              },
                              "valueId": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "attributeId",
                              "attributeNameSnapshot",
                              "attributeType"
                            ]
                          }
                        },
                        "status": {
                          "type": "string",
                          "enum": ["ACTIVE", "INACTIVE"],
                          "description": "Whether this offering can be booked. An INACTIVE offering rejects new bookings but existing ones stand."
                        },
                        "skillIds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "default": []
                        },
                        "locationIds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "default": []
                        },
                        "holdDurationMinsOverride": {
                          "type": "integer",
                          "nullable": true,
                          "minimum": 0,
                          "exclusiveMinimum": true
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "entityType",
                        "projectId",
                        "serviceId",
                        "offeringId",
                        "pricing",
                        "duration",
                        "attributeValues",
                        "status",
                        "deleted",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Offering not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["ServiceOfferings"],
        "summary": "Soft delete an offering",
        "description": "Marks the offering deleted, forces it INACTIVE and decrements the parent service's `counts.offerings`, once: deleting an unknown or already-deleted offering is a 404 and changes nothing, so a retry is safe. The record is retained so bookings and order items that snapshot it still resolve. Packages built on this offering are not cascaded and keep selling — archive those separately, or a storefront package will quote a session against an offering that no longer appears in the catalogue. Prefer the status route if you only want it off sale, since deletion cannot be undone through the API.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
              "example": "srv_01kv60qg12e82acr78edfnjhvv"
            },
            "required": true,
            "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
            "name": "serviceId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The offering — one bookable variant of a service, carrying its own duration and regional pricing rules.",
              "example": "off_01kv60qge5eh59ap0gw0pqrrys"
            },
            "required": true,
            "description": "The offering — one bookable variant of a service, carrying its own duration and regional pricing rules.",
            "name": "offeringId",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}/status": {
      "post": {
        "tags": ["ServiceOfferings"],
        "summary": "Change offering status",
        "description": "Takes one variant off sale without touching the rest of the service. An INACTIVE offering stops accepting new bookings while bookings already made against it stand, so this is the safe way to retire a price point or a duration. Unlike service status there is no transition table — ACTIVE and INACTIVE move freely in both directions. An unknown or soft-deleted `offeringId` is a 404, and nothing is written.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
              "example": "srv_01kv60qg12e82acr78edfnjhvv"
            },
            "required": true,
            "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
            "name": "serviceId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The offering — one bookable variant of a service, carrying its own duration and regional pricing rules.",
              "example": "off_01kv60qge5eh59ap0gw0pqrrys"
            },
            "required": true,
            "description": "The offering — one bookable variant of a service, carrying its own duration and regional pricing rules.",
            "name": "offeringId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "New status",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": ["ACTIVE", "INACTIVE"],
                    "description": "Whether this offering can be booked. An INACTIVE offering rejects new bookings but existing ones stand."
                  }
                },
                "required": ["status"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "entityType": {
                          "type": "string",
                          "enum": ["SERVICE_OFFERING"]
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "serviceId": {
                          "type": "string"
                        },
                        "offeringId": {
                          "type": "string"
                        },
                        "name": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        },
                        "pricing": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "ruleId": {
                                "type": "string",
                                "minLength": 1
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "DEFAULT",
                                  "COUNTRY",
                                  "STATE",
                                  "POSTAL"
                                ],
                                "description": "How specifically a price rule targets a region. Resolution picks the most specific match: POSTAL beats STATE beats COUNTRY beats DEFAULT. DEFAULT is the fallback every offering must define (\"any region\"). On an order item, `priceScope` reports which one actually applied — seeing DEFAULT where you expected a regional price means the region did not resolve."
                              },
                              "country": {
                                "type": "string",
                                "minLength": 1
                              },
                              "state": {
                                "type": "string",
                                "minLength": 1
                              },
                              "postalCodes": {
                                "type": "array",
                                "items": {
                                  "type": "string",
                                  "minLength": 1
                                }
                              },
                              "price": {
                                "$ref": "#/components/schemas/Money"
                              },
                              "tax": {
                                "type": "object",
                                "properties": {
                                  "taxable": {
                                    "type": "boolean"
                                  },
                                  "taxPercentage": {
                                    "type": "number",
                                    "minimum": 0
                                  }
                                },
                                "required": ["taxable"]
                              }
                            },
                            "required": ["ruleId", "scope", "price"]
                          },
                          "minItems": 1
                        },
                        "duration": {
                          "oneOf": [
                            {
                              "type": "object",
                              "properties": {
                                "type": {
                                  "type": "string",
                                  "enum": ["FIXED"]
                                },
                                "minutes": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true
                                }
                              },
                              "required": ["type", "minutes"]
                            },
                            {
                              "type": "object",
                              "properties": {
                                "type": {
                                  "type": "string",
                                  "enum": ["FLEXIBLE"]
                                },
                                "defaultMinutes": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true
                                },
                                "minMinutes": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true
                                },
                                "stepMinutes": {
                                  "type": "integer",
                                  "minimum": 0,
                                  "exclusiveMinimum": true
                                },
                                "pricePerStep": {
                                  "$ref": "#/components/schemas/Money"
                                }
                              },
                              "required": [
                                "type",
                                "defaultMinutes",
                                "minMinutes",
                                "stepMinutes"
                              ]
                            }
                          ]
                        },
                        "attributeValues": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "attributeId": {
                                "type": "string",
                                "minLength": 1
                              },
                              "attributeNameSnapshot": {
                                "type": "object",
                                "additionalProperties": {
                                  "type": "string"
                                }
                              },
                              "attributeType": {
                                "type": "string",
                                "enum": ["STRING", "NUMBER", "ENUM"],
                                "description": "Value type of a service attribute. ENUM attributes carry an allowed-values list."
                              },
                              "value": {
                                "anyOf": [
                                  {
                                    "type": "object",
                                    "additionalProperties": {
                                      "type": "string"
                                    }
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "string"
                                  }
                                ]
                              },
                              "valueId": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "attributeId",
                              "attributeNameSnapshot",
                              "attributeType"
                            ]
                          }
                        },
                        "status": {
                          "type": "string",
                          "enum": ["ACTIVE", "INACTIVE"],
                          "description": "Whether this offering can be booked. An INACTIVE offering rejects new bookings but existing ones stand."
                        },
                        "skillIds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "default": []
                        },
                        "locationIds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "default": []
                        },
                        "holdDurationMinsOverride": {
                          "type": "integer",
                          "nullable": true,
                          "minimum": 0,
                          "exclusiveMinimum": true
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "entityType",
                        "projectId",
                        "serviceId",
                        "offeringId",
                        "pricing",
                        "duration",
                        "attributeValues",
                        "status",
                        "deleted",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Offering not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/services/{serviceId}/offerings/{offeringId}/packages": {
      "post": {
        "tags": ["ServicePackages"],
        "summary": "Create a sellable package (bundle) for an offering",
        "description": "Sells `creditCount` prepaid sessions of one offering as a single bundle. The parent service must already carry an ACTIVE business model of type PACKAGE — without it this is a 400, and that guard is the usual reason a first package create fails, so add the business model before the package. The offering must belong to the service named in the path and not be deleted, or 404. Pricing is FLAT and cannot be changed: each rule's amount is the total for the WHOLE bundle, not per session, so a 10-session bundle at 45000 charges 45000 once. The `pricing` array obeys the same rules as an offering's — exactly one DEFAULT rule, children require parents, country and state coerce to ISO codes. Defaults if omitted: status ACTIVE (so it is on sale the moment it is created — send DRAFT if it is not ready), capacity 1, and validityDays null meaning credits never expire.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
              "example": "srv_01kv60qg12e82acr78edfnjhvv"
            },
            "required": true,
            "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
            "name": "serviceId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The offering — one bookable variant of a service, carrying its own duration and regional pricing rules.",
              "example": "off_01kv60qge5eh59ap0gw0pqrrys"
            },
            "required": true,
            "description": "The offering — one bookable variant of a service, carrying its own duration and regional pricing rules.",
            "name": "offeringId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Package data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "description": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "pricing": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "ruleId": {
                          "type": "string",
                          "minLength": 1
                        },
                        "scope": {
                          "type": "string",
                          "enum": ["DEFAULT", "COUNTRY", "STATE", "POSTAL"],
                          "description": "How specifically a price rule targets a region. Resolution picks the most specific match: POSTAL beats STATE beats COUNTRY beats DEFAULT. DEFAULT is the fallback every offering must define (\"any region\"). On an order item, `priceScope` reports which one actually applied — seeing DEFAULT where you expected a regional price means the region did not resolve."
                        },
                        "country": {
                          "type": "string",
                          "minLength": 1
                        },
                        "state": {
                          "type": "string",
                          "minLength": 1
                        },
                        "postalCodes": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "minLength": 1
                          }
                        },
                        "price": {
                          "$ref": "#/components/schemas/Money"
                        },
                        "tax": {
                          "type": "object",
                          "properties": {
                            "taxable": {
                              "type": "boolean"
                            },
                            "taxPercentage": {
                              "type": "number",
                              "minimum": 0
                            }
                          },
                          "required": ["taxable"]
                        }
                      },
                      "required": ["ruleId", "scope", "price"]
                    },
                    "minItems": 1
                  },
                  "creditCount": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true
                  },
                  "discountPercent": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Percentage discount (0-100) recorded when this package's prices were seeded from the offering's prices (price = offering price * creditCount * (1 - discountPercent/100)). Informational metadata only: `pricing` is the authoritative source of the amounts charged. Individual prices can be manually overridden after seeding, and the offering's prices may change later, so this value is not guaranteed to match the actual prices - never derive amounts from it."
                  },
                  "validityDays": {
                    "type": "integer",
                    "nullable": true,
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "default": null
                  },
                  "status": {
                    "type": "string",
                    "enum": ["DRAFT", "ACTIVE", "ARCHIVED"],
                    "default": "ACTIVE",
                    "description": "Lifecycle of the package bundle. ARCHIVED hides it from the storefront and blocks new orders, but order items already placed against it stay bookable."
                  },
                  "capacity": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "default": 1
                  }
                },
                "required": ["pricing", "creditCount"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Package created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ServicePackage"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Offering not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": ["ServicePackages"],
        "description": "The bundles buyable for one specific offering, ordered by status and then by credit count ascending — so the cheapest bundle leads and a price ladder renders without client-side sorting. Pass `status=ACTIVE` for the purchasable set; DRAFT and ARCHIVED bundles are included otherwise. Not paginated: `nextCursor` is always null, since a single offering's bundle list is small and bounded. Use the service-scoped list instead when the client has not yet chosen an offering. Unlike that route, an unknown `offeringId` here returns an empty list rather than 404, so an empty `data` does not prove the id was right.",
        "summary": "List packages for an offering (storefront)",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
              "example": "srv_01kv60qg12e82acr78edfnjhvv"
            },
            "required": true,
            "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
            "name": "serviceId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The offering — one bookable variant of a service, carrying its own duration and regional pricing rules.",
              "example": "off_01kv60qge5eh59ap0gw0pqrrys"
            },
            "required": true,
            "description": "The offering — one bookable variant of a service, carrying its own duration and regional pricing rules.",
            "name": "offeringId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "enum": ["DRAFT", "ACTIVE", "ARCHIVED"],
              "description": "Lifecycle of the package bundle. ARCHIVED hides it from the storefront and blocks new orders, but order items already placed against it stay bookable."
            },
            "required": false,
            "description": "Lifecycle of the package bundle. ARCHIVED hides it from the storefront and blocks new orders, but order items already placed against it stay bookable.",
            "name": "status",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Packages",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ServicePackage"
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": ["data", "nextCursor"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/services/{serviceId}/packages": {
      "get": {
        "tags": ["ServicePackages"],
        "summary": "List every package for a service (storefront discovery)",
        "description": "Returns every package under the service, across all of its offerings — the call a storefront makes before the client has chosen an option. Pass ?status=ACTIVE for only the purchasable bundles. Each package carries its offeringId, so the client can join it against the offerings list it already holds.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
              "example": "srv_01kv60qg12e82acr78edfnjhvv"
            },
            "required": true,
            "description": "The service — the sellable thing (a lesson, a treatment). Offerings hang off a service and carry the duration and price.",
            "name": "serviceId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "enum": ["DRAFT", "ACTIVE", "ARCHIVED"],
              "description": "Lifecycle of the package bundle. ARCHIVED hides it from the storefront and blocks new orders, but order items already placed against it stay bookable."
            },
            "required": false,
            "description": "Lifecycle of the package bundle. ARCHIVED hides it from the storefront and blocks new orders, but order items already placed against it stay bookable.",
            "name": "status",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Packages",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ServicePackage"
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": ["data", "nextCursor"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Service not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/packages/{packageId}": {
      "get": {
        "tags": ["ServicePackages"],
        "summary": "Get a package by id",
        "description": "Resolves a package from its id alone, without needing the serviceId — the order and slate flows hold a `packageId` and nothing else, which is why this route exists alongside the nested ones. Read it before creating an order to confirm `creditCount`, `capacity` and the region rules you are about to be charged against. Packages predating regional pricing report one synthesised DEFAULT rule with `ruleId: \"r_legacy_default\"`. A deleted or archived-then-deleted package is a 404; note that an order item already placed against it stays bookable even though this returns nothing.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service package — a bundle of prepaid sessions drawn down by bookings.",
              "example": "pkg_01kv7n10k0fnptwk81wkm59vj7"
            },
            "required": true,
            "description": "The service package — a bundle of prepaid sessions drawn down by bookings.",
            "name": "packageId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Package",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ServicePackage"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": ["ServicePackages"],
        "summary": "Update a package",
        "description": "A partial update: only the fields you send change. Editing `pricing` or `creditCount` affects future purchases ONLY — every order item already placed snapshots the package at purchase time, so repricing never disturbs credits a client has already bought and never retro-bills them. `pricing` is revalidated in full against the hierarchy rules, so send the complete rule set including its DEFAULT, not just the region you are changing. Neither the offering nor the service can be reassigned here; build a new package instead. Status is set through POST /packages/{packageId}/status, not here.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service package — a bundle of prepaid sessions drawn down by bookings.",
              "example": "pkg_01kv7n10k0fnptwk81wkm59vj7"
            },
            "required": true,
            "description": "The service package — a bundle of prepaid sessions drawn down by bookings.",
            "name": "packageId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Update data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "description": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "pricing": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "ruleId": {
                          "type": "string",
                          "minLength": 1
                        },
                        "scope": {
                          "type": "string",
                          "enum": ["DEFAULT", "COUNTRY", "STATE", "POSTAL"],
                          "description": "How specifically a price rule targets a region. Resolution picks the most specific match: POSTAL beats STATE beats COUNTRY beats DEFAULT. DEFAULT is the fallback every offering must define (\"any region\"). On an order item, `priceScope` reports which one actually applied — seeing DEFAULT where you expected a regional price means the region did not resolve."
                        },
                        "country": {
                          "type": "string",
                          "minLength": 1
                        },
                        "state": {
                          "type": "string",
                          "minLength": 1
                        },
                        "postalCodes": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "minLength": 1
                          }
                        },
                        "price": {
                          "$ref": "#/components/schemas/Money"
                        },
                        "tax": {
                          "type": "object",
                          "properties": {
                            "taxable": {
                              "type": "boolean"
                            },
                            "taxPercentage": {
                              "type": "number",
                              "minimum": 0
                            }
                          },
                          "required": ["taxable"]
                        }
                      },
                      "required": ["ruleId", "scope", "price"]
                    },
                    "minItems": 1
                  },
                  "creditCount": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true
                  },
                  "discountPercent": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100,
                    "description": "Percentage discount (0-100) recorded when this package's prices were seeded from the offering's prices (price = offering price * creditCount * (1 - discountPercent/100)). Informational metadata only: `pricing` is the authoritative source of the amounts charged. Individual prices can be manually overridden after seeding, and the offering's prices may change later, so this value is not guaranteed to match the actual prices - never derive amounts from it."
                  },
                  "validityDays": {
                    "type": "integer",
                    "nullable": true,
                    "minimum": 0,
                    "exclusiveMinimum": true
                  },
                  "capacity": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ServicePackage"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/packages/{packageId}/status": {
      "post": {
        "tags": ["ServicePackages"],
        "summary": "Change package status (rewrites the storefront sort key)",
        "description": "Moves the bundle between DRAFT, ACTIVE and ARCHIVED. Any status can follow any other — unlike services, there is no transition table, so a bundle can be pulled and reinstated freely. ARCHIVED is the correct way to retire a bundle: it drops out of the storefront and blocks new orders, while credits clients already bought stay bookable, which deleting the offering underneath would not achieve. Status is encoded in the storefront index key and rewritten here in the same write, so a status-filtered list reflects the change immediately rather than lagging.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The service package — a bundle of prepaid sessions drawn down by bookings.",
              "example": "pkg_01kv7n10k0fnptwk81wkm59vj7"
            },
            "required": true,
            "description": "The service package — a bundle of prepaid sessions drawn down by bookings.",
            "name": "packageId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "New status",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": ["DRAFT", "ACTIVE", "ARCHIVED"],
                    "description": "Lifecycle of the package bundle. ARCHIVED hides it from the storefront and blocks new orders, but order items already placed against it stay bookable."
                  }
                },
                "required": ["status"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ServicePackage"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/locations": {
      "get": {
        "tags": ["Locations"],
        "summary": "List locations for a project",
        "description": "The project's locations: PHYSICAL venues where a service is delivered, VIRTUAL locations, and TRAVEL_ZONE areas a supplier travels within. Active locations only unless `includeInactive=true`; deleted locations are never returned. Filter by `locationType`, and within a type by `namePrefix`. Not paginated: a project holds tens of locations, read in one query and returned in one response. Display `nameI18n` in the reader's language when present, falling back to `name`. Locations are created and edited in the MarketBox dashboard.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"],
              "description": "Only locations of this type. With it, the list is sorted by name; without it, by id.",
              "example": "PHYSICAL"
            },
            "required": false,
            "description": "Only locations of this type. With it, the list is sorted by name; without it, by id.",
            "name": "locationType",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": ["true", "false"],
              "description": "Also return inactive locations (`active: false`). Deleted locations are never returned.",
              "example": "false"
            },
            "required": false,
            "description": "Also return inactive locations (`active: false`). Deleted locations are never returned.",
            "name": "includeInactive",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Only locations whose name starts with this text, compared case-insensitively (against `nameNormalized`). Requires `locationType`: sent without it, the request is refused with 400 VALIDATION_ERROR.",
              "example": "bondi"
            },
            "required": false,
            "description": "Only locations whose name starts with this text, compared case-insensitively (against `nameNormalized`). Requires `locationType`: sent without it, the request is refused with 400 VALIDATION_ERROR.",
            "name": "namePrefix",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Locations list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "locationId": {
                            "type": "string",
                            "description": "The location id.",
                            "example": "loc_01kv60qh7rf3d9mn2ptxwa5zbc"
                          },
                          "projectId": {
                            "type": "string",
                            "description": "The project the location belongs to.",
                            "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
                          },
                          "locationType": {
                            "type": "string",
                            "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"],
                            "description": "PHYSICAL: a venue with an address and coordinates, where the service is delivered. VIRTUAL: delivered online; no address. TRAVEL_ZONE: an area the supplier travels within to reach the client, centred on `latitude`/`longitude` and bounded by the `travel*` fields.",
                            "example": "PHYSICAL"
                          },
                          "name": {
                            "type": "string",
                            "description": "The display name, unique within the project among locations of the same type.",
                            "example": "Bondi Pool"
                          },
                          "nameNormalized": {
                            "type": "string",
                            "description": "`name` trimmed, lower-cased and with inner spaces collapsed: the search key that `namePrefix` is matched against.",
                            "example": "bondi pool"
                          },
                          "defaultLanguage": {
                            "type": "string",
                            "description": "The language of `name`. Absent unless the location carries translations in `nameI18n`.",
                            "example": "en"
                          },
                          "nameI18n": {
                            "type": "object",
                            "additionalProperties": {
                              "type": "string"
                            },
                            "description": "The name by language code, when translations are set. Absent otherwise: display `name`.",
                            "example": {
                              "en": "Bondi Pool",
                              "fr": "Piscine de Bondi"
                            }
                          },
                          "addressOneLine": {
                            "type": "string",
                            "nullable": true,
                            "description": "The full address on one line. Usually null for a VIRTUAL location.",
                            "example": "1 Beach Rd, Bondi NSW 2026, AU"
                          },
                          "street": {
                            "type": "string",
                            "nullable": true,
                            "description": "Street line of the address.",
                            "example": "1 Beach Rd"
                          },
                          "city": {
                            "type": "string",
                            "nullable": true,
                            "description": "City.",
                            "example": "Bondi"
                          },
                          "state": {
                            "type": "string",
                            "nullable": true,
                            "description": "State, province or region.",
                            "example": "NSW"
                          },
                          "country": {
                            "type": "string",
                            "nullable": true,
                            "description": "Country.",
                            "example": "AU"
                          },
                          "postalCode": {
                            "type": "string",
                            "nullable": true,
                            "description": "Postal or ZIP code.",
                            "example": "2026"
                          },
                          "longitude": {
                            "type": "number",
                            "nullable": true,
                            "description": "Longitude (WGS 84): a PHYSICAL venue's position or a TRAVEL_ZONE's centre. Usually null for VIRTUAL.",
                            "example": 151.2743
                          },
                          "latitude": {
                            "type": "number",
                            "nullable": true,
                            "description": "Latitude (WGS 84): a PHYSICAL venue's position or a TRAVEL_ZONE's centre. Usually null for VIRTUAL.",
                            "example": -33.8915
                          },
                          "timezone": {
                            "type": "string",
                            "nullable": true,
                            "description": "The location's IANA time zone; a booking at this location is shown in it. Null when not set, in which case the supplier's or the project's zone applies.",
                            "example": "Australia/Sydney"
                          },
                          "travelZoneType": {
                            "type": "string",
                            "nullable": true,
                            "enum": ["CIRCULAR", "DRAWN", null],
                            "description": "TRAVEL_ZONE only (null otherwise). CIRCULAR: a radius of `travelDistance` around the centre. DRAWN: the polygon in `travelRegions`.",
                            "example": "CIRCULAR"
                          },
                          "travelDistance": {
                            "type": "number",
                            "nullable": true,
                            "description": "CIRCULAR travel zones only (null otherwise): the radius, in `travelDistanceUnit`.",
                            "example": 10
                          },
                          "travelDistanceUnit": {
                            "type": "string",
                            "nullable": true,
                            "enum": ["KM", "MILES", null],
                            "description": "CIRCULAR travel zones only (null otherwise): the unit of `travelDistance`.",
                            "example": "KM"
                          },
                          "travelRegions": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "type": {
                                "type": "string",
                                "enum": ["Polygon", "MultiPolygon"]
                              },
                              "coordinates": {
                                "nullable": true
                              }
                            },
                            "required": ["type"],
                            "description": "DRAWN travel zones only (null otherwise): the zone as a GeoJSON Polygon or MultiPolygon."
                          },
                          "active": {
                            "type": "boolean",
                            "description": "Whether the location is active. The list omits inactive locations unless `includeInactive=true` is passed.",
                            "example": true
                          },
                          "deleted": {
                            "type": "boolean",
                            "description": "Soft-delete flag; deleted locations are never returned, so this is always false.",
                            "example": false
                          },
                          "createdAt": {
                            "type": "string",
                            "description": "When the location was created (ISO 8601, UTC).",
                            "example": "2026-10-01T14:00:00.000Z"
                          },
                          "updatedAt": {
                            "type": "string",
                            "description": "When the location was last changed (ISO 8601, UTC).",
                            "example": "2026-10-01T14:00:00.000Z"
                          }
                        },
                        "required": [
                          "locationId",
                          "projectId",
                          "locationType",
                          "name",
                          "nameNormalized",
                          "active",
                          "deleted",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Project not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/locations/{locationId}": {
      "get": {
        "tags": ["Locations"],
        "summary": "Get a location by ID",
        "description": "One location of the project, active or inactive. A deleted location, an unknown id and another project's location all return the same 404.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "A location of the project: a PHYSICAL venue, a VIRTUAL location or a TRAVEL_ZONE. Ids come from GET /locations.",
              "example": "loc_01kv60qh7rf3d9mn2ptxwa5zbc"
            },
            "required": true,
            "description": "A location of the project: a PHYSICAL venue, a VIRTUAL location or a TRAVEL_ZONE. Ids come from GET /locations.",
            "name": "locationId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Location",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "locationId": {
                          "type": "string",
                          "description": "The location id.",
                          "example": "loc_01kv60qh7rf3d9mn2ptxwa5zbc"
                        },
                        "projectId": {
                          "type": "string",
                          "description": "The project the location belongs to.",
                          "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
                        },
                        "locationType": {
                          "type": "string",
                          "enum": ["PHYSICAL", "VIRTUAL", "TRAVEL_ZONE"],
                          "description": "PHYSICAL: a venue with an address and coordinates, where the service is delivered. VIRTUAL: delivered online; no address. TRAVEL_ZONE: an area the supplier travels within to reach the client, centred on `latitude`/`longitude` and bounded by the `travel*` fields.",
                          "example": "PHYSICAL"
                        },
                        "name": {
                          "type": "string",
                          "description": "The display name, unique within the project among locations of the same type.",
                          "example": "Bondi Pool"
                        },
                        "nameNormalized": {
                          "type": "string",
                          "description": "`name` trimmed, lower-cased and with inner spaces collapsed: the search key that `namePrefix` is matched against.",
                          "example": "bondi pool"
                        },
                        "defaultLanguage": {
                          "type": "string",
                          "description": "The language of `name`. Absent unless the location carries translations in `nameI18n`.",
                          "example": "en"
                        },
                        "nameI18n": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          },
                          "description": "The name by language code, when translations are set. Absent otherwise: display `name`.",
                          "example": {
                            "en": "Bondi Pool",
                            "fr": "Piscine de Bondi"
                          }
                        },
                        "addressOneLine": {
                          "type": "string",
                          "nullable": true,
                          "description": "The full address on one line. Usually null for a VIRTUAL location.",
                          "example": "1 Beach Rd, Bondi NSW 2026, AU"
                        },
                        "street": {
                          "type": "string",
                          "nullable": true,
                          "description": "Street line of the address.",
                          "example": "1 Beach Rd"
                        },
                        "city": {
                          "type": "string",
                          "nullable": true,
                          "description": "City.",
                          "example": "Bondi"
                        },
                        "state": {
                          "type": "string",
                          "nullable": true,
                          "description": "State, province or region.",
                          "example": "NSW"
                        },
                        "country": {
                          "type": "string",
                          "nullable": true,
                          "description": "Country.",
                          "example": "AU"
                        },
                        "postalCode": {
                          "type": "string",
                          "nullable": true,
                          "description": "Postal or ZIP code.",
                          "example": "2026"
                        },
                        "longitude": {
                          "type": "number",
                          "nullable": true,
                          "description": "Longitude (WGS 84): a PHYSICAL venue's position or a TRAVEL_ZONE's centre. Usually null for VIRTUAL.",
                          "example": 151.2743
                        },
                        "latitude": {
                          "type": "number",
                          "nullable": true,
                          "description": "Latitude (WGS 84): a PHYSICAL venue's position or a TRAVEL_ZONE's centre. Usually null for VIRTUAL.",
                          "example": -33.8915
                        },
                        "timezone": {
                          "type": "string",
                          "nullable": true,
                          "description": "The location's IANA time zone; a booking at this location is shown in it. Null when not set, in which case the supplier's or the project's zone applies.",
                          "example": "Australia/Sydney"
                        },
                        "travelZoneType": {
                          "type": "string",
                          "nullable": true,
                          "enum": ["CIRCULAR", "DRAWN", null],
                          "description": "TRAVEL_ZONE only (null otherwise). CIRCULAR: a radius of `travelDistance` around the centre. DRAWN: the polygon in `travelRegions`.",
                          "example": "CIRCULAR"
                        },
                        "travelDistance": {
                          "type": "number",
                          "nullable": true,
                          "description": "CIRCULAR travel zones only (null otherwise): the radius, in `travelDistanceUnit`.",
                          "example": 10
                        },
                        "travelDistanceUnit": {
                          "type": "string",
                          "nullable": true,
                          "enum": ["KM", "MILES", null],
                          "description": "CIRCULAR travel zones only (null otherwise): the unit of `travelDistance`.",
                          "example": "KM"
                        },
                        "travelRegions": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "type": {
                              "type": "string",
                              "enum": ["Polygon", "MultiPolygon"]
                            },
                            "coordinates": {
                              "nullable": true
                            }
                          },
                          "required": ["type"],
                          "description": "DRAWN travel zones only (null otherwise): the zone as a GeoJSON Polygon or MultiPolygon."
                        },
                        "active": {
                          "type": "boolean",
                          "description": "Whether the location is active. The list omits inactive locations unless `includeInactive=true` is passed.",
                          "example": true
                        },
                        "deleted": {
                          "type": "boolean",
                          "description": "Soft-delete flag; deleted locations are never returned, so this is always false.",
                          "example": false
                        },
                        "createdAt": {
                          "type": "string",
                          "description": "When the location was created (ISO 8601, UTC).",
                          "example": "2026-10-01T14:00:00.000Z"
                        },
                        "updatedAt": {
                          "type": "string",
                          "description": "When the location was last changed (ISO 8601, UTC).",
                          "example": "2026-10-01T14:00:00.000Z"
                        }
                      },
                      "required": [
                        "locationId",
                        "projectId",
                        "locationType",
                        "name",
                        "nameNormalized",
                        "active",
                        "deleted",
                        "createdAt",
                        "updatedAt"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Project or location not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/skills": {
      "get": {
        "tags": ["Skills"],
        "summary": "List skills for a project",
        "description": "The project's skills — the qualifications a supplier can list on their profile. Use it to build the skill picker of a supplier profile form: the ids you send as `skillIds` to PATCH /suppliers/me come from here. Active skills only unless `includeInactive=true`; soft-deleted skills are never returned. Not paginated: a project holds few enough skills to return in one response. Display `nameI18n` in the reader's language, falling back to `name`. Skills are created and edited in the MarketBox dashboard.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "enum": ["true", "false"],
              "description": "Also return inactive skills (`active: false`). Soft-deleted skills are never returned.",
              "example": "false"
            },
            "required": false,
            "description": "Also return inactive skills (`active: false`). Soft-deleted skills are never returned.",
            "name": "includeInactive",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Skills list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "skillId": {
                            "type": "string",
                            "description": "The skill id; what a supplier profile lists in `skillIds`.",
                            "example": "skl_01kv60qgnef2kt3pvqgwmkbzfr"
                          },
                          "projectId": {
                            "type": "string",
                            "description": "The project the skill belongs to.",
                            "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
                          },
                          "defaultLanguage": {
                            "type": "string",
                            "description": "The language of `name`; `nameI18n` always has an entry for it.",
                            "example": "en"
                          },
                          "name": {
                            "type": "string",
                            "description": "The name in `defaultLanguage`.",
                            "example": "Lifeguard certified"
                          },
                          "nameI18n": {
                            "type": "object",
                            "additionalProperties": {
                              "type": "string"
                            },
                            "description": "The name by language code.",
                            "example": {
                              "en": "Lifeguard certified",
                              "fr": "Sauveteur certifié"
                            }
                          },
                          "nameNormalized": {
                            "type": "string",
                            "description": "`name` trimmed, lower-cased, spaces collapsed; unique within the project.",
                            "example": "lifeguard certified"
                          },
                          "active": {
                            "type": "boolean",
                            "description": "Whether the skill is active. List endpoints omit inactive skills unless `includeInactive=true` is passed.",
                            "example": true
                          },
                          "deleted": {
                            "type": "boolean",
                            "description": "Soft-delete flag; deleted skills are never listed, so this is always false.",
                            "example": false
                          },
                          "ordinal": {
                            "type": "number",
                            "description": "Display order, ascending. A list of active skills is sorted by it; with `includeInactive=true` the inactive skills come first, each group sorted by it.",
                            "example": 0
                          },
                          "createdAt": {
                            "type": "string",
                            "description": "When the skill was created (ISO 8601, UTC).",
                            "example": "2026-10-01T14:00:00.000Z"
                          },
                          "updatedAt": {
                            "type": "string",
                            "description": "When the skill was last changed (ISO 8601, UTC).",
                            "example": "2026-10-01T14:00:00.000Z"
                          }
                        },
                        "required": [
                          "skillId",
                          "projectId",
                          "defaultLanguage",
                          "name",
                          "nameI18n",
                          "nameNormalized",
                          "active",
                          "deleted",
                          "ordinal",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Project not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/orders/{orderId}/transactions": {
      "post": {
        "tags": ["Transactions"],
        "summary": "Record a manual (cash/external/comp) transaction against an order",
        "description": "Books money that moved outside Stripe — cash at the door, a bank transfer, a comped session. Card payments do not belong here: `source` accepts only CASH, EXTERNAL and COMP, and STRIPE is rejected, because Stripe rows are created by the payment-intent flow and settled by webhook. `kind: \"REFUND\"` is likewise rejected; refunds are not yet supported.\n\nThe two kinds behave differently and the difference is easy to miss. PAYMENT adds to the order's `amountPaid` in the same atomic write, so it changes what the order still owes. ADJUSTMENT records a ledger row and leaves `amountPaid` alone — use it for corrections you want visible in history without moving the balance. Either way the row is written SUCCEEDED immediately, with no pending state to poll.\n\n`amount.currency` must equal the order's currency exactly or the call is a 400; the order's currency is fixed at creation and cannot be converted here. A 409 means the order changed between this call reading it and writing — re-read the order and retry, rather than assuming the payment was recorded. `clientId` defaults to the order's client.\n\n`source: \"COMP\"` REQUIRES `reason` — a waived charge with no justification on the ledger is refused with a 400. Record why the charge was waived (\"Service recovery — late supplier\"), not that it was waived; the row already says that.\n\nSend `idempotencyKey` on any recording you might retry. The same key on the same order returns the row the FIRST call created, as HTTP 200 with `replayed: true`, instead of recording the money a second time; a first recording is 201 with `replayed: false`. Branch on the status or on `replayed` — never on \"a 2xx means I just took a payment\". A key belongs to one order and does not expire.\n\nThe order settles as a consequence of this write, not through a separate call: once the ledger covers the order's total the order moves to `PAID` in the same atomic write, with `settledAt` and `paymentMethod` stamped on it. `PAID` cannot be asked for directly — `POST /orders/{orderId}/status` answers a `PAID` target with a 409.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The order — the commercial record. Order items are drawn down into bookings.",
              "example": "ord_01kv8m92p4jcrywn14znp8cym0"
            },
            "required": true,
            "description": "The order — the commercial record. Order items are drawn down into bookings.",
            "name": "orderId",
            "in": "path"
          }
        ],
        "requestBody": {
          "description": "Manual transaction data",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "enum": ["PAYMENT", "ADJUSTMENT"]
                  },
                  "source": {
                    "type": "string",
                    "enum": ["CASH", "EXTERNAL", "COMP"]
                  },
                  "amount": {
                    "$ref": "#/components/schemas/Money"
                  },
                  "clientId": {
                    "type": "string",
                    "minLength": 1
                  },
                  "note": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 500
                  },
                  "reason": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 500,
                    "description": "Why the charge was waived. REQUIRED when source is COMP.",
                    "example": "Service recovery — late supplier"
                  },
                  "idempotencyKey": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128,
                    "description": "Replay guard. The same key on the same order returns the row the first call created instead of recording the money twice.",
                    "example": "9f8c0f7a-1f3f-4c8e-9a2b-6c7d8e9f0a1b"
                  }
                },
                "required": ["kind", "source", "amount"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Replay of an earlier idempotencyKey — the original row, unchanged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "projectId": {
                          "type": "string"
                        },
                        "tenantId": {
                          "type": "string"
                        },
                        "transactionId": {
                          "type": "string"
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "PAYMENT",
                            "REFUND",
                            "CREDIT_REDEMPTION",
                            "ADJUSTMENT",
                            "CREDIT_REVERSAL"
                          ]
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "STRIPE",
                            "CASH",
                            "EXTERNAL",
                            "PACKAGE_CREDIT",
                            "COMP"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "enum": ["PENDING", "SUCCEEDED", "FAILED", "CANCELED"]
                        },
                        "amount": {
                          "$ref": "#/components/schemas/Money"
                        },
                        "platformFee": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/Money"
                            },
                            {
                              "nullable": true
                            }
                          ]
                        },
                        "relatedTransactionId": {
                          "type": "string",
                          "nullable": true
                        },
                        "orderId": {
                          "type": "string"
                        },
                        "orderItemId": {
                          "type": "string",
                          "nullable": true
                        },
                        "allocationId": {
                          "type": "string",
                          "nullable": true
                        },
                        "bookingId": {
                          "type": "string",
                          "nullable": true
                        },
                        "clientId": {
                          "type": "string",
                          "nullable": true
                        },
                        "stripePaymentIntentId": {
                          "type": "string",
                          "nullable": true
                        },
                        "stripeChargeId": {
                          "type": "string",
                          "nullable": true
                        },
                        "stripeRefundId": {
                          "type": "string",
                          "nullable": true
                        },
                        "stripeAccountId": {
                          "type": "string",
                          "nullable": true
                        },
                        "connectChargeType": {
                          "type": "string",
                          "nullable": true,
                          "enum": ["DIRECT"]
                        },
                        "failureCode": {
                          "type": "string",
                          "nullable": true
                        },
                        "failureMessage": {
                          "type": "string",
                          "nullable": true
                        },
                        "note": {
                          "type": "string",
                          "nullable": true
                        },
                        "disputeId": {
                          "type": "string",
                          "nullable": true,
                          "description": "The Stripe dispute (chargeback) id, when the client disputed this card payment with their bank. Set by MarketBox from Stripe's events, never by a request. The transaction's `status` stays SUCCEEDED while it is disputed."
                        },
                        "disputeStatus": {
                          "type": "string",
                          "nullable": true,
                          "enum": [
                            "needs_response",
                            "under_review",
                            "won",
                            "lost",
                            null
                          ],
                          "description": "Where the dispute stands: `needs_response` (evidence is due in Stripe), `under_review` (the bank is deciding), `won` (the money stays), or `lost` (the money was taken back). Null or absent when the payment was never disputed. An inquiry that closes without a chargeback reads `won`. Respond to a dispute in Stripe: the API cannot."
                        },
                        "channel": {
                          "type": "string",
                          "enum": [
                            "BACKOFFICE",
                            "OPEN_API",
                            "STRIPE_WEBHOOK",
                            "SCHEDULER",
                            "ORDER_CASCADE",
                            "MIGRATION"
                          ]
                        },
                        "reason": {
                          "type": "string",
                          "nullable": true
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "version": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "projectId",
                        "tenantId",
                        "transactionId",
                        "kind",
                        "source",
                        "status",
                        "amount",
                        "orderId",
                        "deleted",
                        "version",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    },
                    "replayed": {
                      "type": "boolean",
                      "enum": [true]
                    }
                  },
                  "required": ["data", "replayed"]
                }
              }
            }
          },
          "201": {
            "description": "Transaction recorded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "projectId": {
                          "type": "string"
                        },
                        "tenantId": {
                          "type": "string"
                        },
                        "transactionId": {
                          "type": "string"
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "PAYMENT",
                            "REFUND",
                            "CREDIT_REDEMPTION",
                            "ADJUSTMENT",
                            "CREDIT_REVERSAL"
                          ]
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "STRIPE",
                            "CASH",
                            "EXTERNAL",
                            "PACKAGE_CREDIT",
                            "COMP"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "enum": ["PENDING", "SUCCEEDED", "FAILED", "CANCELED"]
                        },
                        "amount": {
                          "$ref": "#/components/schemas/Money"
                        },
                        "platformFee": {
                          "allOf": [
                            {
                              "$ref": "#/components/schemas/Money"
                            },
                            {
                              "nullable": true
                            }
                          ]
                        },
                        "relatedTransactionId": {
                          "type": "string",
                          "nullable": true
                        },
                        "orderId": {
                          "type": "string"
                        },
                        "orderItemId": {
                          "type": "string",
                          "nullable": true
                        },
                        "allocationId": {
                          "type": "string",
                          "nullable": true
                        },
                        "bookingId": {
                          "type": "string",
                          "nullable": true
                        },
                        "clientId": {
                          "type": "string",
                          "nullable": true
                        },
                        "stripePaymentIntentId": {
                          "type": "string",
                          "nullable": true
                        },
                        "stripeChargeId": {
                          "type": "string",
                          "nullable": true
                        },
                        "stripeRefundId": {
                          "type": "string",
                          "nullable": true
                        },
                        "stripeAccountId": {
                          "type": "string",
                          "nullable": true
                        },
                        "connectChargeType": {
                          "type": "string",
                          "nullable": true,
                          "enum": ["DIRECT"]
                        },
                        "failureCode": {
                          "type": "string",
                          "nullable": true
                        },
                        "failureMessage": {
                          "type": "string",
                          "nullable": true
                        },
                        "note": {
                          "type": "string",
                          "nullable": true
                        },
                        "disputeId": {
                          "type": "string",
                          "nullable": true,
                          "description": "The Stripe dispute (chargeback) id, when the client disputed this card payment with their bank. Set by MarketBox from Stripe's events, never by a request. The transaction's `status` stays SUCCEEDED while it is disputed."
                        },
                        "disputeStatus": {
                          "type": "string",
                          "nullable": true,
                          "enum": [
                            "needs_response",
                            "under_review",
                            "won",
                            "lost",
                            null
                          ],
                          "description": "Where the dispute stands: `needs_response` (evidence is due in Stripe), `under_review` (the bank is deciding), `won` (the money stays), or `lost` (the money was taken back). Null or absent when the payment was never disputed. An inquiry that closes without a chargeback reads `won`. Respond to a dispute in Stripe: the API cannot."
                        },
                        "channel": {
                          "type": "string",
                          "enum": [
                            "BACKOFFICE",
                            "OPEN_API",
                            "STRIPE_WEBHOOK",
                            "SCHEDULER",
                            "ORDER_CASCADE",
                            "MIGRATION"
                          ]
                        },
                        "reason": {
                          "type": "string",
                          "nullable": true
                        },
                        "deleted": {
                          "type": "boolean"
                        },
                        "version": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdBy": {
                          "type": "string"
                        },
                        "updatedBy": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "projectId",
                        "tenantId",
                        "transactionId",
                        "kind",
                        "source",
                        "status",
                        "amount",
                        "orderId",
                        "deleted",
                        "version",
                        "createdAt",
                        "updatedAt",
                        "createdBy",
                        "updatedBy"
                      ]
                    },
                    "replayed": {
                      "type": "boolean",
                      "enum": [false]
                    }
                  },
                  "required": ["data", "replayed"]
                }
              }
            }
          },
          "400": {
            "description": "Validation error / currency mismatch / a COMP with no reason",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Order or client not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "Order modified concurrently (VERSION_CONFLICT), or a replay whose original row could not be read (TRANSACTION_IDEMPOTENCY_RECORD_MISSING — terminal, do not retry)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "422": {
            "description": "A SUCCEEDED PAYMENT, or an ADJUSTMENT with source COMP, on a CANCELLED order (ORDER_NOT_PAYABLE). A REFUND, or any other ADJUSTMENT, is still recorded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/transactions": {
      "get": {
        "tags": ["Transactions"],
        "summary": "List transactions (filter by order, client, or status)",
        "description": "The money ledger for the project, newest first, for reconciliation and payment history.\n\nThe filters are not combinable, and this is the mistake to avoid: exactly one of `orderId`, `clientId` and `status` takes effect, in that order of precedence, and the others are ignored without an error. Sending `orderId` with `status=FAILED` returns EVERY transaction on that order, failed or not — so filter by status client-side when you also need one of the others. With none of the three set, the whole project is listed. `startDate` and `endDate` are the exception: they narrow whichever of the four queries runs.\n\nResults are paginated with an opaque cursor that is only valid for the same filters that produced it. Both settled and unsettled rows come back, so sum only `status: \"SUCCEEDED\"` when computing what was actually collected — a PENDING Stripe row is an intent, not money.\n\nThe ledger is append-only, so a correction is always a NEW row pointing at the one it corrects through `relatedTransactionId`, never an edit. Amounts are always positive; the `kind` carries the direction. A `REFUND` offsets a `PAYMENT`, and a `CREDIT_REVERSAL` offsets the `CREDIT_REDEMPTION` of a package session that was cancelled and returned to its package — so package credit actually used is redemptions minus reversals. Neither credit kind is money: both have `source: \"PACKAGE_CREDIT\"`. A consumer switching exhaustively on `kind` should tolerate values it does not know.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "required": false,
            "name": "orderId",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "required": false,
            "name": "clientId",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": ["PENDING", "SUCCEEDED", "FAILED", "CANCELED"]
            },
            "required": false,
            "name": "status",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "required": false,
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "required": false,
            "name": "endDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50,
              "description": "Maximum rows to return in `data`, 1–200. Defaults to 50. Values outside the range return 400. A page can still hold fewer rows than requested, so treat `nextCursor: null` as the only end-of-results signal and never stop on a page that merely looks short.",
              "example": 50
            },
            "required": false,
            "description": "Maximum rows to return in `data`, 1–200. Defaults to 50. Values outside the range return 400. A page can still hold fewer rows than requested, so treat `nextCursor: null` as the only end-of-results signal and never stop on a page that merely looks short.",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Opaque pagination token from a previous response's `nextCursor`. Treat it as a magic string — never parse or construct one. A cursor is only valid for the same filters that produced it, and `nextCursor: null` means the last page."
            },
            "required": false,
            "description": "Opaque pagination token from a previous response's `nextCursor`. Treat it as a magic string — never parse or construct one. A cursor is only valid for the same filters that produced it, and `nextCursor: null` means the last page.",
            "name": "cursor",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Transactions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "projectId": {
                            "type": "string"
                          },
                          "tenantId": {
                            "type": "string"
                          },
                          "transactionId": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "PAYMENT",
                              "REFUND",
                              "CREDIT_REDEMPTION",
                              "ADJUSTMENT",
                              "CREDIT_REVERSAL"
                            ]
                          },
                          "source": {
                            "type": "string",
                            "enum": [
                              "STRIPE",
                              "CASH",
                              "EXTERNAL",
                              "PACKAGE_CREDIT",
                              "COMP"
                            ]
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "PENDING",
                              "SUCCEEDED",
                              "FAILED",
                              "CANCELED"
                            ]
                          },
                          "amount": {
                            "$ref": "#/components/schemas/Money"
                          },
                          "platformFee": {
                            "allOf": [
                              {
                                "$ref": "#/components/schemas/Money"
                              },
                              {
                                "nullable": true
                              }
                            ]
                          },
                          "relatedTransactionId": {
                            "type": "string",
                            "nullable": true
                          },
                          "orderId": {
                            "type": "string"
                          },
                          "orderItemId": {
                            "type": "string",
                            "nullable": true
                          },
                          "allocationId": {
                            "type": "string",
                            "nullable": true
                          },
                          "bookingId": {
                            "type": "string",
                            "nullable": true
                          },
                          "clientId": {
                            "type": "string",
                            "nullable": true
                          },
                          "stripePaymentIntentId": {
                            "type": "string",
                            "nullable": true
                          },
                          "stripeChargeId": {
                            "type": "string",
                            "nullable": true
                          },
                          "stripeRefundId": {
                            "type": "string",
                            "nullable": true
                          },
                          "stripeAccountId": {
                            "type": "string",
                            "nullable": true
                          },
                          "connectChargeType": {
                            "type": "string",
                            "nullable": true,
                            "enum": ["DIRECT"]
                          },
                          "failureCode": {
                            "type": "string",
                            "nullable": true
                          },
                          "failureMessage": {
                            "type": "string",
                            "nullable": true
                          },
                          "note": {
                            "type": "string",
                            "nullable": true
                          },
                          "disputeId": {
                            "type": "string",
                            "nullable": true,
                            "description": "The Stripe dispute (chargeback) id, when the client disputed this card payment with their bank. Set by MarketBox from Stripe's events, never by a request. The transaction's `status` stays SUCCEEDED while it is disputed."
                          },
                          "disputeStatus": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "needs_response",
                              "under_review",
                              "won",
                              "lost",
                              null
                            ],
                            "description": "Where the dispute stands: `needs_response` (evidence is due in Stripe), `under_review` (the bank is deciding), `won` (the money stays), or `lost` (the money was taken back). Null or absent when the payment was never disputed. An inquiry that closes without a chargeback reads `won`. Respond to a dispute in Stripe: the API cannot."
                          },
                          "channel": {
                            "type": "string",
                            "enum": [
                              "BACKOFFICE",
                              "OPEN_API",
                              "STRIPE_WEBHOOK",
                              "SCHEDULER",
                              "ORDER_CASCADE",
                              "MIGRATION"
                            ]
                          },
                          "reason": {
                            "type": "string",
                            "nullable": true
                          },
                          "deleted": {
                            "type": "boolean"
                          },
                          "version": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "createdBy": {
                            "type": "string"
                          },
                          "updatedBy": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "projectId",
                          "tenantId",
                          "transactionId",
                          "kind",
                          "source",
                          "status",
                          "amount",
                          "orderId",
                          "deleted",
                          "version",
                          "createdAt",
                          "updatedAt",
                          "createdBy",
                          "updatedBy"
                        ]
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": ["data", "nextCursor"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query/cursor",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/orders/{orderId}/payment-intent": {
      "post": {
        "tags": ["Transactions"],
        "summary": "Create a Stripe PaymentIntent for an order (client-side confirmation)",
        "description": "Starts a card payment for whatever the order still owes. Returns a `clientSecret` to confirm with Stripe.js in the browser — the card details never reach this API. The charge is created on the project's connected account for `total - amountPaid - amountComped`, so part-paid orders are billed only for the remainder and an order paid or comped in full is a 400.\n\nSafe to call more than once: an order has at most one open card payment. If its open intent can still be paid and is for the amount owed now, its existing `clientSecret` is returned instead of a second intent being created, so a user who reloads checkout is not charged twice. If the amount owed has changed since, the old intent is canceled and a new one is created for the new amount. While a card payment on the order is already moving (processing, or a saved-card charge in flight), the call is a 409 `PAYMENT_IN_FLIGHT`: wait for it to finish, then read the order's transactions.\n\nThe order must be DRAFT or PENDING; anything further along its lifecycle is a 400. A 409 means the project has no Stripe account connected or is not yet cleared to take charges, which is a setup problem no retry will fix. Confirming the intent does NOT settle the transaction here: the row stays PENDING until Stripe's webhook confirms it, so treat payment as complete only once the transaction reads SUCCEEDED.\n\nWhen the order's client has an email on file, the card is saved to that client for future bookings (the intent is created with `setup_future_usage: off_session`), so tell the client at checkout that their card will be saved. An intent reused from an earlier call is updated to save the card as well, provided the payment has not been confirmed yet.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The order — the commercial record. Order items are drawn down into bookings.",
              "example": "ord_01kv8m92p4jcrywn14znp8cym0"
            },
            "required": true,
            "description": "The order — the commercial record. Order items are drawn down into bookings.",
            "name": "orderId",
            "in": "path"
          }
        ],
        "responses": {
          "201": {
            "description": "PaymentIntent created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "clientSecret": {
                          "type": "string",
                          "minLength": 1
                        },
                        "paymentIntentId": {
                          "type": "string",
                          "minLength": 1
                        },
                        "transactionId": {
                          "type": "string",
                          "minLength": 1
                        },
                        "amount": {
                          "$ref": "#/components/schemas/Money"
                        }
                      },
                      "required": [
                        "clientSecret",
                        "paymentIntentId",
                        "transactionId",
                        "amount"
                      ]
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Nothing owed / invalid order state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "404": {
            "description": "Order not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "409": {
            "description": "Project not charge-ready, or a card payment on the order is already in progress (PAYMENT_IN_FLIGHT): wait for it to finish, then read the order’s transactions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    },
    "/v1/projects/{projectId}/events": {
      "post": {
        "tags": ["Events"],
        "summary": "Report what your site showed: rendered searches, lists, impressions, clicks, profile views",
        "description": "MarketBox runs the search; your site draws the results. Only your site knows which suppliers it actually put on the page, which cards reached the screen and which ones a client opened, so it reports them here and each supplier sees them in their Search insights. Send from your server, batched: every 10 seconds or at 500 events, whichever comes first. The API key needs the `events:write` capability, granted by name on the application in the dashboard (a key without it — including a legacy key or a `*` key — gets 403).\n\n**Event types.** `search.rendered`: the results of a MarketBox search were drawn (carry its `searchId` and the supplier ids drawn, in order, with their 0-based `position`). **This is what makes a search count**: a search with no render counts for nothing, not as Shown, not as Seen, not on the demand map. `opportunity`: any list that includes suppliers was drawn (home page, a city page, a widget), one per list render; an opportunity carrying a `searchId` counts as the render too. `impression`: a supplier's card was at least 50 % in the viewport for the first time in that list (`IntersectionObserver`, threshold 0.5); carries the opportunity's `eventId` as `listId`. `click`: the client opened a profile or card from a list; carries `impressionId` (or `listId` + `supplierId` when you do not track impressions). `profile_view`: a profile page loaded, from anywhere. `coverage_miss`: a client entered an address and your site found nobody without calling a MarketBox search.\n\n**Each event is validated on its own.** The response is always 202 with `accepted` and the `rejected` ones by index and code; a rejected event never fails the batch. The whole request fails only on auth (401/403), size (413: over 256 KB) or shape (400: no `events`, or over 500). `eventId` is your idempotency key: on a 429 or 5xx retry the same batch with the same ids and nothing is counted twice. `occurredAt` must be within 24 hours ahead and 72 hours back of receipt; a key holding `events:import` may send up to 400 days back (a back-fill), and those events are stored as imported. Give up on an event after 72 hours.\n\n**Privacy.** `sessionKey` is opaque and hashed by you — never an email, IP or user id. A place is sent as a resolution-8 H3 cell or as `lat`/`lng`; coordinates are reduced to the cell on receipt and never stored. `path` loses its query string. Supplier ids must belong to this project; `searchId`, `listId` and `impressionId` are stored as you sent them.\n\nAbout 50 requests a second per key are allowed, with bursts of 100; past that a 429 with `Retry-After`.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
              "example": "prj_01kv60qgnef2kt3pvqgwmkbzfr"
            },
            "required": true,
            "description": "The project (tenant) that owns the resource. Every resource in this API is scoped to a project, and your API key is restricted to the projects it was issued for — a project outside that scope returns 403.",
            "name": "projectId",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "description": "Default `sessionKey` for every event in the batch that has none: an opaque per-session key you hash yourself, at most 64 characters. A longer value is ignored, never an error."
            },
            "required": false,
            "description": "Default `sessionKey` for every event in the batch that has none: an opaque per-session key you hash yourself, at most 64 characters. A longer value is ignored, never an error.",
            "name": "x-mb-session-key",
            "in": "header"
          }
        ],
        "requestBody": {
          "description": "The batch of events",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SiteEventsBatch"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The batch was read: what was accepted and what was not",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiteEventsAccepted"
                }
              }
            }
          },
          "400": {
            "description": "Not a batch: no `events` array, or more than 500",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "403": {
            "description": "API key lacks `events:write` or cannot access this project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "413": {
            "description": "The body is over 256 KB; nothing was read",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests from this key; retry after a second",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          },
          "503": {
            "description": "MarketBox could not check or record the batch (a dependency was down); nothing was recorded. Retry the same batch after `Retry-After` seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorMessage"
                }
              }
            }
          }
        }
      }
    }
  }
}
