Customers API
Manage customer information, store contact details, and track customer payment history with idempotent operations.
Customer Management
The Customers API allows you to create and manage customer records for use with invoices, payments, and quotations.
Idempotency Support
Customer creation supports idempotency using email addresses to prevent duplicate records.
Create Customer
POST
/api/v1/customers
Update Customer
PATCH
/api/v1/customers/{id}
List Customers
GET
/api/v1/customers
Get Customer Details
GET
/api/v1/customers/{id}
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Customer's full name |
| string | Yes | Unique email address | |
| phone | string | No | Phone number with country code |
| company | string | No | Company or organization name |
| address | object | No | Customer's address details |
| metadata | object | No | Custom key-value pairs |
Idempotency
Customer creation is idempotent based on email addresses. If you attempt to create a customer with an existing email, the API will return the existing customer record instead of creating a duplicate.
Idempotency Key
The email address serves as a natural idempotency key. You can safely retry customer creation requests without worrying about duplicates.
Best Practices
Use Metadata
Store custom attributes in the metadata field to track customer segments, preferences, or other business-specific data.
Validate Email Addresses
Ensure email addresses are valid before creating customers to maintain data quality and prevent delivery issues.
Phone Number Format
Include country codes in phone numbers for international compatibility (e.g., +1868-555-0123).