Chargebee

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#

Every plan includes one billing connection per site, Free too; Growth and Scale allow any number. See 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.

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.

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.