Failed Payment Recovery

Billing Contact API

Send payment recovery emails to multiple billing contacts

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:

ParameterTypeRequiredDescription
userIdstringYesYour internal user identifier
data.emailstringYesUser's email address
data.phonestringNoUser's phone number
data.namestringYesUser's full name
data.billingAdminbooleanYesSet to true to send payment recovery emails
data.[custom]anyNoAdditional fields available for email merge tags

Example request

{
  "customerId": "cus_xyz",
  "users": [
    {
      "userId": "user_123",
      "data": {
        "name": "Sarah Wilson",
        "email": "[email protected]",
        "phone": "+1235557890",
        "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]",
          "phone": "+1235557890",
          "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.