Stripe Subscriptions, and standalone Stripe invoices, are tightly integrated with NetSuite.
Here's how the NetSuite Stripe Subscription integration works:
- Stripe Subscriptions are represented as NetSuite invoices with one or more line items. Each period (1 month, 1 year, etc), a new invoice is created in Stripe, which triggers the creation of a invoice in NetSuite to represent the subscription.
- If the Stripe invoice is paid, a NetSuite CustomerPayment is created and applied against the NetSuite invoice.
- If there is a refund, a CreditMemo and CustomerRefund is created.
- If a subscription is changed (different plan or quantity/seats purchased), that plan change is not represented on the current subscription's invoice. Prorations and plan changes are included in the next subscription cycle's invoice. This functionality can be customized (more information on this below).
- If an invoice remains unpaid (if a customer's card fails and they do not update it, for example) the invoice in NetSuite can either be automatically closed or remain open.
Here's what a Stripe invoice looks like in NetSuite:
Here are some technical details to keep in mind:
- Subscription invoices are not "finalized" until one hour after they are created. During this period the invoice is not created in NetSuite. Once a invoice is finalized (after that one hour period) it is sent over to NetSuite.
- Zero dollar line items are not removed from the invoice. They are included just like any other line item.
- Non-plan line items (i.e. additional
InvoiceItems) are supported. There's some extra work to ensure they are mapped to the right item in NetSuite.
Manual Invoice Payments
Invoices paid "manually" (cash, check, wire, or any other payment method not supported by Stripe) are also supported. Stripe has a feature available to set up a subscription for "manual" payment.
Here's how subscriptions paid on terms (manually) work:
- If an invoice (or subscription) is marked for manual payment it is brought over to NetSuite as an unpaid invoice
- The due date based on the payment terms specified in Stripe is brought over as the due date on the NetSuite invoice.
- When the invoice is marked as paid in NetSuite, SuiteSync marks invoice in Stripe as paid and adds the transaction ID of the NetSuite payment to the Stripe invoice metadata. Note that if an invoice is partially paid in NetSuite it is not marked as paid in Stripe.
- Stripe automatically updates the subscription status in Stripe when the invoice is updated by SuiteSync
This enables you to use Stripe subscriptions to manage subscription status in—regardless of the payment method—but manage collections on those invoices from a single source in NetSuite.
Here's all of the nitty-gritty details on how plan changes are represented in NetSuite.
If don't want customers to carry a credit/balance, or if you want to refund a customer for unused time, check out this example code.
Stripe Coupons are supported in the integration. They are represented as NetSuite discount items. You can either create a unique discount item in NetSuite for each coupon in Stripe or use a single discount item for all coupons in Stripe (you can also develop a custom mapping).
In Stripe, coupons are represented as a separate line item on the invoice. In NetSuite, there are two options for representing coupons:
- An additional line item on the invoice, just like Stripe.
- On the header level of the invoice, using the "Discount" drop-down in NetSuite.
Using coupons with revenue recognition
Coupons do not have a revenue period. If you are using revenue recognition, you'll want to use non-posting discounts. This causes the discount amount to be subtracted from the total revenue recognized for the item representing the subscription.
If you choose to use posting discount items, the revenue account used can be customized.
Stripe trial periods create $0 invoices in Stripe. The integration allows you to pull these trial period invoices into NetSuite, or ignore them. Trial invoices can be created by using the
trial_period_days parameters in Stripe.
Note that trial invoices use a special invoice structure in Stripe. All line items on the invoice are set to zero, so the invoice has no accounting impact at all. This is different from using a coupon/discount, or another method that creates an invoice with a net total of zero. We don't skip invoices that have line items with a non-zero value since there are many cases where an invoice may have a net total of zero but contains line items which have a GL impact that you'll want to be recorded in NetSuite.
Customers with lower cost plans usually opt to prevent trial invoices from being pulled into NetSuite. These trial invoices don't have any accounting impact and simply create noise in high-volume scenarios.
However, if you have scripts or other automation that you'd like to run in NetSuite when a customer creates a subscription in Stripe, you may want to keep this option enabled.
Invoices for Standalone Charges
Standalone charges are payments in Stripe created without an invoice. If Stripe Subscriptions isn't being used or if you are using a 3rd party system that connects to Stripe (like Tito, Invoiced, Recurly, etc) standalone (i.e. one-time) payments are being created. In this case, Stripe only has information about the cash collected but does not have any details about the line items or revenue components of the Stripe charge.
If it's important to track multiple line items (for instance, if you have revenue and taxes to record for each payment), you'll need to create an invoice in NetSuite to pair with the Stripe payment. You can do this using a CSV import or directly via the API.
However, if revenue reporting requirements are simple, the integration can create an invoice using the information on the charge. Here's how:
- For each standalone charge in Stripe, a NetSuite invoice is created. The description of the charge is added to the memo of the invoice. Data from Stripe metadata fields can also be added to the invoice.
- A single line item is used on the invoice to represent the entire Stripe charge. The same NetSuite item is used for all payments on the Stripe account. If you have multiple Stripe accounts, you can use a different NetSuite item for each account, which enables you to separate out these revenue streams in NetSuite reports.
- A payment is created and applied against the invoice. The payment is automatically reconciled to a bank deposit, fees are recorded, etc.
- Refunds and disputes are automatically represented with a credit memo and refund.
- Taxes, discounts, multiple lines items, etc are not supported when using this feature. Take a read through the other invoice documentation for more information on how to handle those more complex cases.
Here's an example of where this feature is helpful:
- You are using a tool like Tito (event management) or some other Stripe plugin and want to accurately record revenue and cash in NetSuite without any engineering work.
- You are just getting started with NetSuite and need to pull revenue and cash entries into NetSuite from Stripe. Your developers don't have time to build a custom integration and you want to avoid importing CSVs.
Standalone Invoice Items
Stripe's Invoice Items can be used to add one-time charges to a customer's subscription. This is helpful for implementing usage based billing, overage charges, bonus pack purchases, etc.
They are also used to add line items for a standalone invoice.
Here's an example of how to add one using the Stripe dashboard:
Each invoice item you create in Stripe has a unique ID, even if the line item represents a consistent type of charge that you add to a customer's bill. In most cases, you'll want to map an invoice item you add to a customer to an existing NetSuite item.
The integration provides two main ways to do this:
- When you add the line item to the customer you can map it to an existing NetSuite item using metadata. Here's a full list of the mappings available.
- A NetSuite item can be matched using the
descriptionof the Stripe line item. The Stripe line item description is used to search for a NetSuite item whose "Display Name" matches the Stripe description. If a match is not found a fallback item is used. The match is not case sensitive.
Customer Balance or Credit
How invoice payment failures are handled
If your card fails to charge the invoice will remain unpaid in Stripe and therefore remain open in NetSuite. Here's more information on how failed payments operate in Stripe.
Stripe retries the payment on an invoice a couple times, after it fails for the final time it moves to a "unpaid and closed" state, which is detailed out here.
Unpaid and closed, or forgiven invoices
If a customer's card fails to charge the subscription is
past_due and the invoice associated with the billing period is unpaid. At this point, you can choose to "forgive" or close the unpaid invoices in Stripe.
Here's an example of a closed invoice in Stripe:
If an invoice is open and unpaid, you'll see a "Close" button on the Stripe invoice.
Here's how this works in Stripe:
- Forgiving a Stripe invoice instructs Stripe to treat the users subscription as if they had paid the invoice. Stripe will stop attempting to collect payment, but the user's subscription will continue to function normally
Closing an invoice instructs Stripe to stop attempting to charge the user's card, but the user's subscription status remains
- If your Stripe subscription payment retry strategy cancels a subscription, associated invoices are closed.
By default, invoices that are closed and unpaid, or invoices that are forgiven, remain open in NetSuite. This enables you to create processes around handling "bad debt" in a way that works for your business.
There's an option available that automatically creates a credit memo against any closed or forgiven invoices that are not paid. This closes the invoice in NetSuite and reverses the entries to A/R and makes an entry to an income account.
On the credit memo which closes out the "bad debt" created by the invoice, you can either use the original item(s) on the invoice, or override the default item with a unique item to represent all "bad debt" that is closed out. Using this "bad debt" item allows you to customize the account that this bad debt posts to. If you are using revenue recognition in NetSuite, the schedule from the original invoice is copied over to the CreditMemo if you use the original items on the invoice.
If you aren't automatically cancelling subscriptions when the last payment attempt fails, you'll need to manually manage closing out open Stripe invoices for a customer when you are sure you won't be attempting collection on those invoices. Here's an example of how to manually close Stripe invoices for a customer.
If you are automatically cancelling subscriptions when you visit this Stripe settings page you should see something similar to:
Note that SuiteSync is not effected by the number of failed card retries. Only the "Finally then" rule effects how SuiteSync works.
Stripe does not record the date when the invoice was closed or forgiven. Since this information does not exist, we use the date of the last failed payment against the invoice as the date of the (optional) credit memo that is created to automatically close the invoice. In most cases, the date of the last failed payment on the invoice is the date that the invoice is closed. This is the case in the Stripe retry configuration shown in the above screenshot. If you are handling payment retries and invoice status changes using a customized dunning system (either home-grown or a 3rd party service) they may not close the invoice on the same day as the last failed charge.
When a customer's invoice fails to be paid for the last time, it's possible to enable a credit hold on the customer. This is an optional feature that can be enabled on your account.
How can I close out Stripe invoices in batches?
You may run into a situation where you have past invoices which were accidentally left open and you want to close them out.
In Stripe, there's no way in the dashboard to batch close invoices. You'll need to either:
- Close them out manually in the Stripe dashboard
- Use a script to close out invoices in batches. You'll want to the
Can CashSales be used instead of Invoices?
Each billing period of a Stripe subscription (i.e. a Stripe invoice) can only be represented by a NetSuite invoice.
CashSales represent an order and collected cash. Since Stripe invoices (created at the beginning of each billing cycle) are not always paid (in the case of a failed card payment) representing a Stripe invoice as a CashSale would incorrectly indicate that cash has been collected from the customer.