Context object for rendering tax app templates

Last updated
Save as PDF

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.

Advanced custom fields cannot be used with the Connect Tax App. Similarly, custom fields created using Object Manage cannot be utilized with the Connect Tax App.

Field name	Type	Description
document	object	Standard fields and custom fields of an invoice, credit memo, or debit memo.
customer	object	Standard fields and custom fields of a customer.
seller	object	Seller information configured for the engine settings.
document_items	array of objects	Standard fields and custom fields of an invoice item, credit memo item, or debit memo item.
today	string	The date when the object is created.

Standard 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 the YYYY-MM-DD format.
taxCompanyCode	string	The unique code that identifies a company account in the tax vendor's system. Note: For the standard template (tax calculation), this field is at the document_item level: `document_item["taxCompanyCode"]` For the void template (tax void), this field is at the document level: `document["taxComapnyCode"]`
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.

Standard fields on the customer object

Field name	Type	Description
id	string	The ID of the customer.
address 1	string	First address line.
address 2	string	Second address line.
city	string	City name.
county	string	County name.
state	string	State name.
country	string	Country name.
zipCode	string	Zip code.
taxRegion	string	Tax region as defined in taxation rules.
accountNumber	string	A unique account number.
accountName	string	A unique account name.
crmAccountId	string	CRM account ID for the customer account.
accountId	string	The ID of the customer account.
stateISO	string	State ISO code.

Standard fields on the seller object

Field name	Type	Description
username	string	User name to log into the tax vendor’s system.
password	string	Password to log into the tax vendor’s system.
endpoint	string	Endpoint URL provided by the tax vendor to receive tax requests.
company_code	string	Unique code that identifies a company account in the tax vendor’s system.
division	string	Division name as defined in Seller Information when configuring tax engine settings.
auth_type	string	Type of authentication as defined in System Configuration when configuring tax engine settings.
address 1	string	First address line as defined in Seller Information when configuring tax engine settings.
address 2	string	Second address line as defined in Seller Information when configuring tax engine settings.
city	string	City name as defined in Seller Information when configuring tax engine settings.
county	string	County name as defined in Seller Information when configuring tax engine settings.
state	string	State name as defined in Seller Information when configuring tax engine settings.
country	string	Country name as defined in Seller Information when configuring tax engine settings.
zipCode	string	Zip code as defined in Seller Information when configuring tax engine settings.
taxRegion	string	Tax regions as defined in Seller Information when configuring tax engine settings.

Standard 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: 0: No 1: Yes 2: PendingVerification
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: For the standard template (tax calculation), this field is at the document_item level: `document_item["taxCompanyCode"]` For the void template (tax void), this field is at the document level: `document["taxComapnyCode"]`
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. For example, to set addresses in the template, use the following field: `document_item["customer"]`
billTo	string	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>
invoiceOwner	object	A Customer object which only has the following fields as standard fields: crmAccountId currency id accountNumber
subscriptionOwner	object	A Customer object which only has the following fields as standard fields: crmAccountId currency id accountNumber

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.

Tax app templates for standalone invoices

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.