Customers
Public API v1 · Create, list, retrieve, and update customers for your business
Summary
Customers represent the people or businesses you bill. Create a customer before attaching payment methods or subscriptions. All customer endpoints are scoped to the business resolved from your secret key.
Either name or email is required on create. When an email is provided, create is idempotent: a matching email for the same business returns the existing customer (200) instead of creating a duplicate (201).
Authentication
Server-to-server. Authenticate with a RapidCents rc_sk_ secret key.
Authorization: Bearer {rc_sk_secret_key}
Content-Type: application/json
Accept: application/jsonBase URL pattern: /api/v1/customers. Business is resolved from the secret key and is never accepted from the request body.
Customer Object
{
"id": "customer-uuid",
"object": "customer",
"name": "Jane Doe",
"email": "[email protected]",
"phone": "+15551234567",
"metadata": {},
"created": 1710000000
}| Field | Type | Description |
|---|---|---|
id | string (UUID) | Unique customer identifier |
object | string | Always customer |
name | string | null | Full name (stored as first + last) |
email | string | null | Normalized lowercase email |
phone | string | null | Phone number |
metadata | object | Key/value bag for your own data |
created | integer | Unix timestamp |
Create Customer
POST /api/v1/customers
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Either name or email | Customer full name (max 255) |
email | string | Either name or email | Valid email (max 255). Dedupes by business + email |
phone | string | No | Phone (max 50) |
metadata | object | No | Arbitrary key/value metadata |
POST /api/v1/customers
Authorization: Bearer {rc_sk_...}
{
"name": "Jane Doe",
"email": "[email protected]",
"phone": "+15551234567"
}{
"id": "customer-uuid",
"object": "customer",
"name": "Jane Doe",
"email": "[email protected]",
"phone": "+15551234567",
"metadata": {},
"created": 1710000000
}List Customers
GET /api/v1/customers
Returns a cursor-paginated list of customers for the authenticated business.
Query Parameters
| Param | Type | Description |
|---|---|---|
limit | integer | Page size (1–100, default 10) |
starting_after | string | Cursor: return records after this id |
ending_before | string | Cursor: return records before this id |
{
"object": "list",
"data": [ { /* customer */ } ],
"has_more": false
}Get Customer
GET /api/v1/customers/{customer}
Retrieves a single customer by id. Returns 404 if the customer does not belong to the authenticated business.
Update Customer
PATCH /api/v1/customers/{customer}
Partially updates customer fields. Changing email to an address already used by another customer in the same business returns 409.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | null | No | Replace full name |
email | string | null | No | Replace email (must be unique per business) |
phone | string | null | No | Replace phone |
metadata | object | null | No | Replace metadata object |
PATCH /api/v1/customers/{customer}
Authorization: Bearer {rc_sk_...}
{
"name": "Jane Doe Updated",
"phone": "+15559876543"
}List Customer Payment Methods
GET /api/v1/customers/{customer}/payment_methods
Lists stored payment methods for a customer. Same pagination query params as list customers (limit, starting_after, ending_before).
Creating or deleting payment methods uses /api/v1/payment_methods (tokenize card). That surface is documented separately from this Customers guide.
All Endpoints
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/customers | Create customer |
| GET | /api/v1/customers | List customers |
| GET | /api/v1/customers/{id} | Get customer |
| PATCH | /api/v1/customers/{id} | Update customer |
| GET | /api/v1/customers/{id}/payment_methods | List customer payment methods |
Error Handling
| HTTP Code | Scenario | Description |
|---|---|---|
422 | Validation error | Missing name and email, invalid email, or field constraints |
409 | Conflict | Email already used by another customer in this business |
404 | Not found | Customer does not exist for this business |
401 | Unauthorized | Missing or invalid secret key |