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_Item 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 or credit memo.
invoiceDate string The date that appears on the invoice, in the YYYY-MM-DD format. 
currency string The ISO 3-letter Currency Code. See Currency code for reference.
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”.
memoType string The type of the memo. Enum: “CreditMemo”, “DebitMemo”.

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.
productRatePlanChargeId string The ID of the product rate plan charge.
taxExemptStatus string The status of your customer's tax exemption. Enum: “Yes”, “No”, “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.
taxCompanyCode string The unique code that identifies a company account in the tax vendor’s system.
totalAmount number The total amount on the document item.
unitPrice number The per-unit price on the document item.
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
invoiceOwner object A Customer object which only has the following four fields as standard fields:
  • crmAccountId
  • currency
  • id
  • accountNumber
subscriptionOwner object A Customer object which only has the following four 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
            }
        ]
}

 

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.