Customers

Create and manage your customer database through the API.

Overview

Customers represent the people or businesses you invoice. Each customer belongs to a specific company and can have multiple invoices and quotes associated with them.

Create a Customer

Bash

 1curl -X POST "https://api.corebill.io/v1/customers?company_id=com_abc123" \
 2  -H "Authorization: Bearer sk_live_your_api_key" \
 3  -H "Content-Type: application/json" \
 4  -d '{
 5    "name": "Acme Corp",
 6    "country": "US",
 7    "email": "billing@acme.com",
 8    "city": "New York",
 9    "currency": "USD",
10    "legal_name": "Acme Corporation Inc.",
11    "legal_vat": "US123456789"
12  }'

Only name and country are required. A unique slug is generated automatically from the name.

List Customers

Bash

 1# List all customers
 2curl "https://api.corebill.io/v1/customers?company_id=com_abc123" \
 3  -H "Authorization: Bearer sk_live_your_api_key"
 4
 5# Filter by status
 6curl "https://api.corebill.io/v1/customers?company_id=com_abc123&status=active" \
 7  -H "Authorization: Bearer sk_live_your_api_key"
 8
 9# Paginate (cursor-based)
10curl "https://api.corebill.io/v1/customers?company_id=com_abc123&limit=10&starting_after=cus_abc123" \
11  -H "Authorization: Bearer sk_live_your_api_key"

Retrieve a Customer

Bash

 1curl "https://api.corebill.io/v1/customers/cus_abc123?company_id=com_abc123" \
 2  -H "Authorization: Bearer sk_live_your_api_key"

Update a Customer

Use POST to update specific fields:

Bash

 1curl -X POST "https://api.corebill.io/v1/customers/cus_abc123?company_id=com_abc123" \
 2  -H "Authorization: Bearer sk_live_your_api_key" \
 3  -H "Content-Type: application/json" \
 4  -d '{
 5    "email": "new-billing@acme.com",
 6    "status": "active"
 7  }'

The API accepts email as a shorthand for contact_email, and phone as a shorthand for contact_phone.

Delete a Customer

Deleting a customer performs a soft delete (sets deleted_at timestamp). Requires admin permission.

Bash

 1curl -X DELETE "https://api.corebill.io/v1/customers/cus_abc123?company_id=com_abc123" \
 2  -H "Authorization: Bearer sk_live_your_api_key"

Customer Fields

Field	Type	Required	Description
`name`	string	Yes	Customer display name
`country`	string	Yes	ISO-2 country code
`email`	string	No	Contact email
`phone`	string	No	Contact phone
`city`	string	No	City
`currency`	string	No	Currency code (default: `USD`)
`legal_name`	string	No	Legal/fiscal name
`legal_address`	string	No	Legal address
`legal_vat`	string	No	VAT/Tax ID
`zipcode`	string	No	Postal code
`notes`	string	No	Internal notes

Authentication Invoices