Skip to main content

Context object for rendering tax app templates

Zuora

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.

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.
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.