Skip to main content

​
Overview

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

​
Create a Customer

curl -X POST "https://api.corebill.io/v1/customers?company_id=com_abc123" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "country": "US",
    "email": "[email protected]",
    "city": "New York",
    "currency": "USD",
    "legal_name": "Acme Corporation Inc.",
    "legal_vat": "US123456789"
  }'
Only name and country are required. A unique slug is generated automatically from the name.

​
List Customers

# List all customers
curl "https://api.corebill.io/v1/customers?company_id=com_abc123"

# Search by name or email
curl "https://api.corebill.io/v1/customers?company_id=com_abc123&search=acme"

# Paginate results
curl "https://api.corebill.io/v1/customers?company_id=com_abc123&limit=10&offset=20"

​
Update a Customer

Use PATCH to update specific fields: 
curl -X PATCH "https://api.corebill.io/v1/customers/cus_abc123?company_id=com_abc123" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "status": "active"
  }'
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. 
curl -X DELETE "https://api.corebill.io/v1/customers/cus_abc123?company_id=com_abc123" \
  -H "Authorization: Bearer sk_live_your_api_key"

​
Customer Fields

FieldTypeRequiredDescription
namestringYesCustomer display name
countrystringYesISO-2 country code
emailstringNoContact email
phonestringNoContact phone
citystringNoCity
currencystringNoCurrency code (default: USD)
legal_namestringNoLegal/fiscal name
legal_addressstringNoLegal address
legal_vatstringNoVAT/Tax ID
zipcodestringNoPostal code
notesstringNoInternal notes