Billing Contact API
The Billing Contact API lets you configure multiple billing contacts for each customer, improving payment recovery rates for team accounts and organizations with multiple administrators.
By default, Churnkey sends payment recovery emails only to the primary email address stored in the Stripe Customer object. With the Billing Contact API, you can specify additional contacts who should receive payment recovery communications.
Add billing contacts
You can update billing contacts for a single customer or in bulk.
Single customer update
Update billing contacts for a single customer.
Endpoint
POST https://api.churnkey.co/v1/api/events/customer-update/set-users
Authentication
All requests require your App ID and Data API Key, which you can find in your Churnkey Dashboard.
{
"Content-Type": "application/json"
"x-ck-api-key": "YOUR_DATA_API_KEY"
"x-ck-app": "YOUR_APP_ID"
}
Request body
{
"customerId": string; // Stripe customer ID
"users": User[]; // Array of user objects
}
The users array accepts objects with the following parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | Your internal user identifier |
data.email | string | Yes | User's email address |
data.name | string | Yes | User's full name |
data.billingAdmin | boolean | Yes | Set to true to send payment recovery emails |
data.[custom] | any | No | Additional fields available for email merge tags |
Example request
{
"customerId": "cus_xyz",
"users": [
{
"userId": "user_123",
"data": {
"name": "Sarah Wilson",
"email": "[email protected]",
"billingAdmin": true,
"role": "Account Owner"
}
},
{
"userId": "user_456",
"data": {
"name": "Alex Chen",
"email": "[email protected]",
"billingAdmin": true,
"role": "Billing Admin"
}
}
]
}
Bulk update
Update billing contacts for multiple customers at once.
Endpoint
POST https://api.churnkey.co/v1/api/events/customer-update/set-users/bulk
The bulk endpoint accepts an array of customer objects, using the same structure as the single customer update.
Example request
[
{
"customerId": "cus_xyz1",
"users": [
{
"userId": "user_123",
"data": {
"name": "Sarah Wilson",
"email": "[email protected]",
"billingAdmin": true
}
}
]
},
{
"customerId": "cus_xyz2",
"users": [
{
"userId": "user_456",
"data": {
"name": "Alex Chen",
"email": "[email protected]",
"billingAdmin": true
}
}
]
}
]
How it works
When you set billingAdmin: true for a user, they'll receive payment recovery communications when a payment fails. This helps ensure that the right people in your customers' organizations are notified about payment issues, improving recovery rates.
Any additional fields you include in the data object will be available as merge fields in your email templates.