Spike: Subscription change events during GitLab sync

Problem

On GitLab.com we track customer's subscriptions via the GitlabSubscription model which contains some key data for tracking seat usage and plan:

• max_seats_used - the maximum number of paid seats used during the subscription term
• max_seats_used_changed_at - the last time the above was changed
• seats_owed - the number seats over the licensed amount (overages)
• trial - a boolean indicating if the subscription is a trial or not
• hosted_plan_id - the ID of the Plan the subscription has

Currently, whenever a GitlabSubscription record is updated, we have to try and establish whether or not we want to reset the max_seats_used based on what is changing.

We need to do this because we don't want to carry over an old value from a previous subscription term, or in other scenarios such as converting from a trial to a paid plan.

This is problematic because we have to essentially guess based on what has changed and to what value (example)

Going forwards, this will be hard to maintain as we add more ways in which we might want to adjust the stats, and will also be difficult to capture all edge cases.

Proposal

As originally suggested in gitlab!110768 (comment 1289263820), instead, CustomersDot could essentially instruct GitLab explicitly about what action has occurred, e.g. a new subscription term, expiry, trial start/end, etc:

All of this kinda makes me wish we had dedicated create, renew, update_entitlements and expire subscription endpoints/states on GitLab, so customers-dot can tell GitLab exactly what kind of subscription changes are being made. Then we could have dedicated services that know how to update statistics for each of these changes, and we wouldn't have to rely on the data state to "guess" so much.

This issue is to investigate/discuss what would be involved / the best approach to take

Result

A good result for this spike would be:

• an estimation of effort involved in implementing this change
• the steps required to deliver the change