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. 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 for the complete integration flow.

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

TypeScript SDK responseCustomerv12.0.0

balanceCustomerBalancerequiredAlways-present map of customer-held balances by currency. The map is empty when the customer has no balance entries.Click or tap to expand
- Name
  currency
  Type
  Record<string, unknown>
  View <currency> attributesClick or tap to expand
  Balance entry keyed by lowercase, three-letter ISO 4217 currency code, such as "ghs".
  Name
  asOf
  Type
  Date
  Description
  Point in time represented by this balance entry. Later customer balance activity may not yet be reflected.
  Name
  available
  Type
  Record<string, unknown>
  View available attributesClick or tap to expand
  Amount available for the customer in this currency.
  Name
  currency
  Type
  string
  Description
  Lowercase ISO 4217 currency code for the balance entry.
  Name
  value
  Type
  number
  Description
  Available amount in the currency's smallest unit.
billingAddressCustomerAddress | nullBilling address saved on the customer when available.Click or tap to expand
- Name
  city
  Type
  string
  Description
  City or town.
- Name
  country
  Type
  string
  Description
  Country identifier. A two-letter ISO 3166-1 code, such as "GH".
- Name
  line1
  Type
  string
  Description
  Street address line 1.
- Name
  line2
  Type
  string
  Description
  Street address line 2.
- Name
  name
  Type
  string
  Description
  Recipient name for this address.
- Name
  phoneNumber
  Type
  string
  Description
  Contact phone number for this address.
- Name
  postCode
  Type
  string
  Description
  Postal or ZIP code.
- Name
  region
  Type
  string
  Description
  State, province, or region.
Name
createdAt
Type
Date
Required
required
Description
When the customer record was created.
customDataCustomDataClick or tap to expand
Your own key-value metadata. Response values are strings. This property is omitted when no custom data has been stored.
Name
emailAddress
Type
string | null
Description
Customer email address when one has been provided.
Name
fingerprint
Type
string
Required
required
Description
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.
Name
guest
Type
boolean
Required
required
Description
true when checkout created the customer from inline customer data. Updating the customer changes this to false.
Name
id
Type
string
Required
required
Description
Application-scoped identifier with the cu_ prefix.
Name
name
Type
string
Required
required
Description
Customer full name.
Name
phoneNumber
Type
string | null
Description
Customer phone number when one has been provided.
Name
reference
Type
string | null
Description
Your own external reference for the customer.
shippingAddressCustomerAddress | nullShipping address saved on the customer when available.Click or tap to expand
- Name
  city
  Type
  string
  Description
  City or town.
- Name
  country
  Type
  string
  Description
  Country identifier. A two-letter ISO 3166-1 code, such as "GH".
- Name
  line1
  Type
  string
  Description
  Street address line 1.
- Name
  line2
  Type
  string
  Description
  Street address line 2.
- Name
  name
  Type
  string
  Description
  Recipient name for this address.
- Name
  phoneNumber
  Type
  string
  Description
  Contact phone number for this address.
- Name
  postCode
  Type
  string
  Description
  Postal or ZIP code.
- Name
  region
  Type
  string
  Description
  State, province, or region.
Name
suffix
Type
string | null
Description
Name suffix such as Jr. or III.
Name
title
Type
string | null
Description
Title or honorific such as Dr. or Ms..
Name
updatedAt
Type
Date | null
Description
When the customer was last updated. Omitted until the first update.

POST/customers/create

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.

Available through MCP

AI clients can use create_customer or create_customer_from_contact for this operation. Confirmed MCP actions still require explicit form confirmation before Inttegro changes state.

Required attributes

TypeScript SDK requestCreateCustomerRequestv12.0.0

Name
name
Type
string
Required
required
Description
Customer display name. Leading and trailing whitespace is removed; the maximum length is 200 characters.

Optional attributes

TypeScript SDK requestCreateCustomerRequestv12.0.0

billingAddressCustomerAddressInputBilling address. billingAddress.country is required when the object is provided.Click or tap to expand
- Name
  city
  Type
  string
  Description
  City or town.
- Name
  country
  Type
  string
  Description
  Country; required within the address.
- Name
  line1
  Type
  string
  Description
  Street address line 1.
- Name
  line2
  Type
  string
  Description
  Street address line 2.
- Name
  name
  Type
  string
  Description
  Recipient name.
- Name
  phoneNumber
  Type
  string
  Description
  Contact phone number.
- Name
  postCode
  Type
  string
  Description
  Postal or ZIP code.
- Name
  region
  Type
  string
  Description
  State, province, or region.
customDataCustomDataInputClick or tap to expand
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.
Name
emailAddress
Type
string
Description
Customer email address. Must be between 3 and 254 characters when provided.
Name
phoneNumber
Type
string
Description
Customer phone number. Must be between 7 and 20 characters when provided.
Name
reference
Type
string
Description
Your external reference for this customer. Must be between 1 and 100 characters when provided.
shippingAddressCustomerAddressInputShipping address. shippingAddress.country is required when the object is provided.Click or tap to expand
- Name
  city
  Type
  string
  Description
  City or town.
