fix(API Usage): API usage notification emails fire at 90%/100% while org is far below plan limit

[bardock-2393]

Thanks for submitting a PR! Please check the boxes below:

• I have read the Contributing Guide.
• I have added information to docs/ if required so people know about the feature.
• I have filled in the "Changes" section below.
• I have filled in the "How did you test this code" section below.

Changes

OrganisationSubscriptionInformationCache.allowed_30d_api_calls can go stale without anyone noticing: chargebee_updated_at was declared on the model but never populated, and a failed Chargebee sync in get_subscription_metadata_from_id was silently swallowed with no logging. Once the cache holds a lower limit than the org's real plan, usage-alert emails get computed against the wrong denominator and fire even though real usage is well under the actual limit.

• Log Chargebee sync failures instead of silently swallowing them.
• Stamp chargebee_updated_at when a Chargebee sync succeeds.
• Skip sending a usage alert (with a warning log) for Chargebee-billed organisations whose cache hasn't synced recently, rather than trusting a limit that may be wrong.
• Regenerate the events catalogue for the 3 new log events.

Contributes to #7976

Review effort: 2/5

How did you test this code?

Added unit tests covering: never-synced cache, stale cache, and fresh cache (regression) for handle_api_usage_notification_for_organisation; the Chargebee sync-failure log; and the chargebee_updated_at stamping in update_caches. Ran the full affected test files (test_unit_organisations_tasks.py, test_unit_organisations_subscription_info_cache.py, tests/unit/organisations/chargebee/) locally against Postgres — all pass (91 tests). Also ran mypy and ruff on all changed files, and the repo's pre-commit/pre-push hooks (including generate-docs and api-typecheck).

[vercel]

@bardock-2393 is attempting to deploy a commit to the Flagsmith Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

📝 Walkthrough

Walkthrough

Chargebee subscription metadata failures now emit structured warnings while returning no metadata. Successful cache synchronisation records chargebee_updated_at, and failed synchronisation leaves existing cached limits and timestamps unchanged. Chargebee API usage notifications skip evaluation when the cache has never synced or is older than twelve hours. Unit tests cover logging, cache preservation, stale and fresh cache behaviour, and notification delivery. The observability catalogue documents the new events and updated source locations.

Estimated code review effort: 3 (Moderate) | ~25 minutes

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 3cac4f94-c6da-4ab8-b683-222787c7d99d

📥 Commits

Reviewing files that changed from the base of the PR and between 2e6017b and 78575a9.

📒 Files selected for processing (8)

• api/organisations/chargebee/chargebee.py
• api/organisations/constants.py
• api/organisations/subscription_info_cache.py
• api/organisations/task_helpers.py
• api/tests/unit/organisations/chargebee/test_unit_chargebee_chargebee.py
• api/tests/unit/organisations/test_unit_organisations_subscription_info_cache.py
• api/tests/unit/organisations/test_unit_organisations_tasks.py
• docs/docs/deployment-self-hosting/observability/_events-catalogue.md