Customers API
Customers are the account records that subscriptions, invoices, payment methods, and portal access attach to.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /customers |
List customers |
| POST | /customers |
Create a customer |
| GET | /customers/{customer_id} |
Retrieve a customer |
The Customer object
{
"id": 123,
"object": "customer",
"name": "Acme Corp",
"contact_name": "Jane Buyer",
"email": "[email protected]",
"phone": "+1-555-0123",
"address_line1": "123 Main St",
"address_line2": null,
"city": "San Francisco",
"state_province": "CA",
"postal_code": "94105",
"country": "US",
"tax_exempt": false,
"tax_id": null,
"credit_balance": "0.00000000",
"auto_pay_enabled": true,
"created_at": "2026-07-07T10:00:00Z",
"updated_at": "2026-07-07T10:00:00Z"
}
Create a customer
curl https://api.floatless.com/api/public/v1/customers \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Corp",
"email": "[email protected]",
"contact_name": "Jane Buyer",
"address_line1": "123 Main St",
"city": "San Francisco",
"state_province": "CA",
"postal_code": "94105",
"country": "US"
}'
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Customer or company name (1–255 characters) |
email |
string | No | Billing email (must be a valid email format) |
contact_name |
string | No | Primary contact name (≤255 characters) |
phone |
string | No | Phone number (≤50 characters) |
address_line1 |
string | No | Street address (≤255 characters) |
address_line2 |
string | No | Address line 2 (≤255 characters) |
city |
string | No | City (≤100 characters) |
state_province |
string | No | State or province (≤50 characters) |
postal_code |
string | No | Postal or ZIP code (≤20 characters) |
country |
string | No | Two-letter country code, defaults to CA |
tax_exempt |
boolean | No | Tax exempt status (default false) |
tax_id |
string | No | Tax identification number (≤100 characters) |
notes |
string | No | Internal notes |
`notes` is write-only through the API: it is stored but not returned in customer responses. Also note `country` defaults to `CA` when omitted — set it explicitly for US customers.
Creating a customer returns 201 with the customer object. Invalid email formats or over-length fields return 422 VALIDATION_ERROR with per-field details (see Errors).
List customers
curl https://api.floatless.com/api/public/v1/customers?limit=25&offset=0 \
-H "Authorization: Bearer sk_live_..."
Query parameters
| Parameter | Type | Description |
|---|---|---|
limit |
integer | Number of results, 1 to 100 |
offset |
integer | Pagination offset |
Retrieve a customer
curl https://api.floatless.com/api/public/v1/customers/123 \
-H "Authorization: Bearer sk_live_..."