- Name
  country
  Type
  string
  Description
  Country; required within the address.
- Name
  line1
  Type
  string
  Description
  Street address line 1.
- Name
  line2
  Type
  string
  Description
  Street address line 2.
- Name
  name
  Type
  string
  Description
  Recipient name.
- Name
  phoneNumber
  Type
  string
  Description
  Contact phone number.
- Name
  postCode
  Type
  string
  Description
  Postal or ZIP code.
- Name
  region
  Type
  string
  Description
  State, province, or region.
Name
title
Type
string
Description
Title or honorific such as Dr.. Must be between 1 and 20 characters when provided.

The response returns the new customer. Store its id as the Inttegro customer ID for this buyer.

Request

POST/customers/create

SDK versionv12.0.0

import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.customers.create({
  name: "Jane Mensah",
  title: "Ms.",
  reference: "user_123456",
  emailAddress: "[email protected]",
  phoneNumber: "+233242057831",
  customData: {
    loyalty_tier: "gold",
    account_manager: "am_789",
  },
})

Response

Object
JSON

SDK versionv12.0.0

CustomerResponse {
  customer: { … },
}

SDK versionv12.0.0

{
  "customer": {
    "id": "cu_a1b2c3d4e5",
    "name": "Jane Mensah",
    "title": "Ms.",
    "email_address": "[email protected]",
    "phone_number": "+233242057831",
    "reference": "user_123456",
    "custom_data": { … },
    "guest": false,
    "balance": {},
    "created_at": "2025-11-23T14:30:00Z"
  }
}

POST/customers/search

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 before a decision or mutation that depends on current customer state.

Request attributes

TypeScript SDK requestResourceSearchRequestv12.0.0

Name
cursor
Type
string
Description
Opaque continuation cursor returned by the previous page. Replay the same request and add this value to retrieve the next page.
facetsResourceSearchFacet[]Fields to group and count. This route accepts only kind.Click or tap to expand
- Name
  field
  Type
  string
  Required
  required
  Description
  Route-local field name. Use kind.
- Name
  limit
  Type
  number
  Description
  Maximum buckets to return, from 1 through 50. Defaults to 10.
filtersResourceSearchFilter[]Exact constraints. This route accepts only kind.Click or tap to expand
- Name
  field
  Type
  string
  Required
  required
  Description
  Route-local field name. Use kind.
- Name
  operator
  Type
  ResourceSearchOperator
  Required
  required
  Description
  Use eq for one value or in for any of several values.
- Name
  values
  Type
  string[]
  Required
  required
  Description
  One value for eq; one through 20 values for in.
Name
pageSize
Type
number
Description
Results per page, from 1 through 100. Defaults to 20.
sortResourceSearchSortResult ordering.Click or tap to expand
- Name
  direction
  Type
  ResourceSearchSortDirection
  Required
  required
  Description
  asc or desc. Relevance supports desc only.
- Name
  field
  Type
  ResourceSearchSortField
  Required
  required
  Description
  relevance or updated_at.
Name
text
Type
string
Description
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, requested facet counts in facets, page and total counts, an optional nextCursor, and freshness metadata. total.relation states whether the total is exact or a lower bound.

Request

POST/customers/search

SDK versionv12.0.0

import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})

const request: Inttegro.ResourceSearchRequest = {
  text: "Ama Mensah",
}
const page = await inttegro.customers.search(request)

Response excerpt

Object
JSON

SDK versionv12.0.0

SearchResponse {
  search: { … },
}

SDK versionv12.0.0

{
  "search": {
    "results": [ … ]
  }
}

POST/customers/lookup

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.

Available through MCP

AI clients can use get_customer for this operation. MCP read tools return minimized business data and do not change Inttegro state.

Required attributes

TypeScript SDK requestLookupCustomerRequestv12.0.0

Name
customerId
Type
string
Required
required
Description
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

SDK versionv12.0.0

import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.customers.lookup({
  customerId: "cu_a1b2c3d4e5",
})

Response

Object
JSON

SDK versionv12.0.0

CustomerResponse {
  customer: { … },
}

SDK versionv12.0.0

{
  "customer": {
    "id": "cu_a1b2c3d4e5",
    "name": "Jane Mensah",
    "title": "Ms.",
    "email_address": "[email protected]",
    "phone_number": "+233242057831",
    "reference": "user_123456",
    "guest": false,
    "billing_address": { … },
    "shipping_address": { … },
    "custom_data": { … },
    "balance": { … },
    "created_at": "2025-11-23T14:30:00Z",
    "updated_at": "2025-11-24T08:00:00Z"
  }
}

POST/customers/update

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.

Available through MCP

AI clients can use update_customer for this operation. Confirmed MCP actions still require explicit form confirmation before Inttegro changes state.

Update behavior

For example, emailAddress 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.
customData replaces the complete metadata object rather than merging with it. Send an empty object to remove all custom data.

Request attributes

TypeScript SDK requestUpdateCustomerRequestv12.0.0

billingAddressCustomerAddressInputReplacement billing address. billingAddress.country is required when this object is provided.Click or tap to expand
- Name
  city
  Type
  string
  Description
  City or town.
- Name
  country
  Type
  string
  Description
  Country identifier. Send a two-letter ISO 3166-1 code such as "GH".
- Name
  line1
  Type
  string
  Description
  Street address line 1.
- Name
  line2
  Type
  string
  Description
  Street address line 2.
- Name
  name
  Type
  string
  Description
  Recipient name.
- Name
  phoneNumber
  Type
  string
  Description
  Contact phone number.
- Name
  postCode
  Type
  string
  Description
  Postal or ZIP code.
- Name
  region
  Type
  string
  Description
  State, province, or region.
customDataCustomDataInputClick or tap to expand
Replacement metadata object. Response values are strings.
Name
customerId
Type
string
Required
required
Description
Customer ID returned by Inttegro, beginning with cu_.
Name
emailAddress
Type
string
Description
Replacement email address. Must be between 3 and 254 characters.
Name
name
Type
string
Description
Replacement display name. Must be between 1 and 200 characters.
Name
phoneNumber
Type
string
Description
Replacement phone number. Must be between 7 and 20 characters.
Name
reference
Type
string
Description
Replacement external reference. Must be between 1 and 100 characters.
shippingAddressCustomerAddressInputReplacement shipping address. shippingAddress.country is required when this object is provided.Click or tap to expand
- Name
  city
  Type
  string
  Description
  City or town.
- Name
  country
  Type
  string
  Description
  Country identifier. Send a two-letter ISO 3166-1 code such as "GH".
- Name
  line1
  Type
  string
  Description
  Street address line 1.
- Name
  line2
  Type
  string
  Description
  Street address line 2.
- Name
  name
  Type
  string
  Description
  Recipient name.
- Name
  phoneNumber
  Type
  string
  Description
  Contact phone number.
- Name
  postCode
  Type
  string
  Description
  Postal or ZIP code.
- Name
  region
  Type
  string
  Description
  State, province, or region.
Name
suffix
Type
string
Description
Replacement name suffix. Must be between 1 and 10 characters.
Name
title
Type
string
Description
Replacement title or honorific. Must be between 1 and 20 characters.

The response returns the updated customer.

Request

POST/customers/update

SDK versionv12.0.0

import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.customers.update({
  customerId: "cu_a1b2c3d4e5",
  name: "Jane Mensah-Asante",
  billingAddress: {
    name: "Jane Mensah-Asante",
    line1: "5 Liberation Road",
    city: "Accra",
    country: "GH",
  },
  customData: {
    loyalty_tier: "platinum",
  },
}, {
  idempotencyKey: "update-customer-user-123456-v2",
})

Response

Object
JSON

SDK versionv12.0.0

CustomerResponse {
  customer: { … },
}

SDK versionv12.0.0

{
  "customer": {
    "id": "cu_a1b2c3d4e5",
    "name": "Jane Mensah-Asante",
    "title": "Ms.",
    "email_address": "[email protected]",
    "phone_number": "+233242057831",
    "reference": "user_123456",
    "custom_data": { … },
    "guest": false,
    "billing_address": { … },
    "balance": {},
    "created_at": "2025-11-23T14:30:00Z",
    "updated_at": "2025-11-25T10:45:00Z"
  }
}

POST/customers/page

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.

Available through MCP

AI clients can use list_customers for this operation. MCP read tools return minimized business data and do not change Inttegro state.

Request attributes

TypeScript SDK requestPageCustomersRequestv12.0.0

Name
pageNumber
Type
number
Required
required
Description
1-based page index to fetch. Must be between 1 and 10.
Name
pageSize
Type
number
Description
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 customers collection and a size of 0.

Request

POST/customers/page

SDK versionv12.0.0

import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.customers.page({
  pageNumber: 1,
  pageSize: 50,
})

Response

Object
JSON

SDK versionv12.0.0

PageResponse {
  page: { … },
}

SDK versionv12.0.0

{
  "page": {
    "number": 1,
    "size": 2,
    "customers": [ … ]
  }
}

The customer object

Properties​

Create customer

Required attributes​

Optional attributes​

Request

Response

Search customers

Request attributes​

Response​

Request

Response excerpt

Lookup customer

Required attributes​

Request

Response

Update customer

Update behavior​

Request attributes​

Request

Response

Page through customers

Request attributes​

Request

Response

Properties

Required attributes

Optional attributes

Request attributes

Response

Required attributes

Update behavior

Request attributes

Request attributes