Get a customer · Ownrecord docs

Returns a customer of the brand in the mode of the request: profile, inferred and declared type, billing address, tax IDs with their latest check and earlier checks, the locked tax country (set at the first successful payment, spec §9.3), processor references and risk. Deleted customers are returned too, with deletedAt. The customer's location evidence is listed by customers.evidence_sets.list.

At a glance

REST: GET /api/v1/customers/{id}
MCP tool: customers_get
Operation ID: customers.get
Scope: Brand
Permission: customers:read
Risk tier: read
Dry run: Not supported
Idempotency: Not needed (read only)
Modes: Test and live
Authentication: API key with the customers:read scope
Since: M4

Request

Path parameters

Field	Type	Description
`id`	`cus_…` ID	The customer's ID (`cus_…`).

Query parameters

This operation takes no query parameters.

Response

200 OK with a JSON object:

Field	Type	Description
`id`	`cus_…` ID
`object`	`"customer"`
`livemode`	boolean
`entityId`	`ent_…` ID
`brandId`	`brd_…` ID
`email`	string
`name`	string or null
`businessName`	string or null
`locale`	string or null
`type`	one of `individual`, `business`, `unknown`	Inferred (spec §13.1): `business` with a tax ID that isn't rejected, or with a business name when declared a business. Tax is decided per sale: only a `valid` tax ID makes a sale business-to-business.
`declaredType`	one of `individual`, `business`, `unknown`	What you declared.
`billingAddress`	object or null
`taxIds`	array of object
`taxIds[].id`	string	Identifies the tax ID on the customer: its canonical number, e.g. `ATU12345678`.
`taxIds[].type`	string	`eu_vat`, `gb_vat`, `ch_uid`/`ch_vat`, `no_org`/`no_vat`, `us_ein`, or another type (unverified).
`taxIds[].value`	string	The number as given.
`taxIds[].country`	string
`taxIds[].number`	string or null	The canonical number (null for types Ownrecord can't check).
`taxIds[].verification`	object	The latest check (spec §9.4).
`taxIds[].verification.status`	one of `valid`, `invalid`, `unavailable`, `format_only`, `unverified`	`valid`, `invalid`, `unavailable` (the register couldn't answer), `format_only` (no register: format and checksum) or `unverified` (a type Ownrecord can't check).
`taxIds[].verification.source`	string	Who decided: VIES, HMRC, CH_UID, FORMAT (format and checksum only) or NONE.
`taxIds[].verification.reason`	string or null	Why, e.g. `not_registered` or `service_unavailable`.
`taxIds[].verification.checkedAt`	date-time
`taxIds[].verification.consultationNumber`	string or null	The register's proof of the check (VIES request identifier, HMRC consultation number).
`taxIds[].verification.simulated`	boolean	A fixture answer (development and test environments), not a register's.
`taxIds[].history`	array of object	Earlier checks, newest first (at most 10).
`taxIds[].history[].status`	one of `valid`, `invalid`, `unavailable`, `format_only`, `unverified`	`valid`, `invalid`, `unavailable` (the register couldn't answer), `format_only` (no register: format and checksum) or `unverified` (a type Ownrecord can't check).
`taxIds[].history[].source`	string	Who decided: VIES, HMRC, CH_UID, FORMAT (format and checksum only) or NONE.
`taxIds[].history[].reason`	string or null	Why, e.g. `not_registered` or `service_unavailable`.
`taxIds[].history[].checkedAt`	date-time
`taxIds[].history[].consultationNumber`	string or null	The register's proof of the check (VIES request identifier, HMRC consultation number).
`taxIds[].history[].simulated`	boolean	A fixture answer (development and test environments), not a register's.
`taxIds[].addedAt`	date-time
`taxCountryLocked`	object or null	Where the customer's purchases are taxed (spec §9.3): set at the first successful payment, moved only when a top-up's evidence resolves to another country.
`taxExempt`	object or null	Tax exemption (spec §9.5). Not applied yet: exemption certificates come in a later release.
`processorRefs`	array of object	The customer at each payment processor used (set by checkout).
`processorRefs[].processorConnectionId`	`pcon_…` ID
`processorRefs[].customerRef`	string
`risk`	object
`risk.level`	one of `normal`, `elevated`, `blocked`
`risk.reasons`	array of string
`risk.firstPaymentAt`	date-time or null
`risk.totalPaid`	money
`portalLastLoginAt`	date-time or null
`testClockId`	`clk_…` ID or null	Test mode: the test clock the customer was created on (spec §16.13).
`metadata`	object
`createdAt`	date-time
`updatedAt`	date-time
`deletedAt`	date-time or null	When the customer was deleted (soft delete); null while active.

Examples

A business customer

HTTP

GET /api/v1/customers/cus_01m4ty3c2b5qx7mhd9k8w6s0aa
Authorization: Bearer or_test_…

Response (200):

JSON

{
  "id": "cus_01m4ty3c2b5qx7mhd9k8w6s0aa",
  "object": "customer",
  "livemode": false,
  "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "email": "billing@alpenapps.example",
  "name": "Lena Huber",
  "businessName": "Alpen Apps GmbH",
  "locale": "de-AT",
  "type": "business",
  "declaredType": "business",
  "billingAddress": {
    "line1": "Mariahilfer Straße 1",
    "line2": null,
    "city": "Wien",
    "postalCode": "1060",
    "region": null,
    "country": "AT"
  },
  "taxIds": [
    {
      "id": "ATU00000000",
      "type": "eu_vat",
      "value": "ATU 0000 0000",
      "country": "AT",
      "number": "ATU00000000",
      "verification": {
        "status": "valid",
        "source": "VIES",
        "reason": null,
        "checkedAt": "2026-10-14T09:00:00.000Z",
        "consultationNumber": "WAPIAAAAZ1x2y3",
        "simulated": false
      },
      "history": [],
      "addedAt": "2026-10-14T09:00:00.000Z"
    }
  ],
  "taxCountryLocked": null,
  "taxExempt": null,
  "processorRefs": [],
  "risk": {
    "level": "normal",
    "reasons": [],
    "firstPaymentAt": null,
    "totalPaid": {
      "amount": "0",
      "currency": "EUR"
    }
  },
  "portalLastLoginAt": null,
  "testClockId": null,
  "metadata": {
    "userId": "u_4821"
  },
  "createdAt": "2026-10-14T09:00:00.000Z",
  "updatedAt": "2026-10-14T09:00:00.000Z",
  "deletedAt": null
}

A consumer after the first payment

The first payment locked the tax country to Germany.

HTTP

GET /api/v1/customers/cus_01m4ty3c2b5qx7mhd9k8w6s0ab
Authorization: Bearer or_test_…

Response (200):

JSON

{
  "id": "cus_01m4ty3c2b5qx7mhd9k8w6s0ab",
  "object": "customer",
  "livemode": false,
  "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "email": "ana@example.com",
  "name": "Ana Schmidt",
  "businessName": null,
  "locale": "de",
  "type": "individual",
  "declaredType": "individual",
  "billingAddress": {
    "line1": null,
    "line2": null,
    "city": null,
    "postalCode": null,
    "region": null,
    "country": "DE"
  },
  "taxIds": [],
  "taxCountryLocked": {
    "country": "DE",
    "subdivision": null,
    "lockedAt": "2026-10-14T09:30:00.000Z",
    "evidenceSetId": "evs_01m4ty3c2b5qx7mhd9k8w6s0ac"
  },
  "taxExempt": null,
  "processorRefs": [
    {
      "processorConnectionId": "pcon_01m4ty3c2b5qx7mhd9k8w6s0af",
      "customerRef": "cus_QxY12AbC"
    }
  ],
  "risk": {
    "level": "normal",
    "reasons": [],
    "firstPaymentAt": "2026-10-14T09:30:00.000Z",
    "totalPaid": {
      "amount": "119000000",
      "currency": "EUR"
    }
  },
  "portalLastLoginAt": null,
  "testClockId": null,
  "metadata": {},
  "createdAt": "2026-10-14T09:00:00.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z",
  "deletedAt": null
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	`id` isn't a customer ID (`cus_…`).	Fix the fields listed in `details.issues` and send the request again.
`resource_not_found`	404	This brand has no such customer in this mode (customers belong to one brand and one mode).	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`scope_required`	400	The request names no brand (an org or entity key without `Ownrecord-Brand`).	Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`).
`livemode_not_allowed`	403	You have no live-mode access, so you can't act on live customers.	Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin.
`permission_denied`	403	You can't read this brand's customers (`customers:read`).	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#

Path parameters#

Query parameters#

Response#

Examples#

A business customer#

A consumer after the first payment#

Errors#