List registrations · Ownrecord docs

Lists the legal entity's registrations in the mode of the request, newest first: one per tax regime of the tax knowledge (spec §10.8), created with the entity in both modes (test mode starts as a copy of live mode), each in its state (registered, grace, pre_registration, monitored, blocked_b2c, …) with its deadlines and threshold position. Filter by state.

Each registration has its state and stateReason, the grace deadlineAt and autoBlockAt (when new consumer sales stop automatically unless the application is submitted), the prerequisites progress, and the threshold position: what the entity sold toward the regime's threshold, all brands combined, with percent of the threshold reached.

States: registered, grace, monitored, pre_registration, blocked_b2c (armed: true when the first consumer sale will start the grace period), not_applicable and deregistered. Filter by state. Paginate with limit (1–100, default 10) and starting_after (the next_cursor of the previous page).

At a glance

REST: GET /api/v1/registrations
MCP tool: registrations_list
Operation ID: registrations.list
Scope: Legal entity
Permission: registrations:read
Risk tier: read
Dry run: Not supported
Idempotency: Not needed (read only)
Modes: Test and live
Pagination: limit (at most 100) and starting_after
Authentication: API key with the registrations:read scope
Since: M3

Request

Query parameters

Field	Type	Required	Description
`state`	one of `not_applicable`, `monitored`, `pre_registration`, `grace`, `registered`, `blocked_b2c`, `deregistered` or array of one of `not_applicable`, `monitored`, `pre_registration`, `grace`, `registered`, `blocked_b2c`, `deregistered`	No	Only registrations in this state (or these states).
`limit`	integer (1 to 100)	No	Page size, 1 to 100 (default 10).
`starting_after`	`regn_…` ID	No	The `next_cursor` of the previous page.

Response

200 OK with a JSON object, a page of the list (newest first):

Field	Type	Description
`object`	`"list"`
`data`	array of object
`data[].id`	`regn_…` ID
`data[].object`	`"registration"`
`data[].entityId`	`ent_…` ID
`data[].livemode`	boolean
`data[].regimeId`	string
`data[].regimeName`	string or null
`data[].jurisdictionIds`	array of string
`data[].state`	one of `not_applicable`, `monitored`, `pre_registration`, `grace`, `registered`, `blocked_b2c`, `deregistered`
`data[].stateReason`	one of 18 values, e.g. `home_country`, `below_threshold`, `zero_threshold` (all in the OpenAPI document)
`data[].stateChangedAt`	date-time
`data[].armed`	boolean
`data[].triggeredAt`	date-time or null
`data[].deadlineAt`	date-time or null
`data[].autoBlockAt`	date-time or null
`data[].applicationSubmittedAt`	date-time or null
`data[].escalationLevel`	integer (0 to 3)
`data[].registrationNumber`	string or null
`data[].effectiveFrom`	date-time or null
`data[].registeredAt`	date-time or null
`data[].prerequisitesDone`	boolean
`data[].prerequisitesProgress`	object
`data[].prerequisitesProgress.done`	integer
`data[].prerequisitesProgress.total`	integer
`data[].threshold`	object or null
`data[].timeZones`	array of string
`data[].createdAt`	date-time
`data[].updatedAt`	date-time
`has_more`	boolean
`next_cursor`	`regn_…` ID or null

Examples

Registrations near or over a threshold

HTTP

GET /api/v1/registrations?state=pre_registration&state=grace&limit=10
Authorization: Bearer or_test_…

Response (200):

JSON

