Api Reference
Customers
On this page, we'll dive into the different customer endpoints you can use to manage your Vatly customers programmatically.
The Customer API Resource
Below you'll find all properties for the Vatly Customer API resource.
Properties
| Name | Type | Description |
|---|---|---|
id | string | Unique identifier for the customer (starts with cus_). |
resource | string | The resource type. Always customer. |
testmode | boolean | Whether this resource is in test mode. |
email | string | The email address for the customer. |
createdAt | string | When this customer was created (ISO 8601 format). |
metadata | object | null | Arbitrary key-value metadata for your application. Up to 50 keys, with key names up to 40 characters and values up to 500 characters. |
links | object | HATEOAS links to related resources. Contains self link. |
List all customers
GET /v1/customers
This endpoint allows you to retrieve a paginated list of all your customers. By default, a maximum of ten customers are shown per page.
Optional attributes
| Name | Type | Description |
|---|---|---|
limit | integer | The number of customers to return (default: 10, max: 100). |
startingAfter | string | A cursor for use in pagination. Returns results after this customer ID. |
endingBefore | string | A cursor for use in pagination. Returns results before this customer ID. |
curl -G https://api.vatly.com/v1/customers \
-H "Authorization: Bearer live_your_api_key_here" \
-d limit=10
$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');
$customers = $vatly->customers->page();
{
"data": [
{
"id": "cus_abc123def456",
"resource": "customer",
"testmode": false,
"email": "john@example.com",
"createdAt": "2024-01-15T10:30:00Z",
"metadata": {},
"links": {
"self": {
"href": "https://api.vatly.com/v1/customers/cus_abc123def456",
"type": "application/json"
}
}
}
],
"links": {
"self": {
"href": "https://api.vatly.com/v1/customers?limit=10",
"type": "application/json"
},
"next": {
"href": "https://api.vatly.com/v1/customers?startingAfter=cus_abc123def456&limit=10",
"type": "application/json"
},
"prev": null
},
"count": 1
}
Create a customer
POST /v1/customers
This endpoint allows you to add a new customer to Vatly. To add a customer, you must provide their email address.
Required attributes
| Name | Type | Description |
|---|---|---|
email | string | The email address for the customer. |
Optional attributes
| Name | Type | Description |
|---|---|---|
metadata | object | Arbitrary key-value metadata for your application. |
curl https://api.vatly.com/v1/customers \
-H "Authorization: Bearer live_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"email": "john@example.com"}'
$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');
$vatly->customers->create([
'email' => 'john@example.com',
]);
{
"id": "cus_abc123def456",
"resource": "customer",
"testmode": false,
"email": "john@example.com",
"createdAt": "2024-01-15T10:30:00Z",
"metadata": {},
"links": {
"self": {
"href": "https://api.vatly.com/v1/customers/cus_abc123def456",
"type": "application/json"
}
}
}
Retrieve a customer
GET /v1/customers/:id
This endpoint allows you to retrieve a customer by providing their Vatly id. Refer to the list at the top of this page to see which properties are included with customer objects.
curl https://api.vatly.com/v1/customers/cus_abc123def456 \
-H "Authorization: Bearer live_your_api_key_here"
$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');
$vatly->customers->get('cus_abc123def456');
{
"id": "cus_abc123def456",
"resource": "customer",
"testmode": false,
"email": "john@example.com",
"createdAt": "2024-01-15T10:30:00Z",
"metadata": {},
"links": {
"self": {
"href": "https://api.vatly.com/v1/customers/cus_abc123def456",
"type": "application/json"
}
}
}