---
title: "Customers"
description: "Create and manage buyer profiles for repeat purchases, saved payment methods, and customer service."
canonical: "https://studio.inttegro.com/api/customers"
format: inttegro-machine-docs/v1
language: "PHP"
sdk_version: "v12.0.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/php/readers/index.json"
reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations."
preamble_estimated_tokens: 691
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "general"
recommended_mcp_tools: ["get_customer","get_customer_analytics","update_customer"]
estimated_tokens: 7349
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Create and manage buyer profiles for repeat purchases, saved payment methods, and customer service. This PHP representation uses the selected SDK's native names wherever Studio has a verified mapping.

### Five questions

#### Q1. When should the reader use Customers?

Use this API reference when exact operations, fields, states, or errors are required.

#### Q2. What is authoritative on this page?

Types and enum members link to pinned SDK references; a response field may link only to its containing type. A “wire-only” request field is not a verified native SDK member.

#### Q3. What page-specific constraint matters most?

Prioritize the machine-only guidance “Choose one durable customer identity for repeat activity”: Create a customer before checkout when the buyer should be recognized across orders or own a reusable payment method. Persist the returned customer ID in your system. Inline customer data on order creation produces a guest customer. If…

#### Q4. Can Inttegro MCP materially help with this task?

Yes, when the reader has an authenticated MCP connection and the task needs live context, guided planning, or a supported operation. The strongest matches are `get_customer`, `get_customer_analytics`, `update_customer`; their exact roles and boundaries are listed below.

#### Q5. How should the reader verify the answer and continue?

