Customers
Create, list, update, and delete project-scoped customers
All customer endpoints are scoped to a project:
/api/billstack/teams/{teamId}/projects/{projectId}/customersList Customers
GET /customers?limit=50&offset=0Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | number | 50 | Max items to return |
offset | number | 0 | Items to skip |
Example:
curl "https://your-billstack.com/.../customers?limit=25" \
-H "Authorization: Bearer bs_..."Response:
{
"customers": [
{
"id": "pc_a1b2c3d4",
"email": "jane@example.com",
"name": "Jane Doe",
"stripeCustomerId": "cus_xxx",
"metadata": { "plan": "pro" },
"projectId": "proj_abc123",
"createdAt": "2026-03-30T12:00:00Z",
"updatedAt": "2026-03-30T12:00:00Z"
}
]
}Auth: Read access (session or API key with customers:read).
Create Customer
POST /customersRequest Body:
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Customer email (must be unique per project) |
name | string | No | Customer display name |
metadata | object | No | Arbitrary key-value pairs |
Example:
curl -X POST "https://your-billstack.com/.../customers" \
-H "Authorization: Bearer bs_..." \
-H "Content-Type: application/json" \
-d '{
"email": "jane@example.com",
"name": "Jane Doe",
"metadata": { "plan": "pro" }
}'Response (201):
{
"customer": {
"id": "pc_a1b2c3d4",
"email": "jane@example.com",
"name": "Jane Doe",
"stripeCustomerId": "cus_xxx",
"metadata": { "plan": "pro" },
"projectId": "proj_abc123",
"createdAt": "2026-03-30T12:00:00Z"
}
}Creates the customer in both Stripe (with project_id metadata) and the BillStack database. If a Stripe customer with the same email already exists, BillStack links to the existing Stripe customer.
Auth: Write access (session or API key with customers:write).
Get Customer
GET /customers/{customerId}Example:
curl "https://your-billstack.com/.../customers/pc_a1b2c3d4" \
-H "Authorization: Bearer bs_..."Response:
{
"customer": {
"id": "pc_a1b2c3d4",
"email": "jane@example.com",
"name": "Jane Doe",
"stripeCustomerId": "cus_xxx",
"metadata": { "plan": "pro" },
"projectId": "proj_abc123",
"createdAt": "2026-03-30T12:00:00Z",
"updatedAt": "2026-03-30T12:00:00Z"
}
}Auth: Read access.
Update Customer
PATCH /customers/{customerId}Request Body:
| Field | Type | Description |
|---|---|---|
email | string | New email address |
name | string | New display name |
metadata | object | New metadata (replaces existing) |
Example:
curl -X PATCH "https://your-billstack.com/.../customers/pc_a1b2c3d4" \
-H "Authorization: Bearer bs_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Smith",
"metadata": { "plan": "enterprise" }
}'Updates the customer in both Stripe and the BillStack database.
Auth: Write access.
Delete Customer
DELETE /customers/{customerId}Example:
curl -X DELETE "https://your-billstack.com/.../customers/pc_a1b2c3d4" \
-H "Authorization: Bearer bs_..."Response:
{
"success": true
}Removes the customer from the BillStack database only. The Stripe customer record is preserved — this prevents breaking any existing Stripe subscriptions or invoices.
Auth: Write access.