When setting up new subscriptions in Stripe, it's crucial to make sure sales tax is calculated correctly from the very first invoice. This guide will show you how to configure your Stripe subscriptions so Kintsugi can accurately calculate and apply sales tax before the invoice is finalized.
Understanding How Stripe Finalizes Initial Invoices
When a subscription is created with automatic payment charging:
Invoice Finalization: Stripe finalizes the first invoice right away.
Tax Calculation Window: This quick finalization means there’s only a very short window for Kintsugi to update the sales tax before the invoice is sent.
This is part of Stripe’s standard process for new subscriptions. By creating a brief pause before invoice finalization, you can ensure there’s enough time for tax details to be applied accurately.
Dos and Don’ts
What to Avoid:
Avoid setting collection_method = charge_automatically during subscription creation.
This will finalize the invoice immediately, giving no time for tax updates.
Instead, set collection_method = send_invoice on the subscription initially.
What to Do:
Ensure the first invoice is generated in draft mode.
After Kintsugi updates the tax, set collection_method = charge_automatically on the invoice if you want automatic collection.
Why Does This Matter?
When integrating Kintsugi with Stripe's subscription model, particularly when "Automatically charge a payment method on file" is selected, accurate sales tax calculation for initial subscriptions can be challenging. This is because invoices are finalized immediately upon subscription creation, preventing Kintsugi from updating the sales tax, which may lead to inaccuracies.
Some points to keep in mind:
The collection_method may need to be updated after invoice creation.
A customer email is required for invoices.
After the initial invoice is created, you can set collection_method = charge_automatically on the invoice if you want automatic collection.
For details, see Stripe’s Subscription Invoices documentation.
Potential Solutions
There are three possible ways to give Kintsugi enough time to apply accurate sales tax before the first invoice is finalized. You can select the method that best fits your billing process.
1. Implement a Delay Before Finalization (won’t work)
Scheduled Finalization: Configure Stripe to delay the automatic finalization of invoices, allowing Kintsugi sufficient time to update the sales tax.
Implementation: Utilize Stripe's auto_advance feature to control when an invoice is finalized. By setting auto_advance to false, you can manually finalize the invoice after Kintsugi updates the tax information.
Reference: Stripe API – Finalize an Invoice
Why won’t work: auto_advance is a property of an invoice and a subscription does not have such a property. Kintsugi won't have any time to set any property in the invoice for the very first invoice generated from a subscription and finalized at the same time.
2. Modifying the Subscription Creation Workflow
Initial Draft State: Create subscriptions with invoices in a draft state, providing a window for tax updates before finalization.
Implementation: When creating a subscription, set the collection_method to send_invoice and ensure auto_advance is set to false. This approach keeps the invoice in a draft state, allowing Kintsugi to update the tax details before manual finalization.
3. Using Webhooks for Real-Time Updates (won’t work)
Invoice Creation Hook: Set up a webhook to listen for the invoice.created event, triggering Kintsugi to calculate and update the sales tax promptly.
Implementation: Configure a webhook endpoint in your application to handle the invoice.created event. Upon receiving this event, Kintsugi can compute the appropriate sales tax and update the invoice before finalization.
Reference: Stripe API – Webhooks
Why won’t work: Kintsugi won't have any time to set any property in the invoice for the very first invoice generated from a subscription and finalized at the same time.
Recommended Approach
The most effective solution involves adjusting the subscription creation process to allow a brief period for tax calculations before invoice finalization. By creating invoices in a draft state and controlling the finalization timing, Kintsugi can accurately update sales tax information, ensuring compliance and accuracy.
Implementation Steps:
Create Subscription with Draft Invoice:
Set collection_method to send_invoice.
Set auto_advance to false.
This configuration keeps the invoice in a draft state upon creation.
Calculate and Update Sales Tax:
Upon receiving the invoice.created event via webhook, trigger Kintsugi to calculate the appropriate sales tax.
Update the draft invoice with the calculated tax details.
Manually Finalize the Invoice:
After updating the tax information, finalize the invoice by setting auto_advance to true or by explicitly calling the finalize API endpoint.
By following this approach, you ensure that all invoices, including those for subscriptions with automatic payment methods, have accurate and updated sales tax information before finalization.
Additional Resources:
Implementing these adjustments will enable seamless integration between Kintsugi and Stripe's subscription model, ensuring accurate tax calculations across all billing scenarios.
If You Still Want Automatic Collection
If you want Stripe to automatically charge the customer’s payment method after the tax update:
After Kintsugi updates the draft invoice, set the invoice’s collection_method to charge_automatically.
Update the subscription’s collection_method from send_invoice to charge_automatically so that future invoices are automatically collected without manual changes.
Alternative Approaches
Stripe also supports other ways to delay invoice finalization for the first subscription period:
Using trial_end:
Set a short trial period when creating the subscription (e.g., a few minutes or hours). This delays invoice creation and finalization until after the trial ends, giving Kintsugi time to calculate tax.
Using Subscription Schedules:
Create a subscription schedule that starts in a pending phase, where you can generate and edit the first invoice before transitioning to the active phase with automatic collection.
For details, see Stripe’s Subscription Invoices documentation.
Quick Comparison
Without this setup:
Subscription is created with automatic charging.
Stripe finalizes the invoice instantly.
Kintsugi cannot update the tax, leading to potential inaccuracies.
With this setup:
Subscription is created with send_invoice and auto_advance = false.
The invoice stays in draft mode.
Kintsugi updates the tax via the webhook.
The invoice is finalized with the correct tax applied.
Benefits of This Approach
Accurate Sales Tax: Ensures the initial subscription invoice includes the correct sales tax.
Compliance: Helps avoid issues related to incorrect tax calculations.
Flexibility: Works even when a payment method is already on file for the customer.
Need help?
For further concerns, we're always here to help. If you can't find the answer you're looking for, please reach out to us using the chat bubble in the bottom right corner.