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.
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.
curl --request POST \
--url https://rest.apisandbox.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"
}]
}' 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);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 invoice
Note 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:
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"
}'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);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:
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"
}'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);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);