v1

latestOpenAPI 3.0.32026-07-264469137.7 KB

Customers

Create a customer

Creates a customer. A customer groups a buyer's payments, subscriptions, and saved payment methods under one record. Only email is required. Requires the customers:write scope.

post/v1/customers

Request body

emailstring email required

The customer's email address. Used to identify the customer and send receipts.

namestring nullable

The customer's full name. Derived from first_name and last_name when those are provided instead.

phone_numberstring nullable

The customer's phone number in E.164 format, e.g. +2348012345678.

metadataobject

Your own key-value data attached to the customer, returned unchanged.

Example request

{
  "email": "jane@example.com",
  "name": "Jane Doe",
  "phone_number": "+2348012345678",
  "metadata": {
    "plan": "pro"
  }
}

Response

Customer created

customer_idstring required

Unique identifier for the customer, prefixed with cust_.

emailstring email required

The customer's email address.

namestring nullable

The customer's full name. null when not set.

phone_numberstring nullable

The customer's phone number in E.164 format, e.g. +2348012345678.

metadataobject required

Your own key-value data attached to the customer.

created_atstring date-time required

ISO 8601 timestamp when the customer was created.

updated_atstring date-time required

ISO 8601 timestamp when the customer was last updated.

Example response

{
  "customer_id": "cust_1a2b3c4d5e6f",
  "email": "jane@example.com",
  "name": "Jane Doe",
  "phone_number": "+2348012345678",
  "metadata": {
    "plan": "pro"
  },
  "created_at": "2026-01-24T12:00:00.000Z",
  "updated_at": "2026-01-24T12:00:00.000Z"
}