List the entity's demand by jurisdiction

Where the legal entity's brands can't sell to consumers yet, and what it would take: one row per customer-location jurisdiction with waitlist entries or blocked checkouts, all brands combined, in the mode of the request (spec §23).

Each row has the waitlist by stage (waiting, pending, notified, left) and the waiting entries' estimatedMonthlyValue per currency (recurring prices per month; one-time prices and credit packs counted once, as a first month's purchase); the checkouts paused there in the window (blockedCheckouts, by reason); and the regimes that apply there: the entity's registration state, the prerequisites with their lead times and status, leadTimeDays (the longest lead time of what isn't done) and the compliance effort (a fiscal representative, a local agent, the filing frequency). brands splits the counts per brand; they add up to the row. Counts and sums only: no customer is named.

Sort by waitlist, monthly_value (EUR equivalent), blocked_checkouts, lead_time or jurisdiction; brand limits every count to one brand of the entity. Callers who can't read registrations get the knowledge base's side only (registrationsVisible: false).

At a glance

REST: GET /api/v1/waitlist/demand
MCP tool: waitlist_demand_list
Operation ID: waitlist.demand.list
Scope: Legal entity
Permission: waitlist:read
Risk tier: read
Dry run: Not supported
Idempotency: Not needed (read only)
Modes: Test and live
Authentication: API key with the waitlist:read scope
Since: M7

Request

Query parameters

Field	Type	Required	Description
`months`	integer (1 to 36)	No	The window for blocked checkouts: this calendar month and the ones before it (1–36, default 12).
`sort`	one of `jurisdiction`, `waitlist`, `monthly_value`, `blocked_checkouts`, `lead_time`	No	`waitlist` (waiting entries), `monthly_value` (EUR equivalent), `blocked_checkouts`, `lead_time` or `jurisdiction`.
`order`	one of `asc`, `desc`	No
`brand`	`brd_…` ID	No	Only this brand of the entity (`brd_…`); all brands when absent.

Response

200 OK with a JSON object:

Field	Type	Description
`object`	`"entity_demand"`
`entityId`	`ent_…` ID
`livemode`	boolean
`window`	object
`window.months`	integer (at least 1)
`window.from`	string
`window.to`	string
`sort`	one of `jurisdiction`, `waitlist`, `monthly_value`, `blocked_checkouts`, `lead_time`
`order`	one of `asc`, `desc`
`brand`	`brd_…` ID or null	The brand filter, or null for every brand.
`brands`	array of object	The entity's brands (the split's names and the filter's choices).
`brands[].id`	`brd_…` ID
`brands[].name`	string
`brands[].slug`	string
`registrationsVisible`	boolean	False when you can't read registrations: `registration` and prerequisite statuses are null.
`fxRateDate`	string or null
`data`	array of object
`data[].jurisdiction`	string	The customer-location jurisdiction: `GB`, `US-TX`, a territory's code.
`data[].name`	string or null
`data[].territoryOf`	string or null
`data[].waitlist`	object
`data[].waitlist.waiting`	integer (at least 0)	Confirmed entries waiting for the brand to be able to sell there.
`data[].waitlist.pending`	integer (at least 0)	Entries whose email isn't confirmed yet.
`data[].waitlist.notified`	integer (at least 0)	Entries told once that the brand can sell there.
`data[].waitlist.left`	integer (at least 0)	Entries whose customer left the waitlist.
`data[].waitlist.estimatedMonthlyValue`	object	What the waiting entries wanted to buy, per month and currency.
`data[].waitlist.estimatedMonthlyValue.total`	array of money
`data[].waitlist.estimatedMonthlyValue.recurring`	array of money	Recurring prices, per month.
`data[].waitlist.estimatedMonthlyValue.oneTime`	array of money	One-time prices and credit packs, counted once (as a first month's purchase).
`data[].blockedCheckouts`	object
`data[].blockedCheckouts.total`	integer (at least 0)	Checkouts paused there in the window (once per session and reason).
`data[].blockedCheckouts.registrationRequired`	integer (at least 0)
`data[].blockedCheckouts.jurisdictionBlocked`	integer (at least 0)
`data[].blockedCheckouts.other`	integer (at least 0)	Other reasons, e.g. unclear location evidence.
`data[].monthlyValueEur`	money or null	The estimated monthly value in EUR at the ECB rates of `fxRateDate` (for sorting).
`data[].leadTimeDays`	integer or null	The longest lead time of the row's regimes.
`data[].regimes`	array of object	The regimes that apply there and the registration.
`data[].regimes[].regimeId`	string
`data[].regimes[].name`	string or null
`data[].regimes[].registration`	object or null	The entity's registration; null when it has none, or you can't read registrations.
`data[].regimes[].prerequisites`	array of object
`data[].regimes[].prerequisites[].code`	string
`data[].regimes[].prerequisites[].description`	string or null
`data[].regimes[].prerequisites[].leadTimeDays`	integer or null
`data[].regimes[].prerequisites[].status`	one of `todo`, `in_progress`, `done` or null
`data[].regimes[].leadTimeDays`	integer or null	The longest lead time of the prerequisites not done yet (0 when all are done).
`data[].regimes[].typicalProcessingDays`	integer or null
`data[].regimes[].effort`	object
`data[].regimes[].effort.fiscalRepresentative`	boolean or null
`data[].regimes[].effort.localAgent`	boolean or null
`data[].regimes[].effort.filingFrequency`	one of `monthly`, `quarterly`, `annual`, `varies` or null
`data[].brands`	array of object	The same counts per brand with a signal there; they add up to the row.
`data[].brands[].brandId`	`brd_…` ID
`data[].brands[].waitlist`	object
`data[].brands[].waitlist.waiting`	integer (at least 0)	Confirmed entries waiting for the brand to be able to sell there.
`data[].brands[].waitlist.pending`	integer (at least 0)	Entries whose email isn't confirmed yet.
`data[].brands[].waitlist.notified`	integer (at least 0)	Entries told once that the brand can sell there.
`data[].brands[].waitlist.left`	integer (at least 0)	Entries whose customer left the waitlist.
`data[].brands[].waitlist.estimatedMonthlyValue`	object	What the waiting entries wanted to buy, per month and currency.
`data[].brands[].blockedCheckouts`	object
`data[].brands[].blockedCheckouts.total`	integer (at least 0)	Checkouts paused there in the window (once per session and reason).
`data[].brands[].blockedCheckouts.registrationRequired`	integer (at least 0)
`data[].brands[].blockedCheckouts.jurisdictionBlocked`	integer (at least 0)
`data[].brands[].blockedCheckouts.other`	integer (at least 0)	Other reasons, e.g. unclear location evidence.

Examples

Live demand over 12 months

HTTP

GET /api/v1/waitlist/demand
Authorization: Bearer or_test_…

Response (200):

JSON

{
  "object": "entity_demand",
  "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
  "livemode": true,
  "window": {
    "months": 12,
    "from": "2025-11-01",
    "to": "2026-10-20"
  },
  "sort": "waitlist",
  "order": "desc",
  "brand": null,
  "brands": [
    {
      "id": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
      "name": "Genno",
      "slug": "genno"
    },
    {
      "id": "brd_01m4tx5nj8emwbyf7y9vcf47x5",
      "name": "Genno Pro",
      "slug": "genno-pro"
    }
  ],
  "registrationsVisible": true,
  "fxRateDate": "2026-10-16",
  "data": [
    {
      "jurisdiction": "GB",
      "name": "United Kingdom",
      "territoryOf": null,
      "waitlist": {
        "waiting": 12,
        "pending": 2,
        "notified": 0,
        "left": 0,
        "estimatedMonthlyValue": {
          "total": [
            {
              "amount": "485000000",
              "currency": "EUR"
            }
          ],
          "recurring": [
            {
              "amount": "365000000",
              "currency": "EUR"
            }
          ],
          "oneTime": [
            {
              "amount": "120000000",
              "currency": "EUR"
            }
          ]
        }
      },
      "blockedCheckouts": {
        "total": 37,
        "registrationRequired": 37,
        "jurisdictionBlocked": 0,
        "other": 0
      },
      "monthlyValueEur": {
        "amount": "485000000",
        "currency": "EUR"
      },
      "leadTimeDays": 21,
      "regimes": [
        {
          "regimeId": "GB_VAT_NETP",
          "name": "UK VAT for non-established sellers",
          "registration": {
            "state": "blocked_b2c",
            "armed": false,
            "stateReason": "zero_threshold"
          },
          "prerequisites": [
            {
              "code": "gateway_account",
              "description": "Open a Government Gateway account",
              "leadTimeDays": 10,
              "status": "done"
            },
            {
              "code": "uk_agent",
              "description": "Appoint a UK tax agent",
              "leadTimeDays": 21,
              "status": "todo"
            }
          ],
          "leadTimeDays": 21,
          "typicalProcessingDays": 30,
          "effort": {
            "fiscalRepresentative": false,
            "localAgent": false,
            "filingFrequency": "quarterly"
          }
        }
      ],
      "brands": [
        {
          "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
          "waitlist": {
            "waiting": 9,
            "pending": 1,
            "notified": 0,
            "left": 0,
            "estimatedMonthlyValue": {
              "total": [
                {
                  "amount": "410000000",
                  "currency": "EUR"
                }
              ],
              "recurring": [
                {
                  "amount": "290000000",
                  "currency": "EUR"
                }
              ],
              "oneTime": [
                {
                  "amount": "120000000",
                  "currency": "EUR"
                }
              ]
            }
          },
          "blockedCheckouts": {
            "total": 31,
            "registrationRequired": 31,
            "jurisdictionBlocked": 0,
            "other": 0
          }
        },
        {
          "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x5",
          "waitlist": {
            "waiting": 3,
            "pending": 1,
            "notified": 0,
            "left": 0,
            "estimatedMonthlyValue": {
              "total": [
                {
                  "amount": "75000000",
                  "currency": "EUR"
                }
              ],
              "recurring": [
                {
                  "amount": "75000000",
                  "currency": "EUR"
                }
              ],
              "oneTime": []
            }
          },
          "blockedCheckouts": {
            "total": 6,
            "registrationRequired": 6,
            "jurisdictionBlocked": 0,
            "other": 0
          }
        }
      ]
    }
  ]
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	The window, the sort or the brand is malformed.	Fix the fields listed in `details.issues` and send the request again.
`scope_required`	400	The request names no legal entity (an org key without `Ownrecord-Entity`).	Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`).
`resource_not_found`	404	The `brand` filter isn't a brand of this entity.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`permission_denied`	403	You can't read this entity's waitlist (brand-scoped members never can: the page combines brands).	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, authentication_required, api_key_invalid, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Query parameters#

Response#

Examples#

Live demand over 12 months#

Errors#