{
  "object": "list",
  "data": [
    {
      "id": "regn_01m4tx5nj8emwbyf7y9vcf47xk",
      "object": "registration",
      "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
      "livemode": true,
      "regimeId": "EU_OSS_UNION",
      "regimeName": "EU One-Stop Shop, Union scheme",
      "jurisdictionIds": ["AT", "DE", "FR", "HR", "IT", "NL"],
      "state": "pre_registration",
      "stateReason": "pre_registration_ratio_reached",
      "stateChangedAt": "2026-10-13T12:00:00.000Z",
      "armed": false,
      "triggeredAt": null,
      "deadlineAt": null,
      "autoBlockAt": null,
      "applicationSubmittedAt": null,
      "escalationLevel": 0,
      "registrationNumber": null,
      "effectiveFrom": null,
      "registeredAt": null,
      "prerequisitesDone": true,
      "prerequisitesProgress": {
        "done": 1,
        "total": 1
      },
      "threshold": {
        "status": "below",
        "window": "calendar_year_current_or_previous",
        "measure": "eu_cross_border_b2c",
        "currentWindow": "2026",
        "previousWindow": "2025",
        "threshold": {
          "amount": "10000000000",
          "currency": "EUR"
        },
        "current": {
          "amount": "8500000000",
          "currency": "EUR"
        },
        "previous": {
          "amount": "0",
          "currency": "EUR"
        },
        "transactionThreshold": null,
        "currentTransactions": null,
        "previousTransactions": null,
        "worldwideTurnoverDeclared": null,
        "ratioPpm": "850000",
        "percent": 85,
        "detail": "8500.00 EUR counted (earlier window 0.00) against 10000.00 EUR"
      },
      "timeZones": ["Europe/Zagreb"],
      "createdAt": "2026-10-13T12:00:00.000Z",
      "updatedAt": "2026-10-13T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Every registration, first page

HTTP

GET /api/v1/registrations?limit=2
Authorization: Bearer or_test_…

Response (200):

JSON

{
  "object": "list",
  "data": [
    {
      "id": "regn_01m4tx5nj8emwbyf7y9vcf47xk",
      "object": "registration",
      "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
      "livemode": true,
      "regimeId": "EU_OSS_UNION",
      "regimeName": "EU One-Stop Shop, Union scheme",
      "jurisdictionIds": ["AT", "DE", "FR", "HR", "IT", "NL"],
      "state": "pre_registration",
      "stateReason": "pre_registration_ratio_reached",
      "stateChangedAt": "2026-10-13T12:00:00.000Z",
      "armed": false,
      "triggeredAt": null,
      "deadlineAt": null,
      "autoBlockAt": null,
      "applicationSubmittedAt": null,
      "escalationLevel": 0,
      "registrationNumber": null,
      "effectiveFrom": null,
      "registeredAt": null,
      "prerequisitesDone": true,
      "prerequisitesProgress": {
        "done": 1,
        "total": 1
      },
      "threshold": {
        "status": "below",
        "window": "calendar_year_current_or_previous",
        "measure": "eu_cross_border_b2c",
        "currentWindow": "2026",
        "previousWindow": "2025",
        "threshold": {
          "amount": "10000000000",
          "currency": "EUR"
        },
        "current": {
          "amount": "8500000000",
          "currency": "EUR"
        },
        "previous": {
          "amount": "0",
          "currency": "EUR"
        },
        "transactionThreshold": null,
        "currentTransactions": null,
        "previousTransactions": null,
        "worldwideTurnoverDeclared": null,
        "ratioPpm": "850000",
        "percent": 85,
        "detail": "8500.00 EUR counted (earlier window 0.00) against 10000.00 EUR"
      },
      "timeZones": ["Europe/Zagreb"],
      "createdAt": "2026-10-13T12:00:00.000Z",
      "updatedAt": "2026-10-13T12:00:00.000Z"
    },
    {
      "id": "regn_01m4tx5nj8emwbyf7y9vcf47xm",
      "object": "registration",
      "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
      "livemode": true,
      "regimeId": "HR_DOMESTIC",
      "regimeName": "Croatia, domestic VAT",
      "jurisdictionIds": ["HR"],
      "state": "registered",
      "stateReason": "home_country",
      "stateChangedAt": "2026-10-13T12:00:00.000Z",
      "armed": false,
      "triggeredAt": null,
      "deadlineAt": null,
      "autoBlockAt": null,
      "applicationSubmittedAt": null,
      "escalationLevel": 0,
      "registrationNumber": "HR12345678901",
      "effectiveFrom": null,
      "registeredAt": null,
      "prerequisitesDone": false,
      "prerequisitesProgress": {
        "done": 0,
        "total": 2
      },
      "threshold": null,
      "timeZones": ["Europe/Zagreb"],
      "createdAt": "2026-10-13T12:00:00.000Z",
      "updatedAt": "2026-10-13T12:00:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "regn_01m4tx5nj8emwbyf7y9vcf47xm"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	A filter or the page size is malformed (`details.issues`).	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`).
`permission_denied`	403	You can't see this entity's registrations (brand-scoped members never can).	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, resource_not_found, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Query parameters#

Response#

Examples#

Registrations near or over a threshold#

Every registration, first page#

Errors#