# List a regime's existing customers

> The registrations.affected_customers operation: GET /api/v1/registrations/{id}/affected_customers in the REST API and the registrations_affected_customers tool in the MCP server.

Lists the customers the legal entity has already charged tax under a registration's regime, in the mode of
the request, all brands combined, with their open liability. When a regime is blocked for new consumers
(`blocked_b2c`), these existing customers keep their renewals, top-ups and refunds, and their tax is still
charged and owed (spec §10.7).

For each customer: `pendingRegistration`, the tax charged before the entity registered
(`tax_pending_registration` in the ledger, net of refunds): the open liability; `chargedAsRegistered`, the
tax charged while registered; the regime's jurisdictions and the first and last sale. `email` and `name` are
shown only if you can read that brand's customers.

`summary` has the regime's open liability per jurisdiction (the ledger balances), the number of customers,
and pending amounts linked to no customer (`unattributed`). Customers are listed newest first; paginate with
`limit` (1–100, default 25) and `starting_after`.

## At a glance

- **REST:** `GET /api/v1/registrations/{id}/affected_customers`
- **MCP tool:** `registrations_affected_customers`
- **Operation ID:** `registrations.affected_customers`
- **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:** M7

## Request

### Path parameters

| Field | Type   | Description                                                                               |
| ----- | ------ | ----------------------------------------------------------------------------------------- |
| `id`  | string | The registration (`regn_…`) or its regime's ID, e.g. `EU_OSS_UNION` or `US_SALES_TAX:TX`. |

### Query parameters

| Field            | Type               | Required | Description                             |
| ---------------- | ------------------ | -------- | --------------------------------------- |
| `limit`          | integer (1 to 100) | No       | Page size, 1 to 100 (default 25).       |
| `starting_after` | `cus_…` 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[].object`                               | `"affected_customer"` |             |
| `data[].customerId`                           | `cus_…` ID            |             |
| `data[].brandId`                              | `brd_…` ID or null    |             |
| `data[].email`                                | string or null        |             |
| `data[].name`                                 | string or null        |             |
| `data[].deleted`                              | boolean               |             |
| `data[].jurisdictionIds`                      | array of string       |             |
| `data[].pendingRegistration`                  | array of money        |             |
| `data[].chargedAsRegistered`                  | array of money        |             |
| `data[].firstSaleAt`                          | date-time             |             |
| `data[].lastSaleAt`                           | date-time             |             |
| `data[].transactionCount`                     | integer (at least 0)  |             |
| `has_more`                                    | boolean               |             |
| `next_cursor`                                 | `cus_…` ID or null    |             |
| `registrationId`                              | `regn_…` ID           |             |
| `regimeId`                                    | string                |             |
| `summary`                                     | object                |             |
| `summary.customerCount`                       | integer (at least 0)  |             |
| `summary.customersWithOpenLiability`          | integer (at least 0)  |             |
| `summary.openLiability`                       | array of object       |             |
| `summary.openLiability[].jurisdictionId`      | string                |             |
| `summary.openLiability[].pendingRegistration` | money                 |             |
| `summary.openLiabilityTotal`                  | array of money        |             |
| `summary.unattributed`                        | array of money        |             |

## Examples

### Two consumers of a blocked OSS registration

```http
GET /api/v1/registrations/EU_OSS_NON_UNION/affected_customers
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "object": "list",
  "data": [
    {
      "object": "affected_customer",
      "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47xs",
      "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
      "email": "lena@example.de",
      "name": "Lena Schmidt",
      "deleted": false,
      "jurisdictionIds": ["DE"],
      "pendingRegistration": [
        {
          "amount": "3800000",
          "currency": "EUR"
        }
      ],
      "chargedAsRegistered": [],
      "firstSaleAt": "2026-10-14T09:30:00.000Z",
      "lastSaleAt": "2026-10-14T09:30:00.000Z",
      "transactionCount": 1
    },
    {
      "object": "affected_customer",
      "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47xr",
      "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
      "email": "marie@example.fr",
      "name": null,
      "deleted": false,
      "jurisdictionIds": ["FR"],
      "pendingRegistration": [
        {
          "amount": "7980000",
          "currency": "EUR"
        }
      ],
      "chargedAsRegistered": [],
      "firstSaleAt": "2026-10-15T10:02:11.000Z",
      "lastSaleAt": "2026-11-15T10:02:13.000Z",
      "transactionCount": 2
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47xk",
  "regimeId": "EU_OSS_NON_UNION",
  "summary": {
    "customerCount": 2,
    "customersWithOpenLiability": 2,
    "openLiability": [
      {
        "jurisdictionId": "DE",
        "pendingRegistration": {
          "amount": "3800000",
          "currency": "EUR"
        }
      },
      {
        "jurisdictionId": "FR",
        "pendingRegistration": {
          "amount": "7980000",
          "currency": "EUR"
        }
      }
    ],
    "openLiabilityTotal": [
      {
        "amount": "11780000",
        "currency": "EUR"
      }
    ],
    "unattributed": []
  }
}
```

## Errors

| Code                                                                                     | HTTP status | When                                                                       | What to do                                                                                                                                         |
| ---------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed)   | 400         | `id`, `limit` or `starting_after` is malformed.                            | Fix the fields listed in `details.issues` and send the request again.                                                                              |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404         | This entity has no such registration in this mode.                         | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.                                               |
| [`scope_required`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#permission_denied)   | 403         | You can't see this entity's registrations.                                 | Ask an organization owner or admin for a role or scope that allows this action.                                                                    |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).