Customers API

Create and manage customers to associate with payments and subscriptions.

Base URL

http://localhost:8081

Create a Customer

POST/customers

Request Body

{
  "email": "jane@example.com",
  "name": "Jane Doe",
  "phone": "+2348012345678",
  "description": "Enterprise customer",
  "metadata": {
    "company": "Acme Corp",
    "plan": "enterprise"
  }
}

Response

{
  "customer_id": "cus_def456",
  "email": "jane@example.com",
  "name": "Jane Doe",
  "phone": "+2348012345678",
  "description": "Enterprise customer",
  "created_at": "2026-07-26T10:30:00Z",
  "metadata": {
    "company": "Acme Corp",
    "plan": "enterprise"
  }
}

Retrieve a Customer

GET/customers/{customer_id}

curl -X GET http://localhost:8081/customers/cus_def456 \
  -H "api-key: test_api_key_xxxx"

List Customers

GET/customers

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (default 20, max 100)
`offset`	integer	Number of results to skip
`email`	string	Filter by email address
`created`	object	Date range filter

Update a Customer

PUT/customers/{customer_id}

{
  "email": "jane.updated@example.com",
  "name": "Jane M. Doe",
  "metadata": {
    "company": "Acme Corp",
    "plan": "enterprise",
    "tier": "gold"
  }
}

Delete a Customer

DELETE/customers/{customer_id}

Permanently deletes a customer. Associated payments and subscriptions are not deleted but will no longer be linked to this customer.