---
title: Billing Contact API
description: 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](https://docs.stripe.com/api/customers/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**

```bash
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](https://app.churnkey.co/account).

```bash
{
    "Content-Type": "application/json"
    "x-ck-api-key": "YOUR_DATA_API_KEY"
    "x-ck-app": "YOUR_APP_ID"
}
```

**Request body**

```typescript
{
    "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.phone`        | `string`  | No       | User's phone number                              |
| `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**

```json
{
  "customerId": "cus_xyz",
  "users": [
    {
      "userId": "user_123",
      "data": {
        "name": "Sarah Wilson",
        "email": "sarah@example.com",
        "phone": "+1235557890",
        "billingAdmin": true,
        "role": "Account Owner"
      }
    },
    {
      "userId": "user_456",
      "data": {
        "name": "Alex Chen",
        "email": "alex@example.com",
        "billingAdmin": true,
        "role": "Billing Admin"
      }
    }
  ]
}
```

### Bulk update

Update billing contacts for multiple customers at once.

**Endpoint**

```bash
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**

```json
[
  {
    "customerId": "cus_xyz1",
    "users": [
      {
        "userId": "user_123",
        "data": {
          "name": "Sarah Wilson",
          "email": "sarah@example.com",
          "phone": "+1235557890",
          "billingAdmin": true
        }
      }
    ]
  },
  {
    "customerId": "cus_xyz2",
    "users": [
      {
        "userId": "user_456",
        "data": {
          "name": "Alex Chen",
          "email": "alex@example.com",
          "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.