Customers

A Customer represents a buyer or client of your business. Customers can be linked to Charges and Invoices to track payment history and simplify recurring billing.

The Customer Object

{
  "id": "cus_abc123def456",
  "object": "customer",
  "email": "[email protected]",
  "name": "John Doe",
  "phone": "+1234567890",
  "address": {
    "line1": "123 Main St",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94102",
    "country": "US"
  },
  "companyName": "Acme Inc",
  "taxId": "12-3456789",
  "description": "VIP customer",
  "metadata": {
    "tier": "gold",
    "source": "referral"
  },
  "created": 1706554800,
  "updated": 1706554800
}

Attributes

Attribute
Type
Description

id

string

Unique identifier for the customer

object

string

Always "customer"

email

string

Customer's email address (unique per merchant)

name

string

Customer's full name

phone

string | null

Customer's phone number

address

object | null

Customer's address

address.line1

string

Street address line 1

address.line2

string

Street address line 2

address.city

string

City

address.state

string

State or province

address.postalCode

string

Postal or ZIP code

address.country

string

Two-letter country code (e.g., "US")

companyName

string | null

Company name (for B2B)

taxId

string | null

Tax ID or VAT number

description

string | null

Internal description or notes

metadata

object | null

Arbitrary key-value pairs

created

integer

Unix timestamp of creation

updated

integer

Unix timestamp of last update

Expanded Attributes

When using ?expand=stats, the response includes:

Attribute
Type
Description

invoiceCount

integer

Number of invoices for this customer

chargeCount

integer

Number of charges for this customer

totalSpent

string

Total amount from completed charges

Endpoints

Method
Endpoint
Description

POST

/v1/customers

GET

/v1/customers/:id

GET

/v1/customers

PATCH

/v1/customers/:id

DELETE

/v1/customers/:id

Last updated