Catch Up Billing Run

Catchup billing run is a process that reconciles outstanding charges by calculating and generating invoices for previously unbilled services or products. 

 

Catch-up billing runs facilitate the migration of customer subscriptions from other systems into Nue. For example, if you are using Stripe to collect payments from your customer, the catch-up billing run in Nue will ensure that Nue Revenue Manager will send out the ‘next’ invoice appropriately.

 

Nue will execute the catch-up bill run prior to starting the regular billing schedule. The catch-up bill run will mark invoices that were already processed through other systems as ‘Catch Up’. These invoices will not be transferred to Stripe, QuickBooks or other external collection systems. The catch-up bill run is created using Nue API, and will only need to be run once after customer subscriptions are migrated into Nue.

 

Prerequisite

Before executing the catch-up bill run, you will need to follow the steps below to check all existing data and configurations:

Step 1: Set up billing parameters for each account

• Login to Salesforce → Nue on Salesforce
• Navigate to Accounts, and click into the Account Detail page
• Check whether the account level billing settings are all set up correctly.  
  • The account billing settings will override the system billing settings if they are not empty. So if the current account will be billed based on the system-level billing settings, leave them empty at the account level.

 

• Repeat the above steps and make sure the billing settings for all accounts are configured correctly.

Step 2: Check billing schedule settings

1. Login to Nue App
2. Navigate to System Settings → Billing
3. Check the system-level billing settings, and make sure they are correctly configured
4. Navigate to System Settings → Invoices
5. Turn off the below settings if they are on (In the red box)
1. Automatically generate the first invoice when an order is activated
2. Automatically activate the first invoice when an order is activated
6. Click ‘Save’ to save the changes

 

Step 3: Import historical subscriptions and orders

Import the historical subscriptions and orders by following this guide.  

 

NOTE   To prepare for catch-up billing schedules, ensure to verify if there are existing invoices for any accounts. If an account possesses invoices in Draft or Active statuses, Nue will exclude it from the catch-up billing process, resulting in no billing information update for that account. Therefore, please ensure that accounts intended for catch-up billing do not contain any invoices.

 

Catch-up billing schedule

Nue offers two different catch-up billing schedule modes: 

 

Generate Invoices

In this catch-up mode, real invoices and credit memos will be generated, and optionally activated.  This option is used when you need to generate invoices for historical orders, and also ingest them into the revenue recognition system for the simulated revenue run and accounting close process.

 

However, even when the real invoices are generated and activated, they will not be transferred to the payment system. The generated invoices (including Invoice Items) and credit memos (including Credit Memo Items) are marked as ‘Catch Up’.

 

Simulation 

In the simulation mode, invoices and credit memos will not be generated. The billing catch up process will run, but the invoices will not be created. The billing process simply sets the Billed Until Date for the active order products.  Since invoices are not generated they will not be transferred to payment systems either.

 

NOTE   In the Simulation mode, the reports and metrics of the invoice data will not be available.

 

Create a catch-up billing schedule

After importing all historical subscriptions and orders successfully, you can start creating a catch-up billing schedule to catch up with the billing statuses to a specific Billing Target Date. This Billing Target Date is defined as the ‘last billing date processed in the other system’ (in other words, the cutover date to Nue). 

 

For example, if your customer subscription has a Billing Cycle Day of the 15th of each month, and is invoiced on a monthly basis, let’s assume that the cut-off date to convert to Nue is March 31, 2023.

 

• The Subscription has a subscription start date of June 15, 2022.
• Your other system has already invoiced this customer 9 times on a monthly basis from June 15 - March 14.
• Nue will create a ‘catch-up’ billing schedule with a target date of March 31, 2023 (the cutover date).
• This catch-up bill run will result in 9 Invoices created in Nue.
• Nue will set these invoices to ‘Catch Up’ status.
• The next invoice created for this Subscription will be created on  April 15, 2023 with an ‘Active’ status. 

Let’s accomplish the above scenario following the below steps:

Get Auto Token

We need to get the API Access Key and API Token. More information can be found here.  

Create Catch Up Billing Schedule→

POST https://api.nue.io/billing/schedules

{
  "scheduleType": "On Demand",
  "customerFilter": null,
  "productFilter": null,
  "orderFilter": null,
  "billCycleDayFilter": null,
  "scheduleStartDate": "2023-03-31",
  "targetDate": "2023-03-31",
  "recurringSchedule": null,
  "status": "Active",
  "zoneId": "Asia/Shanghai",
  "autoActivate": true,
  "splitByPeriod": true,
  "cleanCatchUp": true,
  "catchUpMode": "GenerateInvoices"
}

 

After the catch-up billing schedule job completes, you will see the generated invoices by navigating to Revenue Manager → Invoices.

 

 

If you want to use the Simulation mode, you can set the catch-up mode to ‘Simulation’, then there won’t be catch-up invoices generated, but the bill until date for this subscription will be catched up to 2023/03/15. 

"catchUpMode": "GenerateInvoices"

 

If you don’t want to generate one catch-up invoice for each billing period, simply set the parameter ‘splitByPeriod’ to false, then there will be only one catch-up invoice generated across all billing periods before the Billing Target Date: 

"splitByPeriod": false

 

If the generated catch-up invoices are not as expected or you need to regenerate them from scratch, set the parameter ‘cleanCatchUp’ to true, this will delete all existing catch-up invoices and regenerate new ones. 

"cleanCatchUp": true

 

Apply filters to the billing schedule

If you have a large number of historical subscriptions that need to catch up, we do suggest you use the filters in the billing schedule request to restrict the data volume for each catch-up billing schedule, for example, filtering by account’s name. This will make it easier to verify whether the generated invoices are as expected

{
  "createdThrough": "API",
  "scheduleType": "On Demand",
  "customerFilter": "{name: {_eq: \"Nue IO\"}}",
  "productFilter": null,
  "orderFilter": null,
  "billCycleDayFilter": null,
  "scheduleStartDate": "2023-03-31",
  "targetDate": "2023-03-31",
  "recurringSchedule": null,
  "status": "Active",
  "zoneId": "Asia/Shanghai",
  "autoActivate": true,
  "splitByPeriod": true,
  "cleanCatchUp": true,
  "catchUpMode": "GenerateInvoices"
}

 

You can leverage Nue GraphQL Generator to create the filter condition and attach it to the parameter ‘customerFilter’ in the catch-up billing schedule request.

 

 

NOTE   Make sure to convert the double quote ( “ ) into backslash + double quote (\”) when using it in the API request.

 

Nue billing schedule supports the customer filter, product filter, and order filter. If you need to catch up billing information for some specific products or orders, you can add filter conditions to the API request accordingly. For example, filtering by product revenue model or order number

"productFilter": "{priceModel: {_eq: \"Recurring\"}}",
"orderFilter":"{orderNumber: {_eq: \"00000101\"}}"