Skip to main content

Generate consolidated invoices through bill runs

Zuora

Generate consolidated invoices through bill runs

The Unified Invoicing feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at Zuora Global Support.

With Unified Invoicing, you can use bill runs to generate consolidated invoices for unbilled subscriptions and standalone charges under a customer account.

You can use bill runs to generate consolidated invoices in the following scenarios:  

  • A customer account has a subscription including a monthly recurring flat fee charge, with the BCD 1st, and unit price of $100. A draft standalone invoice INV-008 exists under the same account. After a bill run is executed for the account, a consolidated invoice in Draft status is generated, containing the subscription and draft standalone invoice INV-008. The number and ID of invoice INV-008 are not changed.
  • A customer account has a subscription, and two draft standalone invoices INV-001 and INV-002 exist under the same account. After a bill run is executed for the account, a consolidated invoice in Draft status is generated, containing the subscription and draft standalone invoice INV-001.
  • A subscription and order line items exist under an account, but no standalone invoice exists under the same account. After a bill run is executed for the account, a consolidated invoice in Draft status is generated.

Generate consolidated invoices through bill runs

You can create an ad hoc bill run through the Zuora UI or use the CRUD: Create a bill run operation to generate a consolidated invoice for a customer account.

After the bill run is executed, a consolidated invoice is generated and posted.

Collect payment for consolidated invoices 

After the consolidated invoice is generated, you can collect payment for it. 

You can use the Apply a payment operation to apply an existing payment to the consolidated invoice. You have to set the invoiceId field to the ID of the consolidated invoice in the request body.

To collect payment for a consolidated invoice through the Zuora REST API, perform the following steps:

  1. Determine the mandatory fields that you need for applying a payment to an invoice, including:
    • Path parameter: paymentId
    • Request field: invoices > invoiceId
    • Request field: invoices > amount
  2. Use the Apply a payment operation to apply an existing payment to the consolidated invoice.

The following sample API request applies an existing payment to a consolidated invoice.

Request PUT /v1/payments/{paymentId}/apply
Request body
{
   "effectiveDate": "2021-03-01",
   "invoices": [
      {
         "amount": 10.1,
         "invoiceId": "4028905f5a87c0ff015a87d3f8f10043",
         "items": [
            {
               "amount": 10,
               "invoiceItemId": "4028905f5a87c0ff015a87d3f90c0045"
            },
            {
               "amount": 0.1,
               "taxItemId": "4028905f5a87c0ff015a87d3f884003f"
            }
         ]
      }
   ]
}

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

Request PUT /v1/payments/{paymentId}/apply
Response body
{
   "id": "4028905f5a87c0ff015a87eb6b75007f",
   "number": "P-00000001",
   "status": "Processed",
   "type": "External",
   "accountId": "4028905f5a87c0ff015a87d25ae90025",
   "amount": 44.1,
   "appliedAmount": 44.1,
   "unappliedAmount": 0,
   "refundAmount": 0,
   "creditBalanceAmount": 0,
   "currency": "USD",
   "effectiveDate": "2021-03-01",
   "comment": "normal payment",
   "paymentMethodId": "402881e522cf4f9b0122cf5dc4020045",
   "paymentMethodSnapshotId": null,
   "authTransactionId": null,
   "bankIdentificationNumber": null,
   "gatewayId": null,
   "gatewayOrderId": null,
   "gatewayResponse": null,
   "gatewayResponseCode": null,
   "gatewayState": "NotSubmitted",
   "markedForSubmissionOn": null,
   "referenceId": null,
   "secondPaymentReferenceId": null,
   "softDescriptor": null,
   "softDescriptorPhone": null,
   "submittedOn": null,
   "settledOn": null,
   "cancelledOn": null,
   "createdDate": "2020-03-01 11:30:37",
   "createdById": "402881e522cf4f9b0122cf5d82860002",
   "updatedDate": "2020-03-01 13:56:15",
   "updatedById": "402881e522cf4f9b0122cf5d82860002",
   "financeInformation": {
      "bankAccountAccountingCode": null,
      "bankAccountAccountingCodeType": null,
      "unappliedPaymentAccountingCode": null,
      "unappliedPaymentAccountingCodeType": null,
      "transferredToAccounting": "No"
   },
   "gatewayReconciliationStatus": null,
   "gatewayReconciliationReason": null,
   "payoutId": null,
   "success": true
}