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": "[phone]",
  "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	Create a customer
GET	/v1/customers/:id	Get a customer
GET	/v1/customers	List customers
PATCH	/v1/customers/:id	Update a customer
DELETE	/v1/customers/:id	Delete a customer