# Chargebee

Connect Chargebee with a read-only API key and a basic-auth webhook so ProductLense records transactions, credit notes and subscriptions.

ProductLense reads your Chargebee customers, subscriptions, transactions and credit notes, on Product Catalog 1.0 or 2.0. ProductLense only reads: it never writes to your Chargebee site, never refunds, cancels or changes anything.

## What you need

| Field | Secret | Where to find it |
|---|---|---|
| Site name | No | The subdomain of your Chargebee site: `{site}.chargebee.com`. |
| API key | Yes | A read-only key from Settings → Configure Chargebee → API Keys. |
| Webhook username | No | The basic-auth username you set on the webhook in Chargebee. ProductLense checks it on every delivery. |
| Webhook password | Yes | The basic-auth password you set on the webhook in Chargebee. |

Every plan includes one billing connection per site, Free too; Growth and Scale allow any number. See [plans and limits](/docs/account/plans-and-limits).

## Permissions

Create a **read-only** API key with access to all resources. ProductLense calls `GET /api/v2/customers`, `/api/v2/subscriptions`, `/api/v2/transactions` and `/api/v2/credit_notes` on your site.

## Set up

1. In Chargebee, open Settings → Configure Chargebee → API Keys and create a read-only key.
2. In ProductLense, open your site's Settings → Billing connections → Chargebee, enter the site name and key, pick a webhook username and password, check the Processor fees estimate, and click Connect and import history.
3. Copy the webhook URL from the connection card.
4. In Chargebee, open Settings → Configure Chargebee → Webhooks, add a webhook with that URL, turn on basic authentication and enter the same username and password.

## Webhook

URL: `https://api.productlense.app/api/webhooks/chargebee/<connection-id>` (ProductLense shows the exact URL after you save).

Events ProductLense uses:

- `payment_succeeded`, `payment_refunded`, `payment_failed`, `refund_initiated`
- every `subscription_*` event
- every `customer_*` event

Each handled event also refreshes the customer and subscription objects Chargebee includes in its content.

Verification: HTTP basic auth on the webhook URL, compared in constant time with the username and password stored on the connection.

## What ProductLense reads

- **Customers**: email, name or company, metadata and custom fields.
- **Subscriptions**: status, interval and amount, on Product Catalog 1.0 and 2.0. `non_renewing` stays active until the term ends.
- **Payments**: payment transactions.
- **Refunds**: refund transactions, plus refunded credit notes with no linked refund transaction (offline refunds).
- **History**: the last 12 months on first connect, then a nightly reconcile at 03:00 UTC from the last sync minus 48 hours.

## How fees are derived

Chargebee does not hold the gateway's processing fee (the fee lives in the gateway, such as Stripe), so every Chargebee payment arrives with a fee of 0.

A fee estimate can be set under Processor fees on the connection card (percent, fixed amount per payment, and its currency), for example your gateway's card rate. It starts at 0 and is applied only to charges that arrive with a zero fee. Estimated fees are flagged, and the dashboard shows the share of fees in a period that is estimated. An estimate is only as accurate as the rate you enter; mixed card types and currencies make the real fee differ.

> [!IMPORTANT]
> Connect Chargebee or its gateway for a given payment, not both. A payment that arrives through both connections is counted twice.

## Match payments to visitors

ProductLense reads the user id from the customer's metadata and custom fields: `pl_user_id`, `user_id`, `userId`, `uid`, then the custom fields `cf_pl_user_id` and `cf_user_id`. Use the same id you pass to `identify`. A ProductLense visitor id in `pl_visitor_id` or `visitor_id` is also accepted. Without either, ProductLense falls back to the customer email, matched to the `email` trait sent with `identify`, or to a user id that is that email.

```bash title="Set the custom field on an existing customer"
curl https://{site}.chargebee.com/api/v2/customers/CUSTOMER_ID \
  -u "$CHARGEBEE_FULL_ACCESS_KEY:" \
  -d cf_pl_user_id=user_123
```

Create the `cf_pl_user_id` custom field on customers in Chargebee first. This call runs from your own backend with a write key; ProductLense's key stays read-only.

See [how payments are attributed](/docs/revenue/attribution).