Flagsmith / Flagsmith/flagsmith

Integrate Chargebee Metered Billing

Open
#7,970 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
6.6k
Forks
567
Avg merge
1d 13h
Merged PRs (30d)
121

Description

Spiked from https://github.com/Flagsmith/flagsmith/issues/7923

Currently overage billing happens in [`charge_for_api_call_count_overages`](https://github.com/Flagsmith/flagsmith/blob/a7b0d217f714d4c59ae78023b3d7147d6c5da095/api/organisations/tasks.py#L159), and uses `OrganisationSubscriptionInformationCache` to push overage charges to Chargebee as [100K addons](https://github.com/Flagsmith/flagsmith/blob/a7b0d217f714d4c59ae78023b3d7147d6c5da095/api/organisations/chargebee/constants.py#L1-L2) (set up in Chargebee). The goal of this issue is to integrate with Chargebee's proper tool for this: [Metered Billing](https://www.chargebee.com/docs/billing/2.0/usage-based-billing/metered_billing), and have Chargebee handle the overage billing logic natively.

The scope is limited to adding an integration that co-exists with the current overage logic, while we transition to Metered Billing using a FoF feature flag `chargebee_metered_billing`. Responsibility is further cleaned up after GA (see https://github.com/Flagsmith/flagsmith/issues/7971).

> [!NOTE]
> It seems that Chargebee is moving towards [Usage-Based Billing](https://www.chargebee.com/docs/billing/2.0/usage-based-billing/understanding-usages) and may sunset Metered Billing in the future. Regardless, we decided to move forward with Metered Billing because:
> - As of today, UBB is not yet generally available in Chargebee production.
> - We encountered issues while experimenting with UBB, and had our account set to Metered Billing automatically.
> - Integration footprint is lightweight.

## Acceptance criteria

- [ ] **Live** site in Chargebee has Metered Billing enabled and a single **metered add-on** with a per-unit price. See _Chargebee setup_ below.
- [ ] Usage data is pushed to Chargebee via `Usage.create` (Metered Billing) **every hour**:
- Only for customers having `chargebee_metered_billing` enabled.
- Attach the add-on to the subscription ([`update_for_items`](https://apidocs.chargebee.com/docs/api/subscriptions/update-subscription-for-items)) idempotently so Chargebee tracks overages.
- Pull data from InfluxDB data (kept as usage storage) via [`get_total_events_count`](https://github.com/Flagsmith/flagsmith/blob/a7b0d217f714d4c59ae78023b3d7147d6c5da095/api/app_analytics/analytics_db_service.py#L229).
- Push data points with dedupe key `{subscription_id}:{period_start}` on a _replace_ policy, i.e. each data point is the accumulated **overage** for the subscription and period, in the add-on's unit of 1000 calls: `round((get_total_events_count() − allowed_30d_api_calls) / 1000)` (allowance is already sourced from Chargebee).
- [ ] Overages are calculated and charged by Chargebee — the task `charge_for_api_call_count_overages` (current overage logic) ignores subscriptions with `chargebee_metered_billing` enabled.
- [ ] Turning `chargebee_metered_billing` on for a customer mid-term means the next invoice uses Metered Billing data.

## Chargebee setup

Click to expand

```sh
# Prereqs: item family `flagsmith` exists; Metered Billing enabled on the site.
# env: CB_SITE, CB_API_KEY

# 1. Metered overage add-on (unit = 1000 calls)
curl -s "https://$CB_SITE.chargebee.com/api/v2/items" -u "$CB_API_KEY:" \
-d id=api-calls-overage \
-d name="API Calls Overage" \
-d type=addon \
-d item_family_id=flagsmith \
-d metered=true \
-d usage_calculation=sum_of_usages \
-d unit="1000 calls"

# 2. Per-unit price: 5c per 1000 calls (= $50 / 1M). Repeat per currency sold.
curl -s "https://$CB_SITE.chargebee.com/api/v2/item_prices" -u "$CB_API_KEY:" \
-d id=api-calls-overage-USD \
-d name="API Calls Overage (USD)" \
-d item_id=api-calls-overage \
-d currency_code=USD \
-d pricing_model=per_unit \
-d price=5 \
-d period=1 \
-d period_unit=month
```

Contributor guide

Open the contributing guide

Research direction

Start with api/organisations/tasks.py, api/organisations/chargebee/constants.py, and api/app_analytics/analytics_db_service.py, especially charge_for_api_call_count_overages and get_total_events_count. Trace the existing Chargebee integration and feature-flag handling before adding the hourly Usage.create flow. Done means flagged customers report accumulated overage usage, existing logic skips them, and mid-term activation affects the next invoice.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend, payments
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.