Skip to main content

Generate consolidated invoices through Orders

Zuora

Generate consolidated invoices through Orders

  1. Last updated
  2. Save as PDF

With Unified Invoicing, you can generate consolidated invoices while creating a hybrid order containing both subscriptions and non-subscription charges through the Zuora REST API.

Assume that your end customer places an order for subscribing to professional services and also purchases some hardware products, you want to create a consolidated invoice to include both the order and the non-subscription charge for hardware purchase in real time, and then collect the payment for the invoice. In this scenario, you can use the Create an order operation to create a hybrid order and generate a consolidated invoice directly. Later, you can use the Apply a payment operation to apply an existing payment to the consolidated invoice.

Generate consolidated invoices through Orders

You can use the Create an order operation to create an order line item with a new subscription and generate a consolidated invoice.

To create an order line item with a new subscription:

  1. Determine the mandatory fields that you need for creating an order, including:
    • The following fields for a subscription: 
      • orderDate
      • productRatePlanId
      • existingAccountNumber

        You can also create both a subscription and a new account at the same time. In this case, you need to provide several other fields instead of existingAccountNumber. See Create an order for details.

    • The following fields and other required custom fields for order line items:
      • itemName
      • itemType
      • itemState
      • amountPerUnit

    These fields are a minimal set of fields required for an order. You can configure other optional fields based on your business needs.

  2. Use the Create an order operation to create an order containing a subscription and one order line item.  

The following sample API request creates a subscription and one order line item under an existing account:

Request POST /v1/orders
Request Body 
{
    "existingAccountNumber": "A00000776",
    "subscriptions": [
        {
            "orderActions": [
                {
                    "createSubscription": {
                        "subscribeToRatePlans": [
                            {
                                "productRatePlanId": "402894847af12293017af1c0d12403cc"
                            }
                        ],
                        "terms": {
                            "initialTerm": {
                                "period": 3,
                                "periodType": "Month",
                                "termType": "TERMED",
                                "startDate": "2021-03-01"
                            },
                            "renewalSetting": "RENEW_WITH_SPECIFIC_TERM",
                            "renewalTerms": [
                                {
                                    "period": 2,
                                    "periodType": "Month"
                                }
                            ],
                            "autoRenew": false
                        }
                    },
                    "type": "CreateSubscription",
                    "triggerDates": [
                        {
                            "triggerDate": "2021-03-01",
                            "name": "ContractEffective"
                        },
                        {
                            "triggerDate": "2021-03-01",
                            "name": "ServiceActivation"
                        },
                        {
                            "triggerDate": "2021-03-01",
                            "name": "CustomerAcceptance"
                        }
                    ]
                }
            ]
        }
    ],
    "processingOptions": {
        "billingOptions": {
            "documentDate": "2021-03-01",
            "targetDate": "2021-03-01"
        },
        "collectPayment": false,
        "runBilling": true
    },
    "orderLineItems": [
        {
            "itemName": "OrderItemName",
            "itemType": "Product",
            "UOM": "Each",
            "quantity": 1,
            "amountPerUnit": 10,
            "description": "Description",
            "itemState": "SentToBilling",
            "billTargetDate": "2021-03-01",
            "transactionDate": "2021-03-01",
            "listPricePerUnit": 10
        }
    ],
    "orderDate": "2021-03-01"
}

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

Request POST /v1/orders
Request Body 
{
    "success": true,
    "orderNumber": "O-00000001",
    "accountNumber": "AN_1627553580589",
    "status": "Completed",
    "subscriptionNumbers": [
        "A-S00000001"
    ],
    "invoiceNumbers": [
        "INV00000001"
    ],
    "orderLineItems": [
        {
            "id": "402894847af12293017af1c0dcb603eb",
            "itemNumber": "1"
        }
    ]
}

A hybrid order is created, and a consolidated invoice is generated and posted.

To create the order under a new account instead of an existing account, specify the newAccount field instead of the existingAccountNumber field.

To preview invoices for the new subscription, use the Preview order operation.

Collect payment for consolidated invoices

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

You can first use the value of the invoiceNumbers field included in the returned response to retrieve the ID of the consolidated invoice. Then, 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
}