Add nonBillableUsage to GitlabSubscriptionUsage
What does this MR do and why?
Adds nonBillableUsage to GitlabSubscriptionUsage, so the GitLab Credits dashboards (group dashboard on GitLab.com, instance dashboard on self-managed) can show usage that was not billed, per product and skip reason.
It proxies CustomersDot's new gitlabCreditsUsage.nonBillableUsage field:
- Client:
SubscriptionUsageClient#get_non_billable_usagesends its own query (GET_NON_BILLABLE_USAGE_QUERY), so a failure here does not failcreditsUsed/dailyUsage. It respectsflowTypes, likeget_subscription_usage. - Failure handling: when its ClickHouse read fails, CustomersDot returns
nonBillableUsage: nullwith the errornonBillableUsage is temporarily unavailable. The client logs a warning and returnssuccess: false, without raising or reporting to Sentry, so the field resolves tonulland the rest ofsubscriptionUsagestill resolves. Any other error raises as before. - Model:
GitlabSubscriptions::SubscriptionUsage#non_billable_usagemaps the response toNonBillableUsageStructs, reusingDailyUsage. - GraphQL: new
GitlabSubscriptionUsageNonBillableUsagetype with:productId: matchesGitlabSubscriptionUsageProduct.id.skipReason: nullable;nullmeans the event has no recorded reason.totalCreditsUseddailyUsage
These totals are not included in creditsUsed or dailyUsage, so billed totals still reconcile with Customers Portal.
The frontend (stacked chart in wallet_agnostic_credits_dashboard) follows in a separate MR, for multi-version compatibility.
References
- Closes https://gitlab.com/gitlab-org/gitlab/-/work_items/632384
- Epic: https://gitlab.com/groups/gitlab-org/-/work_items/23876
- CustomersDot counterpart MR: https://gitlab.com/gitlab-org/customers-gitlab-com/-/merge_requests/17365
- Billing engine writer of
skip_reason(draft): https://gitlab.com/gitlab-org/customers-gitlab-com/-/merge_requests/17371 - Similar MR: !254129 (merged)
Screenshots or screen recordings
How to set up and validate locally
-
Run GDK in SaaS mode (
export GITLAB_SIMULATE_SAAS=1 gdk restart). -
Run CustomersDot locally on the branch from https://gitlab.com/gitlab-org/customers-gitlab-com/-/merge_requests/17365, connected to your GDK.
-
Have a group with GitLab Credits and generate usage, including some events with
SkipConsumption = trueinusage_billing_enriched(with and without askip_reasonkey inMetadata). -
As a group owner, run this in https://gdk.test:3443/-/graphql-explorer:
query { subscriptionUsage(namespacePath: "test-group-hvs-101", startDate: "2026-10-01", endDate: "2026-10-06") { creditsUsed nonBillableUsage { productId skipReason totalCreditsUsed dailyUsage { date creditsUsed } } } } -
Check that
nonBillableUsagelists one entry per product and skip reason,skipReasonisnullfor events without a reason, andcreditsUsedis unchanged.
MR acceptance checklist
Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

