Skip to main content

Invoice Settlement migration checklist and guide

Zuora

Invoice Settlement migration checklist and guide

The Invoice Settlement feature is generally available as of Zuora Billing Release 296 (March 2021). This feature includes Unapplied Payments, Credit and Debit Memo, and Invoice Item Settlement. If you want to have access to the feature, see Invoice Settlement Enablement and Checklist Guide for more information.

This article describes the process, checklist, and actions to take for enabling and migrating into the Invoice Settlement feature.

See Invoice Settlement for more information about this feature.

Invoice Settlement does not support feature rollback. After data migration is completed and the Invoice Settlement feature is enabled, you cannot disable it.

Invoice Settlement enablement process

To enable the Invoice Settlement feature, perform the following steps:

  1. Check the known limitations of the Invoice Settlement feature.
    See Known Limitations in Invoice Settlement for more information.
  2. Submit a request at Zuora Global Support to assess whether existing features in the Production environment are compatible with Invoice Settlement.
  3. See Integration Guide to make changes on the integration. 
  4. Go through the migration checklist and perform the corresponding actions. See Migration Checklist and Required Actions for more information.
  5. Submit a request at Zuora Global Support to request the Invoice Settlement feature.

Integration guide

API integration

If you use the Zuora API for integration in specific functional areas, it is best practice to follow the following API integration guide. 

Functional area Guide
Subscription management

You can continue to use Subscribe/Amend calls to create and manage subscriptions.

If you are a new customer, it is best practice to use the following API operations:

Adjusting invoices for overcharging and undercharging, and disputes

Invoice Item Adjustment and Invoice Adjustment are deprecated, and are replaced by credit memos and debit memos.

It is best practice to use the following API operations:

Credit management

Credit Balance Adjustment is deprecated. You can use credit memos ad hoc credit, and unapplied payments for overpayments. 

It is best practice to use the following API operations:

Payment management

You can continue to use Actions / SOAP API calls to create or update payments in bulk, or use CRUD Create payment to create or update a single payment. Actions and CRUD API operations do not support payments to debit memos and payments to invoice items. Two new fields unappliedAmount and appliedAmount on payment are available for Query in WSDL version 107.0 or later.

If you are a new customer, it is best practice to use the following API operations to manage payments:

Refund management

You can continue to use Actions or SOAP API calls to create or update refunds for payments in bulk or use CRUD Create refund to create or update a single refund. Actions and CRUD API operations do not support refunding credit balance which is deprecated or refunding credit memos.

If you are a new customer, it is best practice to use the following API operations to manage refunds :

Billing configurations

The following table lists all the billing configurations relevant to the Invoice Settlement feature.

Setting Details
Billing Rules: Invoice/Credit Memo generation rule Reviews and selects the rule which determines how the bill run will generate invoices and credit memos. See Rules for generating invoices and credit memos for more information.
Billing rules: Create credit memos mirroring invoice items Selects whether and how to create credit memo items for discount invoice items or zero-balance invoice items. See the Define billing rules for more information.
Billing rules: Available to credit validation for credit memos Selects whether and how to validate the "Available to Credit" amount of invoices when creating credit memos from the invoices. See Define billing rules for more information.
Default application rule Configures the application rule to manage how payments and credit memos are allocated to line items when applied or unapplied to invoices and debit memos. See the Default application rule for more information.
Prefix and Numbering Configuration for Memos Configures prefix and numbering for credit memo and debit memo. See Prefix and numbering configuration for billing documents for more information.
Memo templates Sets up custom memo templates for generation credit memo and debit memo PDFs. See Generate memo PDFs with custom memo templates for more information.
Custom Fields Configures custom fields for credit memo, debit memo, credit memo item, debit memo item, credit memo tax item and debit memo tax item. See Objects that support custom fields in Zuora for more information.
Callouts / email notification Configures credit memo and debit memo notifications from the Zuora UI. See Notifications for memos for more information.
Roles permission

Configures billing roles for credit memo, debit memo operations. See Billing roles for more information.

Configures payment roles for payment application operation. See Payment roles for more information.
Reason codes Configures reason codes for credit memo, debit memo. See Create and edit reason codes for more information.
Accounting codes Configures accounting codes for credit memo, debit memo. See Configure accounting codes for more information.

Zuora CPQ

Zuora CPQ 9.x and 8.x are compatible with Invoice Settlement.

If you use Orders, see Orders in Zuora Quotes for more information. If you do not use Orders, see Enable CPQ and Invoice Settlement integration without Orders for more information.

If you are using Zuora CPQ in an earlier version than 8.x, you have to upgrade it to the latest version first.

Zuora Workflow

See Workflow FAQs about the compatibility between workflow tasks and Invoice Settlement.

Zuora 360 and Zuora 360+

Invoice Settlement objects and fields are not supported in Zuora 360 but are supported in Zuora 360+. Therefore, if you want to use Invoice Settlement with Zuora CPQ, you must ensure that Zuora 360+ is enabled.

See New Object Types Supported Only When Zuora 360+ Enabled for more information.

Zuora Finance

You can use Zuora Finance as a general ledger or sub-ledger for the subscription revenue, including running a trial balance, closing the period, and generating reports.

Be careful about the timing when you enable the Invoice Settlement feature. If you already enabled the Finance feature, a best practice is to enable Invoice Settlement right after an accounting period is closed and before a journal run has occurred in the open accounting period. See Finance Integration with Invoice Settlement for more information.

Zuora Revenue

See Enable Invoice Settlement for Billing - Revenue Integration for more information.

Migration checklist and required actions

Before the Invoice Settlement feature is enabled for existing customers, data migration has to be performed. The data migration performs the following actions:

  • Negative invoices are converted to credit memos. One credit memo is created from one negative invoice. The negative invoice is written off with Invoice Item Adjustments first. Then, a credit memo is created from a pre-configured one-time charge.

    The date when the invoice item adjustment is applied (adjustment date) and the date when the credit memo takes effect (memo date) are set to the date when the negative invoice is processed by the migration. 

    If Zuora Finance is enabled on your tenant, ensure that the current accounting period is open during the migration to avoid migration failure.

  • The outstanding credit balance is converted to credit memos. One credit memo is created for an account with outstanding credit balance. An external refund is created to offset the credit balance first. Then, a credit memo is created from a pre-configured one-time charge.

    The refund date and the memo date are set to the date when the outstanding credit balance is processed by the migration. 

    If Zuora Finance is enabled on your tenant, ensure that the current accounting period is open during the migration to avoid migration failure.

  • The payments and refunds are migrated by generating new transactions of payment parts and refund parts. The payments and refunds themselves are not changed.

The duration of data migration depends on the volume of payments, negative invoices, accounts with credit balance. If you want to have an estimated duration about data migration, contact Zuora Global Support. The data migration process does not impact live transactions. During the execution of data migration, you can continue to create new transactions including payments, refunds, invoices, invoice item adjustments, invoice adjustments, credit balance adjustments, and so on. When the new transactions of payments, refunds, credit balance adjustments, and negative invoices are created, the data migration needs to be executed again. It is best practice to execute data migration during a low traffic period to reduce the frequency of re-executing data migrations.

Validate transactions

Before the Invoice Settlement enablement and migration, go through the checklist and perform the corresponding actions.

Scenario Required Actions / Remarks
Any draft accounts with credit balance

If the Credit Balance feature is enabled and any draft amounts have credit balance, perform the following actions:

  1. Use the Account data source to export accounts with the following filter:
    Account.Status = Draft and Account.CreditBalance > 0
  2. Delete the draft accounts or activate them.
Any canceled accounts with credit balance

If the Credit Balance feature is enabled and any canceled amounts have credit balance, perform the following actions:

  1. Use the Account data source to export accounts with the following filter:
    Account.Status = Canceled and Account.CreditBalance > 0
  2. Delete the canceled accounts or activate them.
Any draft accounts with posted negative invoices

If draft accounts have posted negative invoices, perform the following actions:

  1. Use the Invoice data source to export accounts with the following filter:
    Account.Status = Draft and Invoice.Balance < 0
  2. Delete the draft accounts or activate them.
Any inactive accounts with posted negative invoices 

If inactive accounts have posted negative invoices, perform the following actions:

  1. Use the Invoice data source to export accounts with the following filter:
    Account.Status = Canceled and Invoice.Balance < 0
  2. Delete the inactive accounts or activate them.
Any draft invoices with a negative balance

If draft invoices have a negative balance, perform the following actions:

  1. Use the Invoice data source to export invoices with the following filter:
    Invoice.Status = Draft and Invoice.Balance < 0
  2. Cancel the draft invoices or post them.
Draft payments

If draft payments exist, perform the following actions:

  1. Use the Payment data source to export payments with the following filter:
    Payment.Status = Draft
  2. Cancel the draft payments or process them.
Error payments

If error payments exist, Zuora does migrate the error payments during the migration process.

The connections between invoices and error payments are still available in the Invoice Payment data source. To obtain related information, you can export data through the Invoice Payment data source. 

Any scheduled payment runs with the option to apply credit balance before attempting payments

If the Apply Credit Balance to the invoice before attempting payment check box is selected for any scheduled payment run, perform the following actions:

  1. Cancel this payment run and all subsequent payments runs if any.
  2. After the Invoice Settlement feature is enabled, create another payment run. If you want to apply the previous credit balance, select the Auto-apply unapplied credit memos during payment runs check box.
    Note: If this check box is selected, credit memos created from other sources might also be automatically applied.

In this scenario, credit balance is transferred into credit memos during the Invoice Settlement migration process.

Tenant with the Finance permission and posted negative invoices or credit balance

If your tenant has the Zuora Finance permission and posted negative invoices or credit balance, provide an accounting code to use as the On-Account accounting code.

This On-Account accounting code is used for credit memos created during the migration. If it is not provided, Accounts Receivable is used as the On-Account accounting code by default.

Prepare one-time product rate plan charge

If negative invoices or outstanding credit balance exist before the Invoice Settlement enablement, create or update a one-time product rate plan charge within two days before the data migration is triggered. The charge is used to create credit memos from credit balance. The one-time product rate plan charge is not taxable.

Field Field Value Remarks
Charge name

The charge name must be in the format of "Special one time charge for migration - CurrencyCode".

For example, Special one time charge for migration - USD.

Charge model The charge model must be Flat Fee Pricing.
Charge amount The charge amount must be a value of less than 0. For example, -10.

Effective period of the corresponding product and product rate plan

The effective start date must be the first day of this year, and the effective end date must be the last day of this year. 

Accounting code Any valid accounting code
Taxable Do not select this field. This special one-time charge is not taxable.