Flagsmith / Flagsmith/flagsmith
Integrate Chargebee Metered Billing
- 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
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