Context object for rendering tax app templates
Overview of the Context object
The Context object is a collection of contextual data stored in the JSON format. Such data represents background information about a person, an event, or a thing. The Context object is primarily used to facilitate the exchange of data between applications.
Zuora uses the Context object to populate information needed in a tax app template, which serves as the request body of the call Zuora sends to your tax vendor.
Here is the structure of the Context object in Zuora.
Objects
Field name | Type | Description |
---|---|---|
document | object | Standard fields and custom fields of an invoice item, credit memo item, or debit memo item. |
customer | object | Represents the soldTo address for the document. If the document includes multiple addresses, item-level addresses should be used for accuracy. When a billing document contains different addresses for its items, the customer object reflects the soldTo address of the first document item. |
seller | object | Seller information configured for the engine settings. This is applicable when you configure a seller in the configurable tax app. |
today | string | The date when the object is created. |
billTo | object |
Represents the billTo address for the document. Reference it in the template using:
|
account | object |
Represents the Account object that owns the billing document (the invoice owner). Custom fields for the Account object are supported. You can reference it in the template using:
Note: |
invoiceOwner | object |
Represents the Account object that owns the billing document. This is applicable regardless of the document items being from subscription charges or non-subscription charges. You can reference it in the template with:
|
subscriptionOwner | object |
Represents the Account object that owns the subscription (the subscription owner) when document items are from subscription charges. Reference it in the template using:
|
Subscription | object |
Represents the subscription object applicable for document items from subscription charges. Reference it's custom fields in the template using:
|
ratePlanCharge | object |
Represents the Subscription Rate Plan Charge object applicable for document items from subscription charges. Reference it’s custom fields in the template using:
|
productRatePlanCharge | object |
Represents the Product Rate Plan Charge object associated with the billing document item. It applies in the following scenarios:
Reference it’s custom fields in the template using:
|
Fields on the document object
Field name | Type | Description |
---|---|---|
id | string | The ID of the document. |
invoiceNumber | string | The identification number of the invoice, credit memo, or debit memo. |
invoiceDate | string | The date that appears on the invoice in YYYY-MM-DD format. |
taxCompanyCode | string |
The unique code that identifies a company account in the tax vendor's system. Note:
|
currency | string |
The ISO 3-letter Currency Code. See Currency code for reference. You can specify the currency on the subscription level or invoice, credit memo, debit memo level for the Billing Document Level Currency. The currency value will not be the account default currency anymore. You must have the Multiple Currencies feature enabled to change the currency value. |
preview_mode | boolean | Specifies whether to calculate tax in preview mode. |
call_type | string | The type of the call. Enum: “invoice”, “memo”. |
event_type | string | The type of the event. Enum: “taxPreview”, “taxGenerate”, “taxVoid”, "taxOverride". Note that prior to using "taxOverride," confirm vendor compatibility, as this value is exclusive to certain vendors. |
memoType | string | The type of the memo. Enum: “CreditMemo”, “DebitMemo”. |
transactionId | string | The ID of the transaction. |
custom fields | string |
Custom fields are supported for invoices, credit memos, and debit memos. Below are some examples of how to reference custom fields in templates:
|
Fields on the customer object
Field name | Type | Description |
---|---|---|
id | string | The ID of the customer. |
address 1 | string | The first address line. |
address 2 | string | The second address line. |
city | string | The city name. |
county | string | The county name. |
state | string | The state name. |
country | string | The country name. |
zipCode | string | The zip code. |
taxRegion | string | The tax region as defined in taxation rules. |
accountNumber | string | A unique account number. |
accountName | string | A unique account name. |
crmAccountId | string | The CRM account ID for the customer account. |
accountId | string | The ID of the customer account. |
stateISO | string | The state ISO code. |
custom fields of Account | string |
Custom fields for the Account object are supported. The Account is the invoice owner of the billing document. Below is an example of how to reference a custom field for an Account:
|
custom fields of Contact | string |
Custom fields for the Contact object are supported. The Contact represents the sold-to contact for the billing document. Below is an example of how to reference a custom field for a Contact:
|
Fields on the seller object
Field name | Type | Description |
---|---|---|
username | string | The user name to log into the tax vendor’s system. |
password | string | The password to log into the tax vendor’s system. |
endpoint | string | The endpoint URL provided by the tax vendor to receive tax requests. |
company_code | string | A unique code that identifies a company account in the tax vendor’s system. |
division | string | The division name as defined in Seller Information when configuring tax engine settings. |
auth_type | string | The type of authentication as defined in System Configuration when configuring tax engine settings. |
address 1 | string | The first address line as defined in Seller Information when configuring tax engine settings. |
address 2 | string | The second address line as defined in Seller Information when configuring tax engine settings. |
city | string | The city name as defined in Seller Information when configuring tax engine settings. |
county | string | The county name as defined in Seller Information when configuring tax engine settings. |
state | string | The state name as defined in Seller Information when configuring tax engine settings. |
country | string | The country name as defined in Seller Information when configuring tax engine settings. |
zipCode | string | The zip code as defined in Seller Information when configuring tax engine settings. |
taxRegion | string | The tax region as defined in Seller Information when configuring tax engine settings. |
Fields on the document_item object
Field name | Type | Description |
---|---|---|
Id | string | The ID of the document item. |
productName | string | The name of the product. |
productRatePlanChargeName | string | The name of the product rate plan charge. |
productRatePlanChargeId | string | The ID of the product rate plan charge. |
taxExemptStatus | string |
The status of your customer's tax exemption. Enum values are:
|
taxExemptCertificateType | string | The type of the tax exemption certificate that your customer holds. |
taxExemptEntityUseCode | string | A unique entity use code to apply exemptions in the tax engine. |
totalAmount | number | The total amount on the document item. |
unitPrice | number | The per-unit price on the document item. |
taxCompanyCode | string |
The unique code that identifies a company account in the tax vendor's system. Note:
|
quantity | number | The number of units on the document item. |
vatId | string | The ID of the value-added tax. |
discountAmount | number | The amount of a fixed-amount discount on the document item. |
subscriptionRatePlanChargeId | string | The ID of the subscription rate plan charge that is associated with this document item. |
taxCode | string | The tax code identifies which tax rules and tax rates to apply to the document item. |
taxCalculationOwnerOption | number | Specifies the owner of the tax calculation. Enum: 0: Subscription Owner; 1: Invoice Owner.` |
taxDate | string | The date when the tax is applied to the document item. |
taxMode | number | The tax mode of the document item indicating whether the total amount includes tax. Enum: 0: TaxExclusive; 1: TaxInclusive. |
subscriptionOwnerId | string | The ID of the subscription owner. |
taxExemptIssuingJurisdiction | string | The jurisdiction in which the customer tax exemption certificate was issued. |
subscriptionName | string | The name of the subscription. |
subscriptionId | string | The ID of the subscription. |
taxExemptCertificateID | string | The ID of your customer's tax exemption certificate. |
appliedToItemId | string | The ID of the document item that the discount charge is applied to. |
ChargeNumber | string | The number of the rate plan charge associated with the billing item generated from the subscription rate plan charge. |
ServiceStartDate | string | The start date of the service for the document item. |
ServiceEndDate | string | The end date of the service for the document item. |
customer | object |
The same definition as Customer object. To avoid incorrect addresses generating, set addresses at the document_item level instead of the document level. The document can include different addresses at the document item level when you specify a sold-to contact on subscriptions or order line items. Refer to Flexible Billing Attributes for more details. For example, to set addresses in the template, use the following syntax:
Where |
billTo | object |
The Liquid tax template allows tax apps to extract BillTo address information. The document_items object is useful for retrieving BillTo information to share with external app vendors. An example of the syntax is as follows: <StreetAddress1>{{document_item["billTo"]["address1"]}} </StreetAddress1> <StreetAddress2>{{document_item["billTo"]["address2"]}} </StreetAddress2> <City>{{document_item["billTo"]["city"]}}</City> Custom fields of Contact object are supported. The syntax is as follows:
Where |
invoiceOwner | object |
Refers to the Account object, to which the billing document belongs. This is applicable regardless of the document items being from subscription charges or non-subscription charges. It only has the following fields as standard fields:
You can also reference custom fields of the Account object. For example:
|
subscriptionOwner | object |
Refers to the Account object, which is the subscription owner. This is applicable when document items come from subscription charges. It only has the following fields as standard fields:
You can also reference custom fields of the Account object. For example:
|
Custom Fields of InvoiceItem |
string |
Custom fields for
Where Note: Custom fields for |
Custom Fields of Subscription |
string |
Custom fields for
Where |
Custom Fields of RatePlanCharge |
string |
Custom fields for
|
Custom Fields of ProductRatePlanCharge |
string |
Custom fields for
|
Example of the Context object
The following example gives you a glimpse of what a Context object looks like. Note that a field name with the suffix of "__c", like "InvoiceItem.Location__c", represents a custom field.
{ "document": { "invoiceNumber": "INV00000033", // It could be a memo number, e.g. "CM00000016". "invoiceDate": "2020-12-03", // It could be a memo date in the billing request. "currency": "USD", "id": "2c92c8957621951d017627c52ab30e1c", }, "customer": { "country": "US", "accountNumber": "A00000008", }, "seller": { "username": "abc@example.com", "password": "1234567890!", "endpoint": " https://sandbox-rest.avatax.com/api/v2/transactions/create", }, "document_item": [ { "id": "2c92c8957621951d017627c52ad80e1e", "productRatePlanChargeId": "2c92c8fb7621951e01762261402608c5", "ProductRatePlanCharge.TextCustom__c": "RatePlanComponent-cfText", "subscriptionRatePlanChargeId": "2c92c8fe76218dcc017627b2b6234c7c", "subscriptionOwnerId": "2c92c8fb76219524017627b22dc568bc", "customer": { "country": "US", "accountNumber": "A00000008", }, //Customer tax evidence at item level "invoiceOwner": { "id": "2c92c8fb76219524017627b22dc568bc", "accountNumber": "A00000008", "Taxamo_tax_exempt_status__c": "No", }, "subscriptionOwner": { "id": "2c92c8fb76219524017627b22dc568bc", "accountNumber": "A00000008", "Taxamo_tax_exempt_status__c": "No", } } ], "today": "2021-02-07-12:01" }
Context object and tax app templates
The following example shows how information stored in the Context object fills a tax app template written in the Liquid language.
{ "cmpn": { "bscl": 1, "svcl": 0, "fclt": false, "frch": false, "reg": true }, "inv": [ { "doc": "{{document["invoiceNumber"]}}", "ccycd": "{{document["currency"]}}", "cmmt": false, "bill": { "ctry": "{{customer["country"]}}", "pcd":"{{customer["Contact.Pcode__c"]}}" }, "cust": 1, "lfln": false, "date": "{{document["invoiceDate"]}}", "itms": [ {% for document_item in document_items %} { "ref": "{{document_item["id"]}}", "chg": "{{document_item["totalAmount"]}}", "sale": 1, "bill": { "ctry": "{{document_item["customer"]["country"]}}" } "tran": "{{document_item["ProductRatePlanCharge.BillSoft_TransactionType__c"]}}", "serv": "{{document_item["ProductRatePlanCharge.BillSoft_ServiceType__c"]}}", "dbt": false, "adj": false, "disc": 0 } {% endfor %} ], "custref": "{{customer["accountNumber"]}}", "invn": "{{document["id"]}}", "invm": true, "dtl": true, "summ": true } ] }
Best practices for writing tax app templates
If you use multiple company codes on the tax vendor side, it is recommended NOT to use control flows (IF/ELSE/ELSE IF/END IF) in the standard template to override the company code you use in Zuora Billing (The company code you provided when setting up your Connect Tax Engine). Otherwise, the tax void requests might fail.
Custom Fields
Custom fields can also be used with the Connect Tax App. The custom fields of the following objects are available in the tax app templates:
- Account
- Contact (Contact supports legacy custom fields only)
- CreditMemo
- DebitMemo
- Invoice
- InvoiceItem (Invoice Item supports legacy custom fields only)
- ProductRatePlanCharge
- RatePlanCharge
- Subscription
The Contact and Invoice Item objects only support legacy custom fields.
Tax app templates for standalone invoices and Order Line Items (OLI)
If you enable Unified invoicing, you can create a standalone invoice without a subscription, an order, or even a product catalog. In this case, subscription-related and product-related fields on the Context object are correspondingly impacted.
Impact on subscription-related fields
The following custom fields do not exist and can not be referenced on the tax app templates:
- Subscription custom fields
- Rate plan charge custom fields
- Subscription owner information
Impact on product-related fields
If an invoice item is associated with a product rate plan charge, the custom fields of the product rate plan charge still exist; otherwise, the custom fields do NOT exist and can not be referenced on the tax app templates.
If you include the above-mentioned subscription-related fields or product-related fields in your tax app templates, their values are rendered as empty strings in the request body that Zuora sends to your tax vendor.
Order Line Items
When an invoice item comes from an Order Line Item (OLI), the following fields cannot be referenced in tax app templates:
- Standard fields of OLIs
- Custom fields of OLIs
- Custom fields from linked subscriptions. For more details, see Order Line Items with New Subscriptions.
However, when you specify the Bill-To and Sold-To contacts at the Order Line Item level, you can reference them in the tax app template through the `document_item` object. For example:
- To refer to Sold-To contact details, use:
`{{document_item["customer"]["address1"]}} `
- To refer to Bill-To contact fields, use:
`{{document_item["billTo"]["address1"]}} `