For a read, compare the returned resource with the requested identifier and scope. For a write, preserve its identifier and retrieve authoritative current state before declaring the business outcome complete. Continue with [Custom data](https://studio.inttegro.com/machine/php/api/custom-data.md) and [payment method](https://studio.inttegro.com/machine/php/api/payment-methods.md) when those concerns enter scope.

### Recommended MCP assistance

Use these through an authenticated Inttegro MCP connection. This document remains the contract source.

- [`get_customer`](https://studio.inttegro.com/machine/php/inttegro-mcp/tools.md#get_customer) — read; no mutation confirmation. Gets one customer by ID using a minimized projection that reports channel availability without exposing raw contact details.
- [`get_customer_analytics`](https://studio.inttegro.com/machine/php/inttegro-mcp/tools.md#get_customer_analytics) — analytics read; no mutation confirmation. Ranks customers or inspects one customer by paid orders and gross revenue, alongside the exact new-customer count for the period.
- [`update_customer`](https://studio.inttegro.com/machine/php/inttegro-mcp/tools.md#update_customer) — action; exact user confirmation required. Updates selected customer identity, contact, or delivery fields without returning raw contact or address data.

## Document content

# Customers

Customers represent the people and businesses that buy from you. A customer record keeps a buyer's name, contact details, addresses, and your own reference together, giving you a stable identity to use across purchases.

Use a customer when you expect a buyer to return, want to save a payment method, or need a consistent view of their account history. Attach the returned customer ID to future orders and payment methods so activity for the same buyer remains connected.

You can also provide customer details directly when you [create an order](https://studio.inttegro.com/machine/php/api/orders.md#create-an-order). Inttegro creates a guest customer for that checkout; update the customer later if the buyer chooses to create an account or return for another purchase. See [Manage customers](https://studio.inttegro.com/machine/php/guides/manage-customers.md) for the complete integration flow.

## Choose one durable customer identity for repeat activity

- Create a customer before checkout when the buyer should be recognized across
  orders or own a reusable [payment method](https://studio.inttegro.com/machine/php/api/payment-methods.md). Persist the
  returned customer ID in your system.
- Inline customer data on order creation produces a guest customer. If that
  buyer later becomes known, update the guest record instead of creating a
  second identity for the same checkout history.
- Customer lookup returns the profile and customer-held balances, not the
  customer's orders or saved payment methods. Query those resources separately
  with the same customer ID.
- A customer fingerprint is comparable only inside the same application. It is
  duplicate-detection evidence, not an API identifier, and may change when
  Inttegro gains stronger identity evidence. Continue to use the customer ID for
  every API operation.
- Treat each balance entry's timestamp as its freshness boundary. Do not assume
  a customer balance reflects activity after that point.

## The customer object

A customer object contains a buyer's profile and current customer-held balances. Orders and payment methods are separate resources: use the customer ID to associate them with the same buyer.

### Properties

- [`balance`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — required

  Always-present map of customer-held balances by currency. The map is empty when the customer has no balance entries.

  - [`balance.<currency>`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `object`

    Balance entry keyed by lowercase, three-letter ISO 4217 currency code, such as `'ghs'`.

    - [`balance.<currency>.as_of`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `timestamp`

      Point in time represented by this balance entry. Later customer balance activity may not yet be reflected.

    - [`balance.<currency>.available`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `object`

      Amount available for the customer in this currency.

      - [`balance.<currency>.available.currency`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

        Lowercase ISO 4217 currency code for the balance entry.

      - [`balance.<currency>.available.value`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `integer`

        Available amount in the currency's smallest unit.

- [`billing_address`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html)

  Billing address saved on the customer when available.

  - [`billing_address.city`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

    City or town.

  - [`billing_address.country`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

    Country identifier. A two-letter ISO 3166-1 code, such as `'GH'`.

  - [`billing_address.line1`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

    Street address line 1.

  - [`billing_address.line2`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

    Street address line 2.

  - [`billing_address.name`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

    Recipient name for this address.

  - [`billing_address.phone_number`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

    Contact phone number for this address.

  - [`billing_address.post_code`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

    Postal or ZIP code.

  - [`billing_address.region`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

    State, province, or region.

- [`created_at`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `timestamp` — required

  When the customer record was created.

- [`custom_data`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `object`

  Your own key-value metadata. Response values are strings. This property is
  omitted when no custom data has been stored.

- [`email_address`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

  Customer email address when one has been provided.

- [`fingerprint`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string` — required

  Use this application-scoped value to spot possible duplicate customer
  records. When two fingerprints match within the same application, the
  records likely belong to the same buyer. Compare fingerprints only within
  that application, and continue to use each customer ID for API operations.

- [`guest`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `boolean` — required

  `true` when checkout created the customer from inline
  customer data. Updating the customer changes this to
  `false`.

- [`id`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string` — required

  Application-scoped identifier with the `cu_` prefix.

- [`name`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string` — required

  Customer full name.

- [`phone_number`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

  Customer phone number when one has been provided.

- [`reference`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

  Your own external reference for the customer.

- [`shipping_address`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html)

  Shipping address saved on the customer when available.

  - [`shipping_address.city`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

    City or town.

  - [`shipping_address.country`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

    Country identifier. A two-letter ISO 3166-1 code, such as `'GH'`.

  - [`shipping_address.line1`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

    Street address line 1.

  - [`shipping_address.line2`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

    Street address line 2.

  - [`shipping_address.name`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

    Recipient name for this address.

  - [`shipping_address.phone_number`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

    Contact phone number for this address.

  - [`shipping_address.post_code`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

    Postal or ZIP code.

  - [`shipping_address.region`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

    State, province, or region.

- [`suffix`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

  Name suffix such as `Jr.` or `III`.

- [`title`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `string`

  Title or honorific such as `Dr.` or `Ms.`.

- [`updated_at`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) — `timestamp`

  When the customer was last updated. Omitted until the first update.

## Create customer

Create a customer when you want to recognize a buyer across purchases. Save the returned customer ID in your system, then use it when creating orders or saving payment methods for that buyer.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

### Required attributes

- `name` — `string` — required — wire-only

  Customer display name. Leading and trailing whitespace is removed; the maximum length is 200 characters.

### Optional attributes

- `billing_address` — wire-only

  Billing address. billing\_address.country is required when the object is provided.

  - `billing_address.city` — `string` — wire-only

    City or town.

  - `billing_address.country` — `string` — wire-only

    Country; required within the address.

  - `billing_address.line1` — `string` — wire-only

    Street address line 1.

  - `billing_address.line2` — `string` — wire-only

    Street address line 2.

  - `billing_address.name` — `string` — wire-only

    Recipient name.

  - `billing_address.phone_number` — `string` — wire-only

    Contact phone number.

  - `billing_address.post_code` — `string` — wire-only

    Postal or ZIP code.

  - `billing_address.region` — `string` — wire-only

    State, province, or region.

- `custom_data` — `object` — wire-only

  Metadata from your own system, such as a loyalty tier or account manager. Use string values. The complete object may be up to 25 KB, and each key may contain up to 256 characters. See [Custom data](https://studio.inttegro.com/machine/php/api/custom-data.md).

- `email_address` — `string` — wire-only

  Customer email address. Must be between 3 and 254 characters when provided.

- `phone_number` — `string` — wire-only

  Customer phone number. Must be between 7 and 20 characters when provided.

- `reference` — `string` — wire-only

  Your external reference for this customer. Must be between 1 and 100 characters when provided.

- `shipping_address` — wire-only

  Shipping address. shipping\_address.country is required when the object is provided.

  - `shipping_address.city` — `string` — wire-only

    City or town.

  - `shipping_address.country` — `string` — wire-only

    Country; required within the address.

  - `shipping_address.line1` — `string` — wire-only

    Street address line 1.

  - `shipping_address.line2` — `string` — wire-only

    Street address line 2.

  - `shipping_address.name` — `string` — wire-only

    Recipient name.

  - `shipping_address.phone_number` — `string` — wire-only

    Contact phone number.

  - `shipping_address.post_code` — `string` — wire-only

    Postal or ZIP code.

  - `shipping_address.region` — `string` — wire-only

    State, province, or region.

- `title` — `string` — wire-only

  Title or honorific such as `Dr.`. Must be between 1 and 20 characters when provided.

The response returns the new customer. Store its
[`customer.id`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-Customer.html) as the Inttegro customer ID for this buyer.

**Request — POST /customers/create**

```php
<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->customers->create([
  'name' => 'Jane Mensah',
  'title' => 'Ms.',
  'reference' => 'user_123456',
  'email_address' => 'jane@example.com',
  'phone_number' => '+233242057831',
  'custom_data' => [
    'loyalty_tier' => 'gold',
    'account_manager' => 'am_789',
  ],
]);
```

```json
{
  "customer": {
    "id": "cu_a1b2c3d4e5",
    "name": "Jane Mensah",
    "title": "Ms.",
    "email_address": "jane@example.com",
    "phone_number": "+233242057831",
    "reference": "user_123456",
    "custom_data": {
      "loyalty_tier": "gold",
      "account_manager": "am_789"
    },
    "guest": false,
    "balance": {},
    "created_at": "2025-11-23T14:30:00Z"
  }
}
```

## Search customers

Search customers by name or another remembered detail, or narrow the result
set by customer kind. Search results are discovery summaries: use the
returned customer ID with [Lookup customer](#lookup-customer) before a
decision or mutation that depends on current customer state.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

## Use customer search for discovery, then read the customer

- Send [`text`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-ResourceSearchRequest.html#property_text),
  [`filters`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-ResourceSearchRequest.html#property_filters),
  or both. The only filter and facet field accepted by this route is
  `filters[].field`
  with the value `kind`; field names are unqualified.
- Treat each result as a discovery summary. Read the canonical customer by
  [`results[].resource.id`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-ResourceSearchPage.html)
  before relying on profile, balance, or lifecycle data.
- When [`has_more`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-ResourceSearchPage.html)
  is true, replay the same request with
  [`next_cursor`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-ResourceSearchPage.html)
  as the request cursor. The cursor is opaque; do not decode or modify it.
- [`total`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-ResourceSearchPage.html)
  and facet counts describe the search result set, while
  [`result_count`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-ResourceSearchPage.html)
  describes only the current page.
- Inspect [`freshness`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-ResourceSearchPage.html)
  before presenting search data as current. Use customer lookup when delayed,
  partial, unknown, or unavailable data matters.

### Request attributes

- [`cursor`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-ResourceSearchRequest.html#property_cursor) — `string`

  Opaque continuation cursor returned by the previous page. Replay the
  same request and add this value to retrieve the next page.

- [`facets`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-ResourceSearchRequest.html#property_facets) — `array`

  Fields to group and count. This route accepts only kind.

  - `facets.field` — `array` — required

    Route-local field name. Use kind.

  - `facets.limit` — `array`

    Maximum buckets to return, from 1 through 50. Defaults to 10.

- [`filters`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-ResourceSearchRequest.html#property_filters) — `array`

  Exact constraints. This route accepts only kind.

  - `filters.field` — `array` — required

    Route-local field name. Use kind.

  - `filters.operator` — `array` — required

    Use eq for one value or in for any of several values.

  - `filters.values` — `array` — required

    One value for eq; one through 20 values for in.

- [`pageSize`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-ResourceSearchRequest.html#property_pageSize) — `integer`

  Results per page, from `1` through `100`. Defaults to `20`.

- [`sort`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-ResourceSearchRequest.html#property_sort) — `object`

  Result ordering.

  - `sort.direction` — `object` — required

    asc or desc. Relevance supports desc only.

  - `sort.field` — `object` — required

    relevance or updated\_at.

- [`text`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-ResourceSearchRequest.html#property_text) — `string`

  Search text, from 1 through 512 characters. Supply search text, exact
  filters, or both.

### Response

Returns a typed search page with discovery summaries in
[`results`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-ResourceSearchPage.html), requested facet counts in
[`facets`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-ResourceSearchPage.html), page and total counts, an optional
[`next_cursor`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-ResourceSearchPage.html), and [`freshness`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-ResourceSearchPage.html) metadata.
[`total.relation`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-ResourceSearchPage.html) states whether the total is exact or a
lower bound.

**Request — POST /customers/search**

```php
<?php

use Inttegro\Client;
use Inttegro\ResourceSearchRequest;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$request = new ResourceSearchRequest(
    text: 'Ama Mensah',
);
$page = $client->customers->search($request);
```

```json
{
  "search": {
    "results": [
      {
        "resource": { "type": "customer", "id": "cu_a1b2c3d4e5" },
        "title": "Ama Mensah",
        "summary": "ama@example.com",
        "updated_at": "2026-09-21T10:30:00Z"
      }
    ]
  }
}
```

## Lookup customer

Retrieve a customer's current profile and available balances. Use this when showing account details, preparing a repeat purchase, or helping a customer with their account.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

### Required attributes

- `customer_id` — `string` — required — wire-only

  Customer ID returned by Inttegro, beginning with
  `cu_`.

The response returns the customer object, including available customer-held balances by currency.

**Request — POST /customers/lookup**

```php
<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->customers->lookup("cu_a1b2c3d4e5");
```

```json
{
  "customer": {
    "id": "cu_a1b2c3d4e5",
    "name": "Jane Mensah",
    "title": "Ms.",
    "email_address": "jane@example.com",
    "phone_number": "+233242057831",
    "reference": "user_123456",
    "guest": false,
    "billing_address": {
      "name": "Jane Mensah",
      "phone_number": "+233242057831",
      "line1": "23 Adenta High Street",
      "line2": "East Legon Hills",
      "city": "Accra",
      "region": "Greater Accra",
      "post_code": "GA-422-1134",
      "country": "GH"
    },
    "shipping_address": {
      "name": "Jane Mensah",
      "phone_number": "+233242057831",
      "line1": "23 Adenta High Street",
      "line2": "East Legon Hills",
      "city": "Accra",
      "region": "Greater Accra",
      "post_code": "GA-422-1134",
      "country": "GH"
    },
    "custom_data": {
      "loyalty_tier": "gold",
      "account_manager": "am_789"
    },
    "balance": {
      "ghs": {
        "available": {
          "currency": "ghs",
          "value": 6500
        },
        "as_of": "2025-11-24T07:55:00Z"
      }
    },
    "created_at": "2025-11-23T14:30:00Z",
    "updated_at": "2025-11-24T08:00:00Z"
  }
}
```

## Update customer

Keep a customer's name, contact details, addresses, reference, or custom data current. Send only the fields you want to change; omitted fields keep their existing values.

Updating a guest customer created during checkout turns it into a reusable customer, so you can use the same customer ID for future purchases.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

### Update behavior

- For example, `email_address` set to `null` behaves like an omitted field; it does not clear the existing value. The same is true for other top-level optional fields.
- An address replaces the complete saved address. Include every address field you want to keep.
- `custom_data` replaces the complete metadata object rather than merging with it. Send an empty object to remove all custom data.

### Request attributes

- `billing_address` — wire-only

  Replacement billing address. billing\_address.country is required when this object is provided.

  - `billing_address.city` — `string` — wire-only

    City or town.

  - `billing_address.country` — `string` — wire-only

    Country identifier. Send a two-letter ISO 3166-1 code such as `'GH'`.

  - `billing_address.line1` — `string` — wire-only

    Street address line 1.

  - `billing_address.line2` — `string` — wire-only

    Street address line 2.

  - `billing_address.name` — `string` — wire-only

    Recipient name.

  - `billing_address.phone_number` — `string` — wire-only

    Contact phone number.

  - `billing_address.post_code` — `string` — wire-only

    Postal or ZIP code.

  - `billing_address.region` — `string` — wire-only

    State, province, or region.

- `custom_data` — `object` — wire-only

  Replacement metadata object. Response values are strings.

- `customer_id` — `string` — required — wire-only

  Customer ID returned by Inttegro, beginning with
  `cu_`.

- `email_address` — `string` — wire-only

  Replacement email address. Must be between 3 and 254 characters.

- `name` — `string` — wire-only

  Replacement display name. Must be between 1 and 200 characters.

- `phone_number` — `string` — wire-only

  Replacement phone number. Must be between 7 and 20 characters.

- `reference` — `string` — wire-only

  Replacement external reference. Must be between 1 and 100 characters.

- `shipping_address` — wire-only

  Replacement shipping address. shipping\_address.country is required when this object is provided.

  - `shipping_address.city` — `string` — wire-only

    City or town.

  - `shipping_address.country` — `string` — wire-only

    Country identifier. Send a two-letter ISO 3166-1 code such as `'GH'`.

  - `shipping_address.line1` — `string` — wire-only

    Street address line 1.

  - `shipping_address.line2` — `string` — wire-only

    Street address line 2.

  - `shipping_address.name` — `string` — wire-only

    Recipient name.

  - `shipping_address.phone_number` — `string` — wire-only

    Contact phone number.

  - `shipping_address.post_code` — `string` — wire-only

    Postal or ZIP code.

  - `shipping_address.region` — `string` — wire-only

    State, province, or region.

- `suffix` — `string` — wire-only

  Replacement name suffix. Must be between 1 and 10 characters.

- `title` — `string` — wire-only

  Replacement title or honorific. Must be between 1 and 20 characters.

The response returns the updated customer.

**Request — POST /customers/update**

```php
<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->customers->update([
  'customer_id' => 'cu_a1b2c3d4e5',
  'name' => 'Jane Mensah-Asante',
  'billing_address' => [
    'name' => 'Jane Mensah-Asante',
    'line1' => '5 Liberation Road',
    'city' => 'Accra',
    'country' => 'GH',
  ],
  'custom_data' => [
    'loyalty_tier' => 'platinum',
  ],
], "update-customer-user-123456-v2");
```

```json
{
  "customer": {
    "id": "cu_a1b2c3d4e5",
    "name": "Jane Mensah-Asante",
    "title": "Ms.",
    "email_address": "jane@example.com",
    "phone_number": "+233242057831",
    "reference": "user_123456",
    "custom_data": {
      "loyalty_tier": "platinum"
    },
    "guest": false,
    "billing_address": {
      "name": "Jane Mensah-Asante",
      "line1": "5 Liberation Road",
      "city": "Accra",
      "country": "GH"
    },
    "balance": {},
    "created_at": "2025-11-23T14:30:00Z",
    "updated_at": "2025-11-25T10:45:00Z"
  }
}
```

## Page through customers

Browse customers from newest to oldest. Use this endpoint to build customer lists, review recent sign-ups, or select a customer before retrieving their full account activity.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

### Request attributes

- `page_number` — `integer` — required — wire-only

  1-based page index to fetch. Must be between `1` and `10`.

- `page_size` — `integer` — wire-only

  Number of customers to return. Must be between `1` and `256`. Defaults to `256` when omitted.

The response contains the page number, the number of customers returned,
and the customer objects. An empty page has an empty
[`page.customers`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CustomerPage.html) collection and a
[`page.size`](https://php.inttegro.dev/v12.0.0/classes/Inttegro-CustomerPage.html) of
`0`.

**Request — POST /customers/page**

```php
<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->customers->page([
  'page_number' => 1,
  'page_size' => 50,
]);
```

```json
{
  "page": {
    "number": 1,
    "size": 2,
    "customers": [
      {
        "id": "cu_a1b2c3d4e5",
        "name": "Jane Mensah",
        "email_address": "jane@example.com",
        "phone_number": "+233242057831",
        "reference": "user_123456",
        "guest": false,
        "billing_address": {
          "name": "Jane Mensah",
          "phone_number": "+233242057831",
          "line1": "23 Adenta High Street",
          "line2": "East Legon Hills",
          "city": "Accra",
          "region": "Greater Accra",
          "post_code": "GA-422-1134",
          "country": "GH"
        },
        "custom_data": {
          "loyalty_tier": "gold"
        },
        "balance": {
          "ghs": {
            "available": {
              "currency": "ghs",
              "value": 6500
            },
            "as_of": "2025-11-24T07:55:00Z"
          }
        },
        "created_at": "2025-11-23T14:30:00Z"
      },
      {
        "id": "cu_f6g7h8i9j0",
        "name": "Kojo Asante",
        "title": "Mr.",
        "phone_number": "+233201234567",
        "guest": true,
        "balance": {},
        "created_at": "2025-11-22T09:15:00Z",
        "updated_at": "2025-11-24T11:05:00Z"
      }
    ]
  }
}
```