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.

Operations

Create customer
Lookup customer
Update customer
Page through customers

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

balanceobjectrequiredAlways-present map of customer-held balances by currency. The value is {} when the customer has no balance entries.Click or tap to expand
- Name
  <currency>
  Type
  object
  View <currency> attributesClick or tap to expand
  Balance entry keyed by lowercase, three-letter ISO 4217 currency code, such as ghs.
  Name
  as_of
  Type
  timestamp
  Description
  Point in time represented by this balance entry. Later customer balance activity may not yet be reflected.
  Name
  available
  Type
  object
  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
  integer
  Description
  Available amount in the currency's smallest unit.
billing_addressobjectBilling 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. 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 for this address.
- Name
  phone_number
  Type
  string
  Description
  Contact phone number for this address.
- Name
  post_code
  Type
  string
  Description
  Postal or ZIP code.
- Name
  region
  Type
  string
  Description
  State, province, or region.
Name
created_at
Type
timestamp
Required
required
Description
When the customer record was created.
custom_dataobjectClick 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
email_address
Type
string
Description
Customer email address when one has been provided.
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
phone_number
Type
string
Description
Customer phone number when one has been provided.
Name
reference
Type
string
Description
Your own external reference for the customer.
shipping_addressobjectShipping 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. 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 for this address.
- Name
  phone_number
  Type
  string
  Description
  Contact phone number for this address.
- Name
  post_code
  Type
  string
  Description
  Postal or ZIP code.
- Name
  region
  Type
  string
  Description
  State, province, or region.
Name
suffix
Type
string
Description
Name suffix such as Jr. or III.
Name
title
Type
string
Description
Title or honorific such as Dr. or Ms..
Name
updated_at
Type
timestamp
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

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

Optional attributes

billing_addressobjectBilling address. 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
  phone_number
  Type
  string
  Description
  Contact phone number.
- Name
  post_code
  Type
  string
  Description
  Postal or ZIP code.
- Name
  region
  Type
  string
  Description
  State, province, or region.
custom_dataobjectClick 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
email_address
Type
string
Description
Customer email address. Must be between 3 and 254 characters when provided.
Name
phone_number
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.
shipping_addressobjectShipping address. 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
  phone_number
  Type
  string
  Description
  Contact phone number.
- Name
  post_code
  Type
  string
  Description
  Postal or ZIP code.
- Name
  region
  Type
  string
  Description
  State, province, or region.
Name
suffix
Type
string
Description
Name suffix such as Jr. or III. Must be between 1 and 10 characters when provided.
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

curl https://api.inttegro.com/customers/create \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-customer-user-123456" \
  -d '{
    "name": "Jane Mensah",
    "title": "Ms.",
    "reference": "user_123456",
    "email_address": "[email protected]",
    "phone_number": "+233242057831",
    "custom_data": {
      "loyalty_tier": "gold",
      "account_manager": "am_789"
    }
  }'

SDK versionv8.2.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",
  },
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  params := inttegro.CreateCustomerParams{
    Name: "Jane Mensah",
    Title: "Ms.",
    Reference: "user_123456",
    Email: "[email protected]",
    PhoneNumber: "+233242057831",
    CustomData: map[string]string{
      "loyalty_tier": "gold",
      "account_manager": "am_789",
    },
  }
  result, err := client.Customers.Create(ctx, params)
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.customers.create(inttegro.customers.CreateRequest(
  name="Jane Mensah",
  title="Ms.",
  reference="user_123456",
  email_address="[email protected]",
  phone_number="+233242057831",
  custom_data={
    "loyalty_tier": "gold",
    "account_manager": "am_789",
  },
))

SDK versionv5.3.0

<?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' => '[email protected]',
  'phone_number' => '+233242057831',
  'custom_data' => [
    'loyalty_tier' => 'gold',
    'account_manager' => 'am_789',
  ],
]);

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.customers.create(
  name: "Jane Mensah",
  title: "Ms.",
  reference: "user_123456",
  email_address: "[email protected]",
  phone_number: "+233242057831",
  custom_data: {
    loyalty_tier: "gold",
    account_manager: "am_789",
  }
)

SDK versionv5.2.0

import com.inttegro.Client;
import com.inttegro.customers.CreateCustomerParams;
import java.util.Map;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = CreateCustomerParams.builder()
      .name("Jane Mensah")
      .title("Ms.")
      .reference("user_123456")
      .emailAddress("[email protected]")
      .phoneNumber("+233242057831")
      .customData(Map.<String, String>ofEntries(
          Map.entry("loyalty_tier", "gold"),
          Map.entry("account_manager", "am_789")
        ))
      .build();
    var result = client.customers().create(params);
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.Customers.CreateAsync(new {
  name = "Jane Mensah",
  title = "Ms.",
  reference = "user_123456",
  email_address = "[email protected]",
  phone_number = "+233242057831",
  custom_data = new {
    loyalty_tier = "gold",
    account_manager = "am_789",
  },
});

Response

Object
JSON

SDK versionv8.2.0

CustomerResponse {
  customer: { … },
}

SDK versionv8.2.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/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

Name
customer_id
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

curl https://api.inttegro.com/customers/lookup \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cu_a1b2c3d4e5"
  }'

SDK versionv8.2.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",
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  result, err := client.Customers.Lookup(ctx, "cu_a1b2c3d4e5")
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.customers.lookup("cu_a1b2c3d4e5")

SDK versionv5.3.0

<?php

use Inttegro\Client;

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

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.customers.lookup(customer_id: "cu_a1b2c3d4e5")

SDK versionv5.2.0

import com.inttegro.Client;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var result = client.customers().lookup("cu_a1b2c3d4e5");
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.Customers.LookupAsync("cu_a1b2c3d4e5");

Response

Object
JSON

SDK versionv8.2.0

CustomerResponse {
  customer: { … },
}

SDK versionv8.2.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

A top-level null value behaves like an omitted field; it does not clear the existing value.
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 {} to remove all custom data.

Request attributes

billing_addressobjectReplacement billing address. 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
  phone_number
  Type
  string
  Description
  Contact phone number.
- Name
  post_code
  Type
  string
  Description
  Postal or ZIP code.
- Name
  region
  Type
  string
  Description
  State, province, or region.
custom_dataobjectClick or tap to expand
Replacement metadata object. Response values are strings.
Name
customer_id
Type
string
Required
required
Description
Customer ID returned by Inttegro, beginning with cu_.
Name
email_address
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
phone_number
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.
shipping_addressobjectReplacement shipping address. 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
  phone_number
  Type
  string
  Description
  Contact phone number.
- Name
  post_code
  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

cURL
SDK coverage

curl https://api.inttegro.com/customers/update \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: update-customer-user-123456-v2" \
  -d '{
    "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"
    }
  }'

Official SDK coverage for POST /customers/update is pending.

Add this operation to the checked-in SDKs before publishing a runnable sample here.

Response

Object
JSON

SDK versionv8.2.0

CustomerResponse {
  customer: { … },
}

SDK versionv8.2.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

Name
page_number
Type
integer
Required
required
Description
1-based page index to fetch. Must be between 1 and 10.
Name
page_size
Type
integer
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 returns customers: [] and size: 0.

Request

POST/customers/page

curl https://api.inttegro.com/customers/page \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page_number": 1,
    "page_size": 50
  }'

SDK versionv8.2.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,
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  params := inttegro.PageCustomersParams{
    PageNumber: 1,
    PageSize: 50,
  }
  result, err := client.Customers.Page(ctx, params)
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.customers.page(inttegro.customers.PageRequest(
  page_number=1,
  page_size=50,
))

SDK versionv5.3.0

<?php

use Inttegro\Client;

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

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.customers.page(
  page_number: 1,
  page_size: 50
)

SDK versionv5.2.0

import com.inttegro.Client;
import com.inttegro.customers.PageCustomersParams;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = PageCustomersParams.builder()
      .pageNumber(1)
      .pageSize(50)
      .build();
    var result = client.customers().page(params);
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.Customers.PageAsync(new {
  page_number = 1,
  page_size = 50,
});

Response

Object
JSON

SDK versionv8.2.0

PageResponse {
  page: { … },
}

SDK versionv8.2.0

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

The customer object

Properties​

Create customer

Required attributes​

Optional attributes​

Request

Response

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

Required attributes

Update behavior

Request attributes

Request attributes