How to use isAssociatedCredit field on document_item object
The isAssociatedCredit field on the document_item object allows tax engines within Zuora's Configurable Tax App templates (including Avalara Direct Integration) to accurately identify whether an line item represents a credit or a charge.
Some taxes, such as E911 and E988, are flat fees charged per line rather than as a percentage of the amount. When a charge is priced at $0.00, a credit against it is also $0.00, so the tax engine cannot tell the credit apart from a charge. This results in incorrect tax calculation.
Zuora introduces a new field, isAssociatedCredit, which is available to tax templates of the Configurable Tax App.
-
The field is available to all configurable tax apps, including Avalara Direct Integration.
-
If you use a custom Tax Template, update it to read isAssociatedCredit. Zuora does not change custom templates.
-
The change applies to future tax calculations only. Posted invoices and credit memos are not recalculated.
You can access the field via document_item["isAssociatedCredit"].
Typical use cases
-
Quantity change, charge and credit on the same invoice. You reduce a subscription from 576 to 575 lines mid-period. Zuora credits the old quantity and bills the new one on the same invoice. With the field set, the net flat-fee tax is the credit for one line (for example, -$1.50 at $1.50 per line) instead of a large positive amount.
-
Quantity change, credit on a separate credit memo. The same change, but the credit lands on a credit memo and the charge on an invoice. Each document is taxed separately, and each item carries its own isAssociatedCredit value, so the credit memo is taxed as a credit.
-
Credit memo created from an invoice. You create a credit memo from a posted invoice to correct a billing error, write off, or reverse the invoice. The credit memo's flat-fee tax reverses the tax charged on the original invoice.
Product removal, subscription cancellation, and order line item returns work the same way.
When isAssociatedCredit is true or false
Item | Value |
|---|---|
| Credit against a previously billed charge, from an order action (quantity or price change, product removal, subscription cancellation, order line item return) | true |
| New charge | false |
| Credit memo item created from an invoice item that was a charge | true |
| Credit memo item created from an invoice item that was a credit | false |
| Debit memo item created from an invoice or a credit memo | false |
| Standalone invoice or memo item | false |
| Invoice or memo item from a product rate plan charge (PRPC) | false |
A credit memo item reverses its source invoice item, so its value is the opposite of the source item's value.
Example 1: Downsell on a $0 charge
A subscription has a $0.00 charge with a flat-fee E911 tax of $1.50 per line. You reduce the quantity from 576 to 575 lines mid-period. Zuora credits the old quantity and bills the new quantity, so the invoice contains two zero-amount items (This depends on the billing rule: Invoice/Credit Memo generation rule :
Item | Quantity | Amount | isAssociatedCredit |
|---|---|---|---|
| New charge | 575 | $0.00 | false |
| Credit for the previous charge | 576 | $0.00 | true |
Because both amounts are $0.00, the amount alone cannot show which item is the credit. isAssociatedCredit identifies it, so the tax template can apply the flat-fee tax to the credit item as a credit:
Item | Flat-fee tax |
|---|---|
| New charge (575 lines) | +$862.50 |
| Credit (576 lines) | -$864.00 |
| Net | -$1.50 |
If you then write off the invoice, the credit memo contains:
Item | Quantity | Amount | isAssociatedCredit |
|---|---|---|---|
| Reverses the new charge | 575 | $0.00 | true |
| Reverses the credit | 576 | $0.00 | false |
Example 2: Price change
A subscription's price changes from $50 to $100. The invoice contains:
Item | Amount | isAssociatedCredit |
|---|---|---|
| New charge | $100 | false |
| Credit for the previous charge | -$50 | true |
If you then write off the invoice, the credit memo contains:
Item | Amount | isAssociatedCredit |
|---|---|---|
| Reverses the $100 charge | $100 | true |
| Reverses the -$50 credit | -$50 | false |