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

Your instance is configured during the implementation project.

OSC 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 OSC documentation in Vertex Community. You need a Vertex Community user to view these topics.

Prerequisites

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

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

Integration Points

How OSC 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 OSC. See Use Tax Setup in O Series to define your unique taxability in Vertex Community.
• OSC Fields: Commonly used OSC fields like tax_type, imposition, and imposition_type are returned in responses.
• Flexible Output Fields: If you configure Flexible Output Fields in OSC, 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: OSC 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 OSC settings). See the Overview section of Address Cleansing topic in Vertex Community.

Inbound Requests

You can use specific fields to send certain information to OSC 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 OSC. 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 OSC for a good. You define a Product Tax Code 12341 and a Product Tax Class of ABCD in OSC 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 OSC 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 OSC in the following format:

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

4. OSC 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 OSC fields such as the TAIDs and imposition information.

Outbound Responses

The API responses contain a number of fields sent from and related to OSC.

OSC Tax Fields in API Responses

The following OSC 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 OSC, then these fields can be included in the responses from the API.

For example, a customer has defined flexible output fields in OSC. 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)

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

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

The following table list the TAID fields: