Create billing documents

Billing documents represent your customer's invoices, credit memos, and debit memos.

Invoices are statements of amounts owed by a customer, and are either generated one-off or periodically from a subscription. They contain invoice items, and proration adjustments that may be caused by changes to a subscription.

If your invoice is configured to be charged automatically, Zuora automatically finalizes your invoice and attempts payment; otherwise Zuora will email the invoice to your customer and await payment. Any credit memos may be applied before determining the amount due for the invoice, which is the amount that will be charged.

Quickstart API
v1 API

Create an invoice

Assume the billing timing of the recurring price that your customer subscribes to is in_advance. After your customer has created a subscription, you need to create an invoice and bill it to your customer.

The following code sample creates an invoice for the subscription of the Gold product and post it to your customer's account.

cURLJavaNode
Copy
Copied
curl --request POST \
    --url https://rest.test.zuora.com/v2/invoices \
    --header 'Authorization: Bearer 36d7146ffe674eb5988c6838dfe370ae' \
    --header 'Content-Type: application/json' \
    --data '{
      "account_id": "2c92c0f96abc17de016abd62bd0c5854",
      "pay": false,
      "description": "invoice of subscription for Gold product",
      "document_date": "2023-02-01",
      "post": true,
      "items": [
      {
            "amount": 100,
            "booking_reference": "PE2FGW",
            "name": "Subscription item 1",
            "description": "A new invoice item",
            "service_start": "2023-01-01"
        }]
    }'
Copy
Copied
  LocalDate startDate = LocalDate.of(2022,11,1);
  LocalDate endDate = LocalDate.of(2023,11,1);

  BillingDocumentItemCreateRequest invoiceItemRequest = new BillingDocumentItemCreateRequest()
      .amount(new BigDecimal(300.00))
      .bookingReference("PE2FGW")
      .name("subscription item 1")
      .description("a new invoice item")
      .quantity(new BigDecimal(2))
      .serviceEnd(endDate)
      .serviceStart(startDate);

  BillingDocumentCreateRequest invoiceRequest = new BillingDocumentCreateRequest()
      .accountId("8ad09b7d8292b85d0182a4d6f875225a")
      .pay(false)
      .description("new invoice")
      .documentDate(startDate)
      .type(BillingDocumentCreateRequest.TypeEnum.INVOICE)
      .post(true)
      .items(Collections.singletonList(invoiceItemRequest));

  BillingDocument newInvoice = zuoraClient.billingDocuments().postBillingDocument(invoiceRequest);
  System.out.println(newInvoice);
Copy
Copied
const invoiceItemRequest = {
    amount: 300,
    booking_reference: 'PE2FGW',
    name: 'subscription item 1',
    description: 'a new invoice item',
    quantity: 2,
    service_start: '2022-11-01',
    service_end: '2023-11-01',
};
 
const invoiceRequest = {
    account_id: '8ad09b7d8292b85d0182a4d6f875225a',
    pay: false,
    description: 'new invoice',
    document_date: '2022-11-01',
    type: 'invoice',
    post: true,
    items: [invoiceItemRequest]
};
 
const newInvoice = await zuoraClient.billingDocuments.postBillingDocument(invoiceRequest);

Create a credit memo

Credit memos are legal documents used to correct charge mistakes on invoices and manage the balance on a particular invoice or customer account.

You can use the Create a credit memo operation to create credit memos in either of the following ways:

  • Create a credit memo from an invoiceNote that you can create a credit memo from an invoice only if you have the Billing user role permission. See Billing Roles for more information.
  • Create a credit memo from a price

    These memos are recognized as standalone credit memos. The purpose of standalone credit memos is to raise an ad hoc price or credit not related to a specific invoice. The memo items refer to one-time prices. These prices do not have to be part of any subscription. Standalone credit memos can be applied to any invoice or debit memo with a positive balance.

Create a credit memo from an invoice

The following example creates a credit memo from an invoice with invoice_id = 8ad0889d8736ecc50187460849231ae2. The credit memo item is created based on the invoice item with invoice_item_id = 8ad0889d8736ecc501874608493d1ae3:
cURLJavaNode
Copy
Copied
curl --request POST \
  --url https://rest.apisandbox.zuora.com/v2/credit_memos \
  --header 'Authorization: Bearer 8c839831b0c74af9af01d0171647019b' \
  --header 'Content-Type: application/json' \
  --data '{
            "account_id": "2c92c0f96abc17de016abd62bd0c5854",
            "description": "credit memo from invoice",
            "document_date": "2023-04-01",
            "invoice_id": "8ad0889d8736ecc50187460849231ae2",
            "items": [
              {
                "invoice_item_id": "8ad0889d8736ecc501874608493d1ae3",
                "amount": 10,
                "quantity": 5,
                "service_start": "2023-01-01",
	              "service_end": "2023-04-01",
	              "name": "credit memo item 1"
              }
            ],
            "reason_code": "Charge Dispute"
}'
Copy
Copied
LocalDate startDate = LocalDate.of(2022,9,20);
LocalDate endDate = LocalDate.of(2022,9,30);

BillingDocumentItemCreateRequest invoiceItem = new BillingDocumentItemCreateRequest()
    .amount(new BigDecimal(10))
    .quantity(new BigDecimal(5))
    .serviceStart(startDate)
    .serviceEnd(endDate)
    .sku("SKU-123")
    .invoiceItemId("8ad0855182b04d010182b0ccd9d33e79");

List<BillingDocumentItemCreateRequest> billingDocumentItemList = new ArrayList<BillingDocumentItemCreateRequest>();
billingDocumentItemList.add(invoiceItem);

BillingDocumentCreateRequest creditMemoRequest = new BillingDocumentCreateRequest()
    .accountId("8ad09b7d8292b85d0182a4d6f875225a")
    .description("credit memo from invoice")
    .documentDate(todayDate)
    .type(BillingDocumentCreateRequest.TypeEnum.CREDIT_MEMO)
    .invoiceId(invoice.getId())
    .items(billingDocumentItemList)
    .reasonCode("Charge Dispute");

BillingDocument creditMemoFromInvoice = zuoraClient.billingDocuments().postBillingDocument(creditMemoRequest);
Copy
Copied
const invoiceItem = {
    amount: 10,
    quantity: 5,
    service_start: '2022-09-20',
    service_end: '2022-09-30',
    sku: 'SKU-123',
    invoice_item_id: '8ad0855184eab9e10184efdac7917c6d',
};
 
const creditMemoRequest = {
    account_id: '8ad09b7d8292b85d0182a4d6f875225a',
    description: 'credit memo from invoice',
    document_date: '2022-11-02',
    type: 'credit_memo',
    invoice_id: '8ad0855184eab9e10184efdac77d7c6c',
    items: [invoiceItem],
    reason_code: 'Charge Dispute',
};
 
const newCreditMemo = await zuoraClient.billingDocuments.postBillingDocument(creditMemoRequest);

Create a credit memo from a price

The following example creates a credit memo from a price where price_id = 8ad0887182afa5d00182b017730c5fcb:
cURLJavaNode
Copy
Copied
curl --request POST \
    --url https://rest.apisandbox.zuora.com/v2/credit_memos \
    --header 'Authorization: Bearer 38fcea81ac494dfdb1ff9832689ef510' \
    --header 'Content-Type: application/json' \
    --data '{
    "account_id": "2c92c0f96abc17de016abd62bd0c5854",
    "description": "credit memo from price",
    "document_date": "2023-04-01",
    "items": [
      {
        "price_id": "8ad0887182afa5d00182b017730c5fcb",
        "amount": 10,
        "quantity": 5,
        "description": "Description of the credit memo item",
        "service_start": "2022-12-01"
      }
    ],
    "reason_code": "Ad hoc credit"
  }'
Copy
Copied
LocalDate date = LocalDate.of(2022,9,20);

BillingDocumentItemCreateRequest priceItem = new BillingDocumentItemCreateRequest()
    .amount(new BigDecimal(10))
    .quantity(new BigDecimal(5))
    .serviceStart(date)
    .description("Test item description")
    .priceId(price.getId());

List<BillingDocumentItemCreateRequest> billingDocumentItemList = new ArrayList<BillingDocumentItemCreateRequest>();
billingDocumentItemList.add(priceItem);

BillingDocumentCreateRequest creditMemoRequest = new BillingDocumentCreateRequest()
    .accountId("8ad09b7d8292b85d0182a4d6f875225a")
    .description("credit memo from price")
    .documentDate(date)
    .type(BillingDocumentCreateRequest.TypeEnum.CREDIT_MEMO)
    .items(billingDocumentItemList)
    .reasonCode("Ad hoc credit");

BillingDocument creditMemoFromPrice = zuoraClient.billingDocuments().postBillingDocument(creditMemoRequest);
Copy
Copied
const priceItem = {
    amount: 10,
    quantity: 5,
    description: 'Test item description',
    service_start: '2022-09-20',
    price_id: '8ad0887182afa5d00182b017730c5fcb',
};
 
const creditMemoRequest = {
    account_id: '8ad09b7d8292b85d0182a4d6f875225a',
    description: 'credit memo from price',
    document_date: '2022-09-20',
    type: 'credit_memo',
    items: [priceItem],
    reason_code: 'Ad hoc credit',
};
 
const newCreditMemoFromPrice = await zuoraClient.billingDocuments.postBillingDocument(creditMemoRequest);

Create bill runs

An ad hoc bill run lets you create a bill run for a specific and usually one-time purpose. Invoices or credit memos are generated from the bill run depending on the changes made to the subscriptions. You can use the Create a bill run operation to create an ad hoc bill run.

To create a bill run, you must specify the following required fields:

  • invoice_date: the date displayed on the billing document.
  • target_date: all unbilled items before this date will be included in the bill run.
Suppose that a batch of your customers (Batch1) subscribed to your delivery service for 1 year, and you have posted the 1 year’s invoices to them. However, on April 10th, some customers canceled their recurring and one-time subscriptions starting from July 1st. In this case, the target_date should be specified as a date on or later than 2023-07-01, and the invoice date can be specified as 2023-04-10.
cURLJavaNode
Copy
Copied
curl --request POST \
  --url https://rest.test.zuora.com/v2/bill_runs \
  --header 'Authorization: Bearer 9ebfa50a12ef4d77b3de8c2c17923250' \
  --header 'Content-Type: application/json' \
  --data '{
        	"invoice_date": "2023-04-10",
            "target_date": "2023-07-01",
            "batches": "Batch1",
            "charges_excluded": "Usage"
}'
Copy
Copied
LocalDate invoiceDate = LocalDate.of(2023,4,10);
LocalDate targetDate = LocalDate.of(2023,7,1);

BillRunCreateRequest billRunRequest = new BillRunCreateRequest()
        .invoiceDate(invoiceDate)
        .targetDate(targetDate)
        .batches(Collections.singletonList("Batch1"))
        .chargesExcluded(Collections.singletonList("Usage"));

BillRun billRun = zuoraClient.billRuns().createBillRun(billRunRequest);
System.out.print(billRun);
Copy
Copied
const billRunRequest = {
    invoice_date: '2023-04-10',
    target_date: '2023-07-01',
    batches: 'Batch1',
    charges_excluded: 'Usage',
}

const billRuns =  await zuoraClient.billRuns.createBillRun(billRunRequest);

console.log(billRuns);
If the bill run request succeeds, you will get the following 201 Created response:
Copy
Copied
{
	"id": "8ad094b987554ccd018755d23115741f",
	"updated_by_id": "8ad09bce80507dab0180688bdabc20cb",
	"updated_time": "2023-04-06T02:07:31-07:00",
	"created_by_id": "8ad09bce80507dab0180688bdabc20cb",
	"created_time": "2023-04-06T02:07:31-07:00",
	"custom_fields": {},
	"custom_objects": {},
	"account_id": "",
	"email": false,
	"post": false,
	"renew": false,
	"day_of_month": "AllBillCycleDays",
	"bill_run_number": "BR-00000130",
	"bill_run_time": "",
	"invoice_date": "2023-04-10",
	"target_date": "2023-07-01",
	"state": "pending",
	"batches": "Batch1",
	"charges_excluded": "Usage",
	"email_zero_amount_invoices": true,
	"invoices_sent": false,
	"last_invoice_sent_time": "",
	"accounts_processed": 0,
	"invoices_generated": 0,
	"credit_memos_generated": 0
}

View billing documents

The List and Retrieve operations of Invoice, Credit Memo, and Debit Memo are invoked when end subscribers want to view their billing documents or the details of a single billing document.

Use the following operations to view invoices, credit memos, or debit memos in your tenant:

To further filter the results, specify the filter[] query parameter. For example, to list all posted invoices, you can set the filter[] parameter to state.EQ:posted. For the full list of filterable fields on each object, see Expands, filter, fields, and sort.

List invoices

The following example lists all invoices in your tenant:

cURLJavaNode
Copy
Copied
curl --request GET \
      --url 'https://rest.test.zuora.com/v2/invoices' \
      --header 'Authorization: Bearer 406c9801b1cb4899a8dec61ed4fb5111' \
      --header 'Content-Type: application/json'
Copy
Copied
InvoiceListResponse invoiceListResponse = zuoraClient.invoices().getinvoices(null,Collections.singletonList("account"),null);
System.out.println(invoiceListResponse);
Copy
Copied
const invoiceList = await zuoraClient.invoices.getInvoices(({
        filter: [
         'document_date.GT:2023-01-01'
        ]
   }));

console.log(invoiceList);  

List credit memos

The following example lists all credit memos in your tenant:

cURLJavaNode
Copy
Copied
curl --request GET \
      --url https://rest.test.zuora.com/v2/credit_memos \
      --header 'Authorization: Bearer e6f7611768fd4297aade3e9e68a56f8f' \
      --header 'Content-Type: application/json'
Copy
Copied
CreditMemoListResponse creditMemoListResponse = zuoraClient.creditMemos().getCreditMemos(null,Collections.singletonList("account"),null);
System.out.println(creditMemoListResponse);     
Copy
Copied
const creditMemoList = await zuoraClient.creditMemos.getCreditMemos(({
    filter: [
     'document_date.GT:2023-01-01'
    ]
}));

console.log(creditMemoList);  

List debit memos

The following example lists all debit memos in your tenant:

cURLJavaNode
Copy
Copied
curl --request GET \
      --url https://rest.test.zuora.com/v2/debit_memos \
      --header 'Authorization: Bearer 5e8a3e540235449cb6615465411f445b' \
      --header 'Content-Type: application/json'
Copy
Copied
DebitMemoListResponse debitMemoListResponse = zuoraClient.debitmemo().getDebitMemoes(null,Collections.singletonList("account"),null);
System.out.println(debitMemoListResponse);
Copy
Copied
const debitMemoList = await zuoraClient.debitMemos.getDebitMemoes(({
    filter: [
     'document_date.GT:2023-01-01'
    ]
}));

console.log(debitMemoList);