Use cases of subscription management and invoice generation
The Flexible Billing Attributes feature is generally available and has been enabled for all customers in Sandbox environments. If you want to enable this feature in your Production environments, contact your Zuora account team for assistance.
The following use cases are presented to showcase how you can use Flexible Billing Attributes to manage subscriptions and generate invoices.
Pre-conditions for all use cases
To simplify the explanation of each use case, the following pre-conditions apply to all use cases in the sections below.
Condition item | Details |
---|---|
Customer account |
|
Product rate plan charge |
|
Enabled features |
|
Taxation module |
|
Case 1: Create subscriptions with different bill-to contacts and payment terms
In this use case, subscriptions are created with different bill-to contacts and different payment terms. Subscriptions are invoiced based on the bill-to contact and payment term.
As listed in the table, the four subscriptions can be categorized into two groups based on the bill-to contact and payment term. Subscriptions S001 and S002 are one group. For this group, the bill-to contact is Steve America and the payment term is Net 30. Subscriptions S003 and S004 are the other group. For this group, the bill-to contact is Tom Lee and the payment term is Net 45.
To generate invoices for these subscriptions, use the Generate billing documents by account ID operation with the autoPost
field set to true
.
- Invoice INV001 is generated for S001 and S002, with the bill-to contact as Steve America and the payment term as Net 30.
- Invoice INV002 is generated for S003 and S004, with the bill-to contact as Tom Lee and the payment term as Net 45.
Subscription | Generated Invoice | ||||||
---|---|---|---|---|---|---|---|
Subscription Number | Bill To Contact | Subscription Term | Effective Start Date | Payment Term | Invoice Number | Bill To Contact | Payment Term |
S001 | Steve America | 12 Month | 2022-01-01 | Net 30 | INV001 | Steve America | Net 30 |
S002 | Steve America | 12 Month | 2022-01-01 | Net 30 | |||
S003 | Tom Lee | 12 Month | 2022-01-01 | Net 45 | INV002 | Tom Lee | Net 45 |
S004 | Tom Lee | 12 Month | 2022-01-01 | Net 45 |
After invoices are generated, you can create a payment for invoice INV001 and another payment for invoice INV002.
Case 2: Renew subscription early and update bill-to contact and payment term
In this use case, after completing all the operations in Case 1, you renew subscriptions S001 and S002 by updating their subscription term, bill-to contact, and payment and changing the charges.
After the all the operations in Case 1, you use the Create an order operation to do the following updates:
- Create an order with the order action of Update Terms and Conditions to update the subscription term from 12 months to 20 months, bill-to contact to Lock Richard, and payment term to Net 60 for subscriptions S001 and S002.
- Create an order with the order action of Remove Product to remove the charges with the effective date as 2022-09-01 for subscriptions S001 and S002.
- Create an order with the order action of Add Product to add new charges with the effective date as 2022-09-01 to subscriptions S001 and S002.
To generate billing documents for the renewed subscriptions, use the Generate billing documents by account ID operation with the targetDate
field as 2023-01-01
and the autoPost
field as true
.
- Credit memo CM001 is generated to provide credit for the removed charges from 2022-09-01 to 2022-12-31.
- Invoice INV003 is generated for the new charges from 2022-09-01 to 2023-08-31.
Subscription | Generated Billing Document | ||||||
---|---|---|---|---|---|---|---|
Subscription Number | Bill To Contact | Subscription Term | Effective Start Date | Payment Term | Document Number | Bill To Contact | Payment Term |
S001 | Lock Richard | 20 Month | 2022-01-01 | Net 60 | INV003 CM001 |
Lock Richard | Net 30 |
S002 | Lock Richard | 20 Month | 2022-01-01 | Net 60 |
Both the generated invoice and credit memo uses the latest billing attributes, bill-to contact and payment term. After the billing documents are generated, you can apply credit memo CM001 to invoice INV003.
Case 3: Create subscriptions without payment term and bill-to contact
In this use case, a subscription is created without the bill-to contact and payment term being specified. When a bill run is created, the invoice for this subscription will be generated for the default bill-to contact and payment term.
As listed in the following table, two subscriptions are created. Subscription S001 is created without the bill-to contact and payment term being specified. A bill run is created with the targetDate
field as 2022-01-01
and the autoPost
field as true
. As a result, invoice INV001 is generated for subscription S001. Because this subscription does not have the bill-to contact and payment term specified, the default bill-to contact Ray Lockman and payment term Net 30 are used for invoice INV001. Invoice INV002 is generated for subscription S002 with the bill-to contact as Steve America and payment term as Net 45.
Subscription | Generated Invoice | ||||||
---|---|---|---|---|---|---|---|
Subscription Number | Bill To Contact | Subscription Term | Effective Start Date | Payment Term | Invoice Number | Bill To Contact | Payment Term |
S001 | Not specified | 12 Month | 2022-01-01 | Not specified | INV001 | Ray Lockman | Net 30 |
S002 | Steve America | 12 Month | 2022-01-01 | Net 45 | INV002 | Steve America | Net 45 |
Case 4: Renew subscription and update bill-to contact and payment term
In this use case, there are two subscriptions. After the first invoice is generated, both subscriptions are renewed, and the bill-to contact and payment terms of one subscription are changed.
As listed in the following table, two subscriptions are created without the bill-to contact and payment term being specified in the initial version. A bill run is created with the targetDate
field as 2022-01-01
and the autoPost
field as true
. Invoice INV001 is generated for both subscriptions with the default bill-to contact Ray Lockma and payment term Net 30.
Subscription | Generated Invoice | ||||||
---|---|---|---|---|---|---|---|
Subscription Number | Bill To Contact | Subscription Term | Effective Start Date | Payment Term | Invoice Number | Bill To Contact | Payment Term |
S001 | Not specified | 12 Month | 2022-01-01 | Not specified | INV001 | Ray Lockman | Net 30 |
S002 | Not specified | 12 Month | 2022-01-01 | Not specified |
After the first invoice is generated, the Create an order operation is used to do the following updates:
- Renew subscription S001.
- Renew subscription S002 and update the bill-to contact to Steve America and Payment Term to Net 45.
When the order operation is done, the subscriptions are updated as shown in the table below. Another bill run is created with the targetDate
field as 2023-01-01
and the autoPost
field as true
. As a result, invoice INV002 is generated for subscription S001 with the bill-to contact as Ray Lockman and payment term as Net 30. Invoice INV003 is generated for subscription S002 with the bill-to contact as Steve America and payment term as Net 45.
Subscription | Generated Invoice | ||||||
---|---|---|---|---|---|---|---|
Subscription Number | Bill To Contact | Subscription Term | Effective Start Date | Payment Term | Invoice Number | Bill To Contact | Payment Term |
S001 | Not specified | 12 Month | 2023-01-01 | Not specified | INV002 | Ray Lockman | Net 30 |
S002 | Steve America | 12 Month | 2023-01-01 | Net 45 | |||
INV003 | Steve America | Net 45 |
Case 5: Cancel subscription in the middle of the current term
In this use case, subscriptions are created with different bill-to contacts and different payment terms. After being invoiced, the subscriptions are canceled in the middle of the current term. Then, credit memos are generated for different bill-to contacts.
As listed in the following table, the four subscriptions can be categorized into two groups based on the bill-to contact and payment term. Subscriptions S001 and S002 are one group. For this group, the bill-to contact is Steve America and the payment term is Net 30. Subscriptions S003 and S004 are the other group. For this group, the bill-to contact is Tom Lee and the payment term is Net 45.
A bill run is created with the targetDate
field as 2022-01-01
and the autoPost
field as true
. Then, invoice INV001 is generated for S001 and S002, with the bill-to contact as Steve America and the payment term as Net 30. Invoice INV002 is generated for S003 and S004, with the bill-to contact as Tom Lee and the payment term as Net 45.
Subscription | Generated Invoice | ||||||
---|---|---|---|---|---|---|---|
Subscription Number | Bill To Contact | Subscription Term | Effective Start Date | Payment Term | Invoice Number | Bill To Contact | Payment Term |
S001 | Steve America | 12 Month | 2022-01-01 | Net 30 | INV001 | Steve America | Net 30 |
S002 | Steve America | 12 Month | 2022-01-01 | Net 30 | |||
S003 | Tom Lee | 12 Month | 2022-01-01 | Net 45 | INV002 | Tom Lee | Net 45 |
S004 | Tom Lee | 12 Month | 2022-01-01 | Net 45 |
In the middle of the current term, all subscriptions are canceled with the effective date as 2022-09-01. Another bill run is created with the targetDate
field as 2022-09-01
and the autoPost
field as true
. As a result, credit memo CM-01 is generated for subscriptions S001 and S002 with the bill-to contact as Steve America. Credit memo CM-02 is generated for subscriptions S003 and S004 with the bill-to contact as Tom Lee.
Case 6: Regenerate invoice for current term after bill-to contact and payment term change
In this use case, two subscriptions are created without the bill-to contact and payment term being specified. After the first invoice is generated, both subscriptions are renewed, and the bill-to contact and payment term of one subscription are changed. Then, another bill run is created to generate two invoices. However, the updated bill-to contact and payment term information is wrong. So the wrong invoice is canceled. After the bill-to contact and payment term information is corrected, a third bill run is created to generate the correct invoice.
As listed in the following table, two subscriptions are created without the bill-to contact and payment term being specified in the initial version. A bill run is created with the targetDate
field as 2022-01-01
and the autoPost
field as true
. Invoice INV001 is generated for both subscriptions. The default bill-to contact is Ray Lockman and the payment term is Net 30 according to the account settings.
Subscription | Generated Invoice | ||||||
---|---|---|---|---|---|---|---|
Subscription Number | Bill To Contact | Subscription Term | Effective Start Date | Payment Term | Invoice Number
|
Bill To Contact | Payment Term |
S001 | Not specified | 12 Month | 2022-01-01 | Not specified | INV001 | Ray Lockman | Net 30 |
S002 | Not specified | 12 Month | 2022-01-01 | Not specified |
After the first invoice is generated, the Create an order operation is used to do the following updates:
- Renew subscription S001.
- Renew subscription S002 and update the bill-to contact to Steve America and Payment Term to Net 45.
When the order operation is done, the subscriptions are updated as shown in the table below. Another bill run is created with the targetDate
field as 2023-01-01
and the autoPost
field as true
. Then, invoice INV002 is generated for subscription S001 with the bill-to contact as Ray Lockman and payment term as Net 30. Invoice INV003 is generated for subscription S002 with the bill-to contact as Steve America and payment term as Net 45.
Subscription | Generated Invoice | ||||||
---|---|---|---|---|---|---|---|
Subscription Number | Bill To Contact | Subscription Term | Effective Start Date | Payment Term | Invoice Number | Bill To Contact | Payment Term |
S001 | Not specified | 12 Month | 2023-01-01 | Not specified | INV002 | Ray Lockman | Net 30 |
S002 | Steve America | 12 Month | 2023-01-01 | Net 45 | |||
INV003 | Steve America | Net 45 |
After INV002 and INV003 are generated, the end customer finds that the bill-to contact of invoice INV003 is wrong. So invoice INV003 is reversed. Credit memo CM-01 is automatically generated during invoice reversal with the bill-to contact as Steve America.
Another order is created to update the terms and conditions for subscription S002. The bill-to contact is updated to Tom Lee and the payment term is updated to Net 60. When the order operation is done, subscription S002 is updated as shown in the table below. A third bill run is created with the targetDate
field as 2023-01-01
and the autoPost
field as true
. As a result, invoice INV004 is generated for S002 with bill-to contact as Tom Lee and payment term as Net 60.
Subscription | Generated Invoice | ||||||
---|---|---|---|---|---|---|---|
Subscription Number | Bill To Contact | Subscription Term | Effective Start Date | Payment Term | Invoice Number | Bill To Contact | Payment Term |
S002 | Tom Lee | 12 Month | 2023-01-01 | Net 60 | INV004 | Tom Lee | Net 60 |
Case 7: Regenerate invoice for past term after bill-to contact and payment term change
In this use case, two subscriptions are created without the bill-to contact and payment term being specified. After the first invoice is generated, both subscriptions are renewed, and the bill-to contact and payment term of one subscription are changed. Then, another bill run is created to generate two invoices. However, the updated bill-to contact and payment term information of the first invoice that has not been paid is wrong. Therefore, all the generated invoices are reversed to correct mistakes. After the bill-to contact and payment term information is corrected, a third bill run is created to generate the correct invoice.
As listed in the following table, two subscriptions are created without the bill-to contact and payment term being specified in the initial version. A bill run is created with the targetDate
field as 2022-01-01
and the autoPost
field as true
. Invoice INV001 is generated for both subscriptions. The default bill-to contact is Ray Lockman and the payment term is Net 30 according to the account settings.
Subscription | Generated Invoice | ||||||
---|---|---|---|---|---|---|---|
Subscription Number | Bill To Contact | Subscription Term | Effective Date | Payment Term | Invoice Number | Bill To Contact | Payment Term |
S001 | Not specified | 12 Month | 2022-01-01 | Not specified | INV001 | Ray Lockman | Net 30 |
S002 | Not specified | 12 Month | 2022-01-01 | Not specified |
After the first invoice is generated, the Create an order operation is used to do the following updates:
- Renew subscription S001.
- Renew subscription S002 and update the bill-to contact to Steve America and Payment Term to Net 45.
When the order operation is done, the subscriptions are updated as shown in the table below. Another bill run is created with the targetDate
field as 2023-01-01
and the autoPost
field as true
. Then, invoice INV002 is generated for subscription S001 with the bill-to contact as Ray Lockman and payment term as Net 30. Invoice INV003 is generated for subscription S002 with the bill-to contact as Steve America and payment term as Net 45.
Subscription | Generated Invoice | ||||||
---|---|---|---|---|---|---|---|
Subscription Number | Bill To Contact | Subscription Term | Effective Start Date | Payment Term | Invoice Number | Bill To Contact | Payment Term |
S001 | Not specified | 12 Month | 2023-01-01 | Not specified | INV002 | Ray Lockman | Net 30 |
S002 | Not specified | 12 Month | 2023-01-01 | Net 45 | INV003 | Steve America | Net 45 |
After INV002 and INV003 are generated, the end customer finds that the bill-to contact of invoice INV001 is wrong, and INV001 has not been paid yet. Therefore, invoices INV001, INV002, and INV003 are reversed.
- Credit memo CM001 is automatically generated during invoice INV001 reversal with the bill-to contact as Steve America.
- Credit memo CM002 is automatically generated during invoice INV002 reversal with the bill-to contact as Ray Lockman.
- Credit memo CM003 is automatically generated during invoice INV003 reversal with the bill-to contact as Ray Lockman.
Note that canceling the Renewal order action is not supported.
Subsequently, another order is created to update the terms and conditions for subscriptions S001 and S002. The bill-to contact is updated to Tom Lee and the payment term is updated to Net 60. When the order operation is done, subscriptions S001 and S002 are updated as shown in the table below. A third bill run is created with the targetDate
field as 2022-01-01
and the autoPost
field as true
. As a result, invoice INV004 is generated for S001 and S002 with the bill-to contact as Tom Lee and payment term as Net 60.
Subscription | Generated Invoice | ||||||
---|---|---|---|---|---|---|---|
Subscription Number | Bill To Contact | Subscription Term | Effective Start Date | Payment Term | Invoice Number | Bill To Contact | Payment Term |
S001 | Tom Lee | 12 Month | 2023-01-01 | Net 60 | INV004 | Tom Lee | Net 60 |
S002 | Tom Lee | 12 Month | 2023-01-01 | Net 60 |
Another order is created to update the terms and conditions for subscription S002. The bill-to contact is updated to Steve America and the payment term is updated to Net 45. After the order operation is done, a fourth bill run is created with the targetDate
field as 2023-01-01
and the autoPost
field as true
. As a result, invoice INV005 is generated for S001 with the bill-to contact as Tom Lee and payment term as Net 60, and invoice INV006 is generated for S002 with the bill-to contact as Steve America and payment term as Net 45.
Subscription | Generated Invoice | ||||||
---|---|---|---|---|---|---|---|
Subscription Number | Bill To Contact | Subscription Term | Effective Start Date | Payment Term | Invoice Number | Bill To Contact | Payment Term |
S001 | Tom Lee | 12 Month | 2023-01-01 | Net 60 | INV005 | Tom Lee | Net 60 |
S002 | Steve America | 12 Month | 2023-01-01 | Net 45 | INV006 | Steve America | Net 45 |
Case 8: Update bill-to contact and payment term in the middle of current term
In this use case, two subscriptions have different bill-to contacts and payment terms in the initial version. After invoices are generated for the first billing period, the bill-to contact and payment term are updated for one subscription in the middle of the current term.
As listed in the following table, the two subscriptions are created with the details as shown in the table below. The bill-to contact and payment term are not specified for subscription S001. The bill-to contact for subscription S002 is Steve America and the payment term is Net 45. The billing period is monthly for both subscriptions.
A bill run is created with the targetDate
field as 2022-01-01
and the autoPost
field as true
. Invoice INV001 is generated for subscription S001 for January. The bill-to contact is Ray Lockman and the payment term is Net 30. Invoice INV002 is generated for subscription S002 for January. The bill-to contact is Steve America and the payment term is Net 45.
Subscription | Generated Invoice | ||||||
---|---|---|---|---|---|---|---|
Subscription Number | Bill To Contact | Billing Period of Charge | Effective Start Date | Payment Term | Invoice Number | Bill To Contact | Payment Term |
S001 | Not specified | Month | 2022-01-01 | Not specified | INV001 | Ray Lockman | Net 30 |
S002 | Steve America | Month | 2022-01-01 | Net 45 | |||
INV002 | Steve America | Net 45 |
After that, the Create an order operation is used to do the following updates:
- The term of subscription S001 is updated to 12 months.
- The term of subscription S002 is updated to 12 months. The bill-to contact is updated to Tom Lee and the payment term is updated to Net 60.
When the order operation is done, the subscriptions are updated as shown in the table below. Another bill run is created with the targetDate
field as 2022-01-01
and the autoPost
field as true
. Then, invoice INV003 is generated for subscription S001 for February. The bill-to contact is Ray Lockman and the payment term is Net 30. Invoice INV004 is generated for subscription S002 for February. The bill-to contact is Tom Lee and the payment term is Net 60.
Subscription | Generated Invoice | |||||||
---|---|---|---|---|---|---|---|---|
Subscription Number | Bill To Contact | Subscription Term | Billing Period of Charge | Effective Start Date | Payment Term | Invoice Number | Bill To Contact | Payment Term |
S001 | Not specified | 12 Month | Month | 2022-01-01 | Not specified | INV003 | Ray Lockman | Net 30 |
S002 | Tom Lee | 12 Month | Month | 2022-01-01 | Net 60 | |||
INV004 | Tom Lee | Net 60 |
Case 9: Create subscriptions with different bill payment terms
In this use case, subscriptions are created with no bill-to contact and different payment terms. When subscriptions are invoiced, invoices will be generated based on different payment terms for the default bill-to contact.
As listed in the table below, all three subscriptions are created without the bill-to contact being specified. The payment terms are different. Subscription S001 does not have the payment term specified. Subscriptions S002 and S003 have the payment term as Net 45.
A bill run is created with the targetDate
field as 2022-01-01
and the autoPost
field as true
. Invoices are generated based on the bill-to contact and payment term. Invoice INV001 is generated for subscription S001, with the bill-to contact as Ray Lockman and payment term as Net 30. Another invoice INV002 is generated for both S002 and S003, with the bill-to contact as Ray Lockman and payment term as Net 45.
Subscription | Generated Invoice | ||||||
---|---|---|---|---|---|---|---|
Subscription Number | Bill To Contact | Subscription Term | Effective Start Date | Payment Term | Invoice Number | Bill To Contact | Payment Term |
S001 | Not specified | 12 Month | 2022-01-01 | Not specified | INV001 | Ray Lockman | Net 30 |
S002 | Not specified | 12 Month | 2022-01-01 | Net 45 | INV002 | Ray Lockman | Net 45 |
S003 | Not specified | 12 Month | 2022-01-01 | Net 45 |
Case 10: Transfer a subscription with its bill-to contact already specified to a destination invoice account
The invoice owner transfer can be implemented only through the Create an order API operation. When a subscription with the billToContactId
field already specified is transferred to a destination invoice account, the billToContactId
field must be either specified to a bill-to contact under the destination invoice account or be cleared to complete the invoice owner transfer. Clearing the billToContactId
field is implemented by setting theclearingExistingBillToContact
field to true
.
During the invoice owner transfer, the paymentTerm
field of the subscription can also be specified or cleared. Clearing the paymentTerm
field is implemented by setting theclearingExistingPaymentTerm
field to true
.
As listed in the table below. Before the invoice owner transfer, a subscription S001 is originally created under account A00001. Steve America is specified as the bill-to contact of account A00001, and the default payment term of account A00001 is Net 30. Tom Lee is specified as the bill-to contact of the subscription S001, and the payment term of the subscription S001 is specified as Net 45. During the invoice owner transfer, an owner transfer order action is created with the destination invoice account set as A00002, the billToContactId
field of the subscription S001 is specified as Richard Li under account A00002, and the paymentTerm
field of the subscription S001 is specified as Net 50. After the invoice owner transfer, the subscription S001 is transferred to the destination invoice account A00002. The payment term of the subscription S001 is Net 50 and the bill-to contact is Richard Li. Thereby, Richard Li under the destination invoice account A00002 will be invoiced.
Before transfer | After transfer | |||||
---|---|---|---|---|---|---|
Account or Subscription | Bill To Contact | Payment Term | Account or Subscription | Invoice Number | Bill To Contact | Payment Term |
A00001 | Steve America | Net 30 | A00002 | N/A | N/A | N/A |
S001 | Tom Lee | Net 45 | S001 | INV001 | Richard Li | Net 50 |