Subscription change desk for support and success reps

Build me a subscription change desk that our support and customer success reps work out of, so they can make plan changes in Chargebee without anyone handing them a billing admin login. The app is the scoped surface: it does the subscription changes described below and nothing else, so a rep can never wander into refunds, credit notes, catalog editing or anything outside the account they are working. Reps find one account and change one subscription at a time. This is not a churn worklist and not a bulk migration tool, so do not build a ranked queue of at-risk accounts and do not offer changes across a cohort of customers at once. Most accounts looked up here are perfectly healthy and the request is routine, for example move us to the annual plan or add five more seats.

The landing view is a search box. A rep types a person's name, an email address or a company name and gets back matching customers. Query Chargebee with List Customers using its typed filter operators, for example email[is] for an exact address and company[starts_with] or first_name[starts_with] for a name fragment. Chargebee has no fuzzy full text search across customers, so run the sensible filters for whatever the rep typed, merge the results, remove duplicates and show which field matched on each row. Each result row shows the customer name, company, email, customer id and how many active subscriptions they have. Clicking a row opens the account page. Keep recently viewed accounts on the landing view, so a rep in a back and forth conversation can jump straight back without searching again.

The account page is the heart of the app and it answers everything a rep needs before touching anything. Load the customer with Retrieve Customer for the name, company, email and billing details. Load every subscription for that customer with List Subscriptions filtered to the customer id, and load the selected one in full with Retrieve Subscription. For each subscription show the status, every current line item with its item price name and id, quantity, unit amount and billing period, the recurring total, the current term start and end, and the next billing date. Show any change already scheduled for the next term as well, so a rep never stacks a second change on top of one they cannot see. For each subscription call Renewal Estimate and show the next renewal amount and the date it will be charged. Separately call List Payment Sources for the customer and show prominently whether there is a valid payment method on file, with the card brand, last four digits and expiry, and a clear warning when there is no valid card or when the card expires before the next renewal date. A rep about to apply an immediate upgrade needs to know the charge will fail before they tell the customer it worked.

Two data rules matter throughout. Chargebee money amounts are integers in the currency's smallest unit, so divide by the currency's exponent and render real formatted currency everywhere, never a raw integer, and never add amounts in different currencies into a single total. Chargebee timestamps are Unix epoch seconds, so convert them before showing a date or counting days. This is a Product Catalog 2.0 site, so work entirely in items and item prices and never reference the legacy plans and addons model.

From a subscription the rep builds a change. The change types are: switch to a different item price, meaning an upgrade or a downgrade; change the quantity on an existing item; change the billing term; add or remove an addon item price; pause the subscription; resume a paused subscription; cancel the subscription; or discard a change already scheduled for next term. When the rep is picking a new item price, load the options with List Item Prices filtered to the same currency as the subscription and to active price points, and show each option's amount and billing period in plain money, so the rep is choosing between Pro Annual at 1,200.00 USD per year rather than a raw price point id. Every change requires two things before it can go anywhere. First a reason code, chosen from a configurable list, for example customer request, downgrade to retain, upsell, billing error correction, non payment, or other with a required free text note. Second an explicit timing choice between applying immediately, which prorates the current term, and applying at the end of the current term, which changes nothing today. Never preselect the timing quietly, because the difference between those two options is a charge landing on the customer's card today.

The preview is the point of this app, so make it the centre of the change screen and never wire a bare apply button. Before anything is saved, run the matching estimate and show the rep what the change actually costs. Use Update Subscription Estimate For Items for item, quantity, addon and term changes, Pause Subscription Estimate for a pause, Resume Subscription Estimate for a resume, and Cancel Subscription Estimate for a cancellation. Render the result as plain money rather than a raw estimate object: what the subscription costs now against what it will cost after the change, the amount charged or credited today with the proration explained in a sentence the rep can read to the customer on the phone, any credits applied, and the next invoice total with its date. Estimates never write anything to Chargebee, so re-run them freely as the rep adjusts inputs. Treat a preview as bound to the exact inputs that produced it: if the rep edits the item price, quantity, term, timing or anything else, invalidate the previous preview immediately and require a fresh one, so it is impossible to apply a change whose numbers the rep never saw. If an estimate fails, show the Chargebee error inline in plain language and block the apply instead of letting the rep guess.

Some changes are too big for a rep to make alone. In settings an admin sets a monthly value threshold and a list of who counts as an approver. Any cancellation, and any downgrade whose recurring monthly value falls by at or above that threshold, requires manager approval. Everything below it the rep applies on their own, which is the whole point of the desk. When a change needs approval the rep submits it instead of applying it, and the request is stored with the previewed numbers attached, along with the reason code, the timing choice, the customer and subscription, and who requested it and when. Approvers get an approvals queue in the app showing every pending request with the same money preview the rep saw, and they approve or reject with a comment. On approval, re-run the estimate before applying, because time has passed since the preview was taken, and if the numbers have moved materially show the approver the difference and make them confirm again rather than applying stale figures. A rejected request goes back to the rep with the comment attached.

Applying runs the operation matching the change type and honours the immediate or end of term choice: Update Subscription For Items for item, quantity, addon and term changes, Pause Subscription for a pause, Resume Subscription for a resume, Remove Scheduled Changes to discard a change already scheduled for next term, and Cancel Subscription For Items for a cancellation. After a successful apply, re-fetch with Retrieve Subscription and re-render the account page from the real returned state rather than from what the app assumed would happen. If the apply fails, show the Chargebee error in plain language, leave the account page unchanged, and keep the rep's change intact so they can correct it and retry. Only a successful apply may produce the audit records below, so a failed change never leaves a note claiming it happened.

Every applied change writes two audit records automatically. First, in HubSpot, find the customer's company with Search Companies, matching on the company name and the email domain, then write the record with Create Note associated to that company. The note says what changed and from what to what, the money impact including anything charged or credited today and the new recurring amount, the reason code, the timing choice, who applied it, who approved it when it went through approval, and the Chargebee subscription id. If no company matches, or several plausibly match, show the rep the candidates and let them pick or skip. Never guess, because a billing note on the wrong company is worse than no note at all. Second, post a one line audit entry to a billing channel in Slack using Slack Bot's Send a Message with Slack mrkdwn formatting, covering the customer, the subscription, what changed, the money impact, the reason code, the timing and the rep. Let an admin pick the channel with List Channels and remember it. This line is an audit trail, so it posts as the bot for every change regardless of which rep made it.

Keep an in-app change log of every applied change, holding the preview snapshot taken at the time along with the reason code, timing, rep and approver. Show it two ways: on each account page, so the next rep who opens that customer sees what already happened and does not repeat a change, and as a global log filterable by reason code, by rep and by date range, so a manager can review a month of changes in one place. Persist across sessions the change log, pending and decided approval requests, the reason code list, the approval threshold and approver list, the Slack channel and each rep's recently viewed accounts. Each rep sees their own requests and recent accounts, while approvers see the full queue.