Import external invoices as standalone invoices

Overview

Unified Invoicing supports importing invoices from external billing systems into Zuora as standalone invoices through the Zuora REST API.

Enterprises that operate multiple business lines often have more than one billing application. They either need to consolidate the billing records from each source and maintain the customized integration, or suffer from a lack of data integrity and a single view of the business and their end customers.

With Unified Invoicing, you can migrate open and historical invoices from other billing applications into Zuora as standalone invoices through the REST API. With all billing records being presented in one place, you can efficiently manage both subscription and non-subscription transactions of the same end customer at a lower cost, and streamline your reporting for account receivables and accounting operations.

Importing external invoices

This tutorial shows you how to import an external invoice into Zuora through the REST API.

Assume that your end customers have purchased some hardware products and you want to import the corresponding invoices with pre-calculated taxes into Zuora as standalone invoices with predefined data. In this scenario, you can use the Create a standalone invoice operation to achieve it. Zuora does not recalculate the taxes.

In the preceding scenario, you have to provide tax information in theinvoiceItems > taxItems field in the request body of this operation.

To import an invoice from an external billing system into Zuora as a standalone invoice through the Zuora REST API, perform the following steps:

1. Determine the mandatory fields you need for importing an external invoice, including:
   • accountId
   • externalId
   • invoiceDate 
   • invoiceItems
2. Use the Create a standalone invoice operation to import an invoice from an external billing system into Zuora as a standalone invoice. 

The following sample API request imports an invoice with tax information from an external billing system into Zuora as a standalone invoice.

{
    "accountId": "402894847af12293017af1a0406701e7",
    "invoiceDate": "2021-02-01",
    "comments": "comments",
    "autoPay": false,
    "invoiceItems": [
        {
            "amount": 100,
            "description": "description",
            "chargeDate": "2021-02-01 00:00:00",
            "productRatePlanChargeId": "402894847af12293017af1a03be901e4",
            "quantity": 1,
            "serviceStartDate": "2021-02-01",
            "serviceEndDate": "2021-02-10",
            "purchaseOrderNumber": "PO-000303",
            "taxItems": [
                {
                    "exemptAmount": 0,
                    "jurisdiction": "",
                    "locationCode": "",
                    "name": "country tax",
                    "taxAmount": 10,
                    "taxCode": "VAT",
                    "taxCodeDescription": "country tax",
                    "taxDate": "2021-02-01",
                    "taxRate": 0.1,
                    "taxRateDescription": "",
                    "taxRateType": "Percentage",
                    "taxMode": "TaxExclusive"
                }
            ]
        }
    ]
}

After the sample API request is submitted, the following sample API response is returned:

{
    "id": "402894847af12293017af1a04067088f",
    "invoiceNumber": "INV00000035",
    "accountId": "402894847af12293017af1a0406701e7",
    "amount": 110,
    "amountWithoutTax": 100,
    "invoiceDate": "2021-02-01 00:00:00",
    "dueDate": "2021-02-01 00:00:00",
    "autoPay": true,
    "comments": "comments string",
    "status": "Draft",
    "taxAmount": 10,
    "taxExemptAmount": 0,
    "transferredToAccounting": null,
    "success": true
}

Customizing invoice number 

When you create standalone invoices through the REST API, you can use the invoiceNumber field to input a customized invoice number, for example, `6LU5F8NW00001`. A typical use case is to keep the original invoice number when importing invoices from other billing systems into Zuora for easy cross-reference and reporting. Things to note when using this field: 

• Format requirements:
  • Max length: 16 characters
  • Acceptable characters: a-z, A-Z, 0-9, -, _,
• Must be unique.
• Only available in the request body of the Create a standalone invoice and Create standalone invoices operations. Operations to update standalone invoices are not supported. Subscription invoices are not supported.
• When an invoice with a customized invoice number is deleted, the system will change the value by adding a random suffix, for example, from `CUSINV00000001` to `CUSINV00000001_14230a434ea`. This behavior ensures that if you use the same invoice number again, it is still unique in the system.  
• Avoid using the system default prefixes, prefixes for internal use, or any customized prefixes you have configured because that might have a numbering conflict and cause issues with bill runs and subscribe/amend. To resolve the conflict if it happens, go to Billing Settings > Define Numbering and SKU Formats > Define Prefixes, Numbers and Sequence Sets to identify the prefix in conflict. For more information, see Configure prefix and numbering for billing documents.
  • Change the Prefix to a new one; Or
  • Change the Starting Document Number to a value greater than the current value.