The service uses Vertex O Series Cloud (referred to hereafter as O Series Cloud) to provide tax rates and other information.

Your instance is configured during the implementation project.

O Series Cloud drives tax rate calculation with taxability drivers. These drivers can be based on several things like product and usage class. This integrations supports two of these, product and product class. These are mapped to the product_tax_code.code or product_tax_code.class fields in your Vertex for Marketplaces requests.

📘

Note

This topic contains links to the O Series Cloud documentation in Vertex Community. You need a Vertex Community user to view these topics.

Prerequisites

During your implementation project, you will set up O Series Cloud. You need to ensure the following perquisites are met:

• You have completed the deployment of O Series Cloud. See Overview of O Series Cloud in Vertex Community.
• Taxability Drivers (and the corresponding Product Tax Codes and Classes) are defined in O Series Cloud. See Use Tax Setup in O Series to define your unique taxability in Vertex Community.

Integration Points

How O Series Cloud integrates with your transaction processing depends on your implementation and the type of transaction. Some examples of these are:

• User Defined Taxability Drivers: You can use the product_tax_code.code or product_tax_code.class fields to trigger a specific taxability driver in O Series Cloud. See Use Tax Setup in O Series to define your unique taxability in Vertex Community.
• OSC Fields: Commonly used O Series Cloud fields like tax_type, imposition, and imposition_type are returned in responses.
• Flexible Output Fields: If you configure Flexible Output Fields in O Series Cloud, these are returned by the Vertex for Marketplaces API. See the Output Flexible Fields section of this topic. See also the About Flexible Fields topic in Vertex Community.
• Tax Area ID (TAID) fields: O Series Cloud records tax area information in TAID fields. You can view these in the Audit report. See the Tax Area ID (TAID) Fields section of this topic.
• US and Canadian Address Cleansing: For US and Canadian transactions, addresses can be corrected during a tax calculation (depending on your O Series Cloud settings). See the Overview section of Address Cleansing topic in Vertex Community.

Inbound Requests

You can use specific fields to send certain information to O Series Cloud via the Vertex for Marketplaces requests.

User-Defined Taxability Drivers

If you want to trigger user-defined taxability drivers, you need to add the product_tax_code.code or product_tax_code.class fields to the transaction line of your Vertex for Marketplaces requests. OSC will determine the tax rate based on the specified code and class.

❗️

Warning

Before you can add these codes to your requests, you must create the corresponding drivers in O Series Cloud. If you do not, a standard rate is used. These drivers need to contain the values you specify in the Vertex for Marketplace's requests.

If you do not specify the product_tax_code.code or product_tax_code.class fields, a standard rate is also returned.

Fields

You use the following fields to specify the code and class in your Vertex for Marketplace's requests.

Example

Here is an example of how these fields can be specified in the inbound request:

  "transaction": {
    "transaction_lines": [
      {
        "product_class": "P",
        "product_tax_code": {
           "code":  "{oseries_product_code}",
           "class": "{oseries_product_class}"
            }

Here is an example response:

                "product_tax_code": {
                    "code": "12345",
                    "class": "ABCD"
                },

Process Flow

Consider the following example. You have defined a taxability driver in O Series Cloud for a good. You define a Product Tax Code 12341 and a Product Tax Class of ABCD in O Series Cloud to represent this driver. You add these values to your Vertex for Marketplace's requests to trigger this driver when required.

The following diagram shows how O Series Cloud can be used to trigger a specific taxability driver:

The steps are:

1. The Buyer places the goods in their basket and they click Pay.
2. This triggers a Store Transaction request with the following JSON attached (This example is truncated for brevity):

{
  "transaction": {
    "transaction_lines": [
      {
        "product_class": "P",
        "product_tax_code": {
              "code":  "12341",
              "class": "ABCD"},
        "total_amount": 100, 
        ..................
      }
    ],
    "buyer_name": "Joe Test",
    "currency_code": "EUR"
  }
}
'

3. Vertex for Marketplaces passes the product tax code and class information to O Series Cloud in the following format:

"product": {
  "value": "12341",
  "productClass": "ABCD"
}

4. O Series Cloud returns the rate and other information to Vertex for Marketplaces.
5. Vertex for Marketplaces returns the tax information in the response from the Store Transaction request in the Taxes Object Fields object. Here is a snippet:

   "taxes": [
                    {
                        "tax_type": "VAT",
                        "imposition_type": "VAT",
                        "tax_jurisdiction_code": "78324",
                        "tax_amount": 15.0,
                        "tax_calculation_rule_id": "v301084387",
                        "tax_base_amount": 100,
                        "tax_jurisdiction_type": "COUNTRY",
                        "rate": 15,
                        "tax_authority_name": "NEW ZEALAND",
                        "rate_type": "Standard",
                        "tax_authority_id": "78324",
                        "tax_name": "GST",
                        "imposition": "GST",
                        "amount_fraction_taxable": 1
                    }

6. A Vertex for Marketplaces users views the Audit Report. They can view the O Series Cloud fields such as the TAIDs and imposition information.

Outbound Responses

The API responses contain a number of fields sent from and related to O Series Cloud.

O Series Cloud Tax Fields in API Responses

The following O Series Cloud fields are included in responses from the Vertex for Marketplaces API:

These are returned in the Taxes Object Fields, along with other fields.

Output Flexible Fields

If you have configured flexible fields in O Series Cloud, then these fields can be included in the responses from the API.

For example, a customer has defined flexible output fields in O Series Cloud. These fields are included in the API response. For example:

"tax_engine_additional_parameters": [
                    {
                        "param": "FLEX.output.FlexCodeEU",
                        "value": "Example Cloud EU"
                    },
                    {
                        "param": "FLEX.output.Supplier GL",
                        "value": "746464"
                    },
                    {
                        "param": "FLEX.output.Tax Code",
                        "value": "EU Code 1"
                    }
                ],

Flexible fields are returned as one of the following types:

For more information about field requirements, see Define an O Series flexible field and Type of O Series flexible fields in the Vertex Community.

Reporting (Tax Area ID (TAID) Fields)

O Series Cloud records Tax Area ID (TAID) information in each transaction to facilitate compliant reporting.

Vertex for Marketplaces records this information and passes it to O Series Cloud. The fields are only available in the Audit Report. These values are not returned in API responses.

The following table list the TAID fields: