Get Customer

Retrieves a customer by ID.

Endpoint

GET /v1/customers/:id

Authentication

Requires API key authentication via X-API-Key header.

Path Parameters

Parameter	Type	Description
id	string	The customer ID

Query Parameters

Parameter	Type	Description
expand	string	Comma-separated list of fields to expand. Supported: stats

Example Request

curl https://api.example.com/v1/customers/cus_abc123def456 \
  -H "X-API-Key: sk_live_xxxxx"

Example Response

{
  "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"
  },
  "created": 1706554800,
  "updated": 1706554800
}

Example Request with Stats Expansion

curl "https://api.example.com/v1/customers/cus_abc123def456?expand=stats" \
  -H "X-API-Key: sk_live_xxxxx"

Example Response with Stats

{
  "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"
  },
  "invoiceCount": 5,
  "chargeCount": 12,
  "totalSpent": "1250.00",
  "created": 1706554800,
  "updated": 1706554800
}

Errors

Code	Description
401	Invalid or missing API key
404	Customer not found or doesn't belong to your merchant account