Invoices

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 marked as uncollectible or remain open.

Here's what a Stripe invoice looks like in NetSuite:

Example NetSuite Invoice

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.

Products, Plans, and Coupons

Here's more information on how products and plans work.

Plan changes

If a customer is switching from a higher cost plan to a lower cost plan a customer balance is created. No refund is given to the customer and this balance is applied to any future invoices.

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.

Trial Invoices

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_end and 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.

Standalone Invoice Items

Stripe's Invoice Items can be used to add one-time charges to a customer's next recurring invoice. This is helpful for implementing usage based billing, overage charges, bonus pack purchases, one-time service charges, etc. These "add on" invoice items are not associated with a plan or pricing level and therefore do not have a direct mapping to a NetSuite item.

Here's an example of how to add one using the Stripe dashboard:

Invoice items in Stripe

Each standalone 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 invoice. In most cases, you'll want to map an invoice item to an existing NetSuite item. If you don't, the integration uses a generic item for all standalone invoice items.

The integration provides two ways to match a invoice item to specific item in NetSuite:

  1. 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.
  2. A NetSuite item can be matched using the description of the Stripe line item or a metadata field. The Stripe line item description is used to search for a NetSuite item whose "Display Name" (or another NetSuite field, the matching operation is flexible) 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

Paying an invoice with a Stripe customer's account balance is fully supported in the integration. Learn more about how this works.

A invoice is partially or fully paid with the customer's balance if a customer has a negative account balance. A common case where this occurs is when a user downgrades to a lower-cost plan, which in turn creates a negative invoice in Stripe. The unused prorated value (which caused the negative invoice) is added to the customer balance. If the customer balance beta feature is enabled, this credit is immediately created in the form of a credit memo vs created upon next invoice payment. The credit memo is applied against the next invoice to represent the portion of the invoice that was paid using a customer balance.

A less common situation is a positive customer balance. This occurs when there is a plan change that creates a balance less than the minimum payment amount in the invoice's currency or via a manual adjustment in Stripe to the customer's balance. If this occurs, the balance amount is included as a separate line item on the next upcoming invoice for the customer and the invoice below the minimum amount is not created in NetSuite unless your account is setup using the customer balance beta feature. The integration uses a unique item ("Stripe Customer Balance Debit Item") to represent this balance on this next invoice.

Negative Stripe Invoices

NetSuite does not allow negative invoices, which is why negative invoices in Stripe are not identical in structure to the corresponding NetSuite invoice. A negative invoice in Stripe is always represented as a zero-dollar invoice in NetSuite, with the negative amount applied on the next invoice in the form of a customer balance 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, the default Stripe behavior is to leave the failed invoice as is. This will leave both the Stripe and NetSuite invoices open and will need to be manually paid, marked as uncollectible or marked as void. There are also more options if you would like to automatically mark the invoice as uncollectible, which you can read more about here.

Uncollectible invoices

Stripe used to refer to invoices as "open" or "closed" but now has an invoice status which contains statuses of: draft, open, paid, void and uncollectible. To avoid confusion, we try to avoid using the old term "closed" when talking about Stripe invoices and try to use paid, void or uncollectible depending on the scenario.

If a customer's card fails to charge the subscription is past_due and the invoice associated with the billing period is unpaid, you can choose to mark the invoice as uncollectible in the Stripe API or dashboard.

If an invoice is open and unpaid, you'll see an option to change the invoice status which will allow you to mark the invoice as paid, void or uncollectible.

Here's how uncollectible invoices work in Stripe:

  • Marking a Stripe invoice as uncollectible 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
  • Marking an invoice as uncollectible instructs Stripe to stop attempting to charge the user's card, but the user's subscription status remains past_due.
  • If your Stripe subscription payment retry strategy cancels a subscription, associated invoices are marked as uncollectible.

By default, invoices that are open and unpaid with several failing payment attempts remain open in NetSuite. This enables you to create processes around trying to manually collect payment from your customer or determining that the invoice is uncollectible and marking it as such via the Stripe dashboard or API.

The Stripe dashboard also gives an option for when all retries for a payment fail to "mark the invoice as uncollectible" which will move the invoice to the uncollectible state in Stripe. For any of these invoices marked as uncollectible, this will automatically create a credit memo in NetSuite. This credit memo will be used to close out the invoice in NetSuite and reverse the entries to A/R and make 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 marked as uncollectible. 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.

If you are automatically cancelling subscriptions when you visit this Stripe settings page you should see something similar to:

Invoice items in Stripe

Note that SuiteSync is not affected by the number of failed card retries. Only the "Finally then" rule affects how SuiteSync works.

Stripe will record the date that the invoice was closed (i.e. paid, marked uncollectible, or voided) and that is the date that we will report to NetSuite. 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 Stripe closed date.

In Stripe I can reopen an uncollectible invoice. Is this supported by SuiteSync?

No. Once an invoice is marked as uncollectible in Stripe you should not reopen it. NetSuite does not support closing and reopening invoices in the same way Stripe does, so we do not support this Stripe feature.

For example, if you mark an invoice as uncollectible in Stripe and then close the accounting period in NetSuite which that Stripe invoice was included in, NetSuite does not allow you to open the invoice.

Can I prevent a invoice that is not paid successfully from being sent to NetSuite?

No, we don't allow invoices to be brought over only when they are paid. This would cause accounting inaccuracies. Not every invoice which fails to be paid the first time, will remain unpaid. Actually, many (most in some cases) eventually get paid due to Stripe's recovery tools. For instance, an invoice payment may fail on the first attempt but Stripe automatically retries the payment at a later day and it may succeed.

It's important that we bring over the invoice immediately when it is created so we can book revenue accurately. Take this example:

  1. A subscription renews and an invoice is created on the 25th of January. The payment on the invoice fails.
  2. It's a monthly subscription, and revenue recognition is enabled in NetSuite. SuiteSync creates an invoice in NetSuite and revenue is spread over January and February.
  3. On the 5th of February a payment is successfully created for the invoice. The invoice for January is unchanged.
  4. On the 25th of February the subscription renews again, booking revenue for February and March.

If we only brought over the invoice when it was paid, revenue for February would be incorrectly overstated.

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.

Are NetSuite invoices synced to Stripe as Invoices?

No. Stripe invoices are pushed to NetSuite, but NetSuite invoices are not pushed to Stripe as invoices. If you create an invoice in NetSuite and pay it off, only the payment on the invoice is created in Stripe. The payment for the invoice contains a reference and link to the NetSuite invoice, but the invoice and corresponding line items are not replicated in NetSuite.

Is there a limit to the number line items on an invoice?

Yes. The NetSuite invoice has a line limit of 500 lines. An invoice with 500 or more lines in Stripe cannot be sucessfully be pushed into NetSuite due to this limitation. If this situation occurs, you will need to manually reconcilie the invoice and payment in NetSuite in a summary fashion.