Skip to main content

Customers API

The Customers API lets you create, retrieve, update, list, and delete customers. A customer groups a payer's details (name, email, phone) under a stable reference you can reuse across payment intents.

You do not have to use this API to attach a customer to a payment: you can pass a customer object inline when creating a payment intent and we reconcile it for you. Use this API when you want to manage customer records directly.

Create a customer​

Creates a customer, or updates the existing one when you reuse a reference. This is a partial upsert: only the fields you send change.

Parameters​

referenceoptional, string

Your own identifier for the customer, used as the match key. If a customer with this reference already exists we update it; otherwise (or if omitted) we create a new one.

first_nameoptional, string

Customer first name.

last_nameoptional, string

Customer last name.

emailoptional, string

Customer email.

phone_numberoptional, string

Customer phone number.

POST /v202607/customers
const response = await fetch('https://api-{region}.orchestrapay.com/v202607/customers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer orch_sk_live_eu1_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    reference: 'user_12345',
    first_name: 'Jane',
    last_name: 'Doe',
    email: 'jane@example.com',
    phone_number: '+15555550123'
  })
});

Response Parameters​

customerstring

The typed, region-coded customer identifier (cus_...).

referencestring

Your identifier for the customer, if you set one.

first_namestring

Customer first name.

last_namestring

Customer last name.

emailstring

Customer email.

phone_numberstring

Customer phone number.

created_atstring

ISO 8601 creation timestamp.

resource_createdboolean

true if a new customer was created, false if an existing one was updated via its reference.

RESPONSE
{
  "customer": "cus_eu1_2c1d7ef04db08d2e5e980f3f3bc70000",
  "reference": "user_12345",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "phone_number": "+15555550123",
  "created_at": "2026-07-01T12:00:00Z",
  "resource_created": true
}

Get a customer​

Retrieves a single customer by its reference.

Parameters​

customerstring

The customer identifier to retrieve (cus_...).

GET /v202607/customers/{customer}
const response = await fetch('https://api-{region}.orchestrapay.com/v202607/customers/cus_eu1_2c1d7ef04db08d2e5e980f3f3bc70000', {
  headers: { 'Authorization': 'Bearer orch_sk_live_eu1_...' }
});

Response Parameters​

Returns the customer object: customer, reference, first_name, last_name, email, phone_number, created_at.

RESPONSE
{
  "customer": "cus_eu1_2c1d7ef04db08d2e5e980f3f3bc70000",
  "reference": "user_12345",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "phone_number": "+15555550123",
  "created_at": "2026-07-01T12:00:00Z"
}

Update a customer​

Updates a customer. This is a partial update: only the fields you send change; omitted fields are left untouched.

Parameters​

customerstring

The customer identifier to update (cus_...).

referenceoptional, string

Your identifier for the customer.

first_nameoptional, string

Customer first name.

last_nameoptional, string

Customer last name.

emailoptional, string

Customer email.

phone_numberoptional, string

Customer phone number.

POST /v202607/customers/{customer}
const response = await fetch('https://api-{region}.orchestrapay.com/v202607/customers/cus_eu1_2c1d7ef04db08d2e5e980f3f3bc70000', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer orch_sk_live_eu1_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ email: 'jane.doe@example.com' })
});

Response Parameters​

Returns the updated customer object (same shape as Get a customer).

RESPONSE
{
  "customer": "cus_eu1_2c1d7ef04db08d2e5e980f3f3bc70000",
  "reference": "user_12345",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane.doe@example.com",
  "phone_number": "+15555550123",
  "created_at": "2026-07-01T12:00:00Z"
}

Query customers​

Returns a list of customers, most recent first. Cursor-paginated with a fixed set of filters.

Query Parameters​

limitoptional, integer, default is 25

How many customers to return, 1 to 100.

starting_afteroptional, string

A cursor for pagination: a customer id (cus_...). Returns the page immediately after this object.

ending_beforeoptional, string

A cursor for pagination: a customer id (cus_...). Returns the page immediately before this object.

referenceoptional, string

Only return the customer with this reference.

emailoptional, string

Only return customers with this email.

createdoptional, object

Filter by creation time. Pass a Unix timestamp (or ISO 8601), or a range object.

GET /v202607/customers
const params = new URLSearchParams({ limit: '25', email: 'jane@example.com' });
const response = await fetch(
'https://api-{region}.orchestrapay.com/v202607/customers?' + params,
{ headers: { 'Authorization': 'Bearer orch_sk_live_eu1_...' } }
);

Response Parameters​

dataarray

The list of customers, most recent first.

has_moreboolean

true if there are more results after this page.

RESPONSE
{
  "data": [
    {
      "customer": "cus_eu1_2c1d7ef04db08d2e5e980f3f3bc70000",
      "reference": "user_12345",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "phone_number": "+15555550123",
      "created_at": "2026-07-01T12:00:00Z"
    }
  ],
  "has_more": false
}

Delete a customer​

Deletes a customer. This detaches the record; it does not affect payment intents or refunds already made for that customer.

Parameters​

customerstring

The customer identifier to delete (cus_...).

DELETE /v202607/customers/{customer}
const response = await fetch('https://api-{region}.orchestrapay.com/v202607/customers/cus_eu1_2c1d7ef04db08d2e5e980f3f3bc70000', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer orch_sk_live_eu1_...' }
});

Response Parameters​

customerstring

The deleted customer identifier (cus_...).

deletedboolean

Always true on a successful delete.

RESPONSE
{
  "customer": "cus_eu1_2c1d7ef04db08d2e5e980f3f3bc70000",
  "deleted": true
}