feat(billing): Implement last month usage charging on subscription cancellation #296

gentamura · 2025-01-07T04:16:24Z

Summary

Implement proper final billing handling when a subscription is cancelled, ensuring accurate billing for the last period of usage and maintaining data consistency.

Related issue

NONE

Changes

Added handleInvoiceCreation module to manage invoice processing
Added pay function for proper invoice state transitions
Added subscription data synchronisation after cancellation

Testing

Subscription cancellation flow tested
Verified correct invoice state transitions (draft → paid)
Confirmed database synchronisation after subscription cancellation

Other information

Billing state transitions follow Stripe's documentation: https://support.stripe.com/questions/invoice-states
Test clock simulation can be enabled for development testing
Adding the agent time charge manually is both time-consuming and expensive, so it can be done in the stripe cli as follows. As this is only a registration to stripe, the db is not updated, so the ui usage of the application remains unchanged.

stripe billing meter_events create \
  --event-name=agent_time_charge \
  -d ‘payload[value]’=256 \
  -d ‘payload[stripe_customer_id]’={{customer_id}}

Add STRIPE_TEST_CLOCK_ENABLED flag to control timestamp generation behavior: - In test mode: Use current time for simulation - In production: Use period end time minus buffer for accurate billing This change improves testing capabilities while maintaining proper production behavior for usage-based billing calculations.

…bscriptions Remove redundant comments and consolidate invoice handling logic: - Remove TODO comment and old conditional structure - Replace with cleaner invoice validation check - Prepare for implementing proper subscription cancellation processing The changes streamline the webhook handler code while maintaining functionality for canceled subscription scenarios.

vercel · 2025-01-07T04:16:29Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
giselle	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Feb 6, 2025 5:19am

… handling Split invoice processing into smaller, focused functions: - Extract finalizeAndPayInvoice into separate function - Add early return for non-canceled subscriptions - Improve code organization with clear responsibility separation This refactor enhances error handling and makes the code more maintainable by following single responsibility principle.

gentamura · 2025-01-07T05:25:56Z

app/webhooks/stripe/route.ts

@@ -82,33 +83,20 @@ export async function POST(req: Request) {
 					);
 				}
 				await handleSubscriptionCancellation(event.data.object);
+				await upsertSubscription(event.data.object.id);


📝 When a subscription expires and the subscription is cancelled, customer.subscription.updated does not fire, so the above method is executed on customer.subscription.deleted and the database is updated appropriately.

services/usage-based-billing/user-seat.ts

gentamura · 2025-01-07T05:33:44Z

app/webhooks/stripe/handle-invoice-creation.ts

+
+async function finalizeAndPayInvoice(invoiceId: string) {
+	try {
+		await stripe.invoices.finalizeInvoice(invoiceId);


📝 Update from Draft to Open with this method.

ref: https://support.stripe.com/questions/invoice-states?locale=en-US

Can we use auto_advance parameter here?
If we can, we would skip to call invoices.pay, invoices.send..., or so manually.
Stripe would care them.

https://docs.stripe.com/api/invoices/finalize?api-version=2024-11-20.acacia#finalize_invoice-auto_advance

@satococoa

I will keep you posted on the progress along the way.

I ran it with await stripe.invoices.finalizeInvoice(invoice.id, { auto_advance: true }) and the flow was as follows.

Simulation proceeds until the end of the period and the invoice is updated from draft to open for the metered invoice.

automatic collection of the invoice is executed one hour after the invoice is issued, so the simulation proceeds to one hour later

Assumed to be paid at this time, but remained open previously and payment is not completed

Continue to check.

@satococoa
It seems that running auto_advance: true in finalizeInvoice after cancelling a subscription is not working correctly (it works like auto_advance: false), so I also checked with Stripe support and found the following method to run. The following method is called

giselle/app/webhooks/stripe/handle-invoice-creation.ts

Line 19 in 9ba3e19

await stripe.invoices.pay(invoice.id);

If the subscription is cancelled and there are usage fees remaining, a draft invoice for the usage fees will be created at the end of the subscription period.
Based on this invoice, the payment method is executed to complete the billing process and execute the actual payment.

app/webhooks/stripe/handle-invoice-creation.ts

Add upsertSubscription call after handleSubscriptionCancellation to ensure subscription data is properly synchronized in the database when a subscription is canceled. This ensures our system maintains accurate subscription state after cancellation processing.

app/webhooks/stripe/route.ts

gentamura · 2025-01-07T06:42:12Z

@satococoa review, please 🙏

satococoa

Thank you!
Could you check my comments, please?

satococoa · 2025-01-08T00:48:49Z

app/webhooks/stripe/handle-invoice-creation.ts

+
+async function finalizeAndPayInvoice(invoiceId: string) {
+	try {
+		await stripe.invoices.finalizeInvoice(invoiceId);


Can we use auto_advance parameter here?
If we can, we would skip to call invoices.pay, invoices.send..., or so manually.
Stripe would care them.

https://docs.stripe.com/api/invoices/finalize?api-version=2024-11-20.acacia#finalize_invoice-auto_advance

satococoa · 2025-01-08T00:52:39Z

services/usage-based-billing/user-seat.ts

Thank you, but you do not have to care about this in this pull request.
Because I changed user sear reporting logic in #294.

…-deletion

- Remove unnecessary finalization step before payment - Directly process invoice payment - Remove error handling wrapper for cleaner flow

gentamura · 2025-02-06T04:52:57Z

@satococoa review, please 🙏

satococoa

Thank you!
Now it's very clear and straightforward! 👍

satococoa · 2025-02-06T05:00:33Z

app/webhooks/stripe/handle-invoice-creation.ts

+	const subscription = await stripe.subscriptions.retrieve(
+		invoice.subscription,
+	);
+
+	if (subscription.status !== "canceled") {
+		return;
+	}
+
+	await stripe.invoices.pay(invoice.id);


Could you add a comment explaining why we need to call pay when a subscription is canceled?

For example:
When a subscription is canceled, we should charge for usage-based billing from the previous billing cycle. The final invoice, which includes these charges, will be automatically created but will not be processed for payment. Therefore, we need to handle this case manually.

Added 0ff5641 👍

gentamura · 2025-02-06T05:17:49Z

@shige @toyamarinyon review, please 🙏

shige

LGTM! 💳

gentamura · 2025-02-07T00:05:37Z

Thank you for reviewers 🚀

gentamura added 2 commits January 7, 2025 12:55

gentamura force-pushed the feat/charge-last-month-usage-on-subscription-deletion branch from d79ae15 to edfa1aa Compare January 7, 2025 04:17

vercel bot had a problem deploying to Preview January 7, 2025 04:57 Failure

gentamura commented Jan 7, 2025

View reviewed changes

vercel bot had a problem deploying to Preview January 7, 2025 05:27 Failure

gentamura commented Jan 7, 2025

View reviewed changes

services/usage-based-billing/user-seat.ts Outdated Show resolved Hide resolved

gentamura commented Jan 7, 2025

View reviewed changes

app/webhooks/stripe/handle-invoice-creation.ts Outdated Show resolved Hide resolved

gentamura force-pushed the feat/charge-last-month-usage-on-subscription-deletion branch from a10f8f9 to 6ddee1e Compare January 7, 2025 05:44

gentamura commented Jan 7, 2025

View reviewed changes

app/webhooks/stripe/route.ts Outdated Show resolved Hide resolved

vercel bot had a problem deploying to Preview January 7, 2025 05:54 Failure

Remove a comment

49b2633

vercel bot deployed to Preview January 7, 2025 05:58 View deployment

gentamura changed the title ~~Feat/charge last month usage on subscription deletion~~ feat(billing): Implement last month usage charging on subscription cancellation Jan 7, 2025

gentamura self-assigned this Jan 7, 2025

gentamura requested a review from satococoa January 7, 2025 06:41

gentamura marked this pull request as ready for review January 7, 2025 06:41

gentamura requested review from shige and toyamarinyon as code owners January 7, 2025 06:41

satococoa reviewed Jan 8, 2025

View reviewed changes

Merge branch 'main' into feat/charge-last-month-usage-on-subscription…

262e2c8

…-deletion

vercel bot deployed to Preview January 9, 2025 04:28 View deployment

Merge branch 'main' into feat/charge-last-month-usage-on-subscription…

99f4255

…-deletion

vercel bot deployed to Preview January 17, 2025 04:34 View deployment

Merge branch 'main' into feat/charge-last-month-usage-on-subscription…

701c473

…-deletion

vercel bot deployed to Preview February 6, 2025 01:45 View deployment

refactor(stripe): simplify invoice payment process

9ba3e19

- Remove unnecessary finalization step before payment - Directly process invoice payment - Remove error handling wrapper for cleaner flow

vercel bot deployed to Preview February 6, 2025 04:31 View deployment

gentamura requested a review from satococoa February 6, 2025 04:53

satococoa approved these changes Feb 6, 2025

View reviewed changes

Add comments

0ff5641

vercel bot deployed to Preview February 6, 2025 05:19 View deployment

toyamarinyon approved these changes Feb 6, 2025

View reviewed changes

shige approved these changes Feb 6, 2025

View reviewed changes

gentamura merged commit 6042e96 into main Feb 7, 2025
9 checks passed

gentamura deleted the feat/charge-last-month-usage-on-subscription-deletion branch February 7, 2025 00:05

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(billing): Implement last month usage charging on subscription cancellation #296

feat(billing): Implement last month usage charging on subscription cancellation #296

gentamura commented Jan 7, 2025 •

edited

Loading

vercel bot commented Jan 7, 2025 •

edited

Loading

gentamura Jan 7, 2025 •

edited

Loading

gentamura Jan 7, 2025 •

edited

Loading

satococoa Jan 8, 2025

gentamura Jan 8, 2025

gentamura Feb 6, 2025

gentamura commented Jan 7, 2025

satococoa left a comment

satococoa Jan 8, 2025

satococoa Jan 8, 2025

gentamura commented Feb 6, 2025

satococoa left a comment

satococoa Feb 6, 2025

gentamura Feb 6, 2025

gentamura commented Feb 6, 2025

shige left a comment

gentamura commented Feb 7, 2025

feat(billing): Implement last month usage charging on subscription cancellation #296

feat(billing): Implement last month usage charging on subscription cancellation #296

Conversation

gentamura commented Jan 7, 2025 • edited Loading

Summary

Related issue

Changes

Testing

Other information

vercel bot commented Jan 7, 2025 • edited Loading

gentamura Jan 7, 2025 • edited Loading

Choose a reason for hiding this comment

gentamura Jan 7, 2025 • edited Loading

Choose a reason for hiding this comment

satococoa Jan 8, 2025

Choose a reason for hiding this comment

gentamura Jan 8, 2025

Choose a reason for hiding this comment

gentamura Feb 6, 2025

Choose a reason for hiding this comment

gentamura commented Jan 7, 2025

satococoa left a comment

Choose a reason for hiding this comment

satococoa Jan 8, 2025

Choose a reason for hiding this comment

satococoa Jan 8, 2025

Choose a reason for hiding this comment

gentamura commented Feb 6, 2025

satococoa left a comment

Choose a reason for hiding this comment

satococoa Feb 6, 2025

Choose a reason for hiding this comment

gentamura Feb 6, 2025

Choose a reason for hiding this comment

gentamura commented Feb 6, 2025

shige left a comment

Choose a reason for hiding this comment

gentamura commented Feb 7, 2025

gentamura commented Jan 7, 2025 •

edited

Loading

vercel bot commented Jan 7, 2025 •

edited

Loading

gentamura Jan 7, 2025 •

edited

Loading

gentamura Jan 7, 2025 •

edited

Loading