Vertex O Series Cloud Integration
Vertex O Series Cloud is the engine for tax rate calculation.
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
orproduct_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
, andimposition_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
orproduct_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.
Field | Description |
---|---|
product_tax_code.code | This is the code that is defined in O Series Cloud and is used to identify the product. |
product_tax_code.class | This is the class that is defined in O Series Cloud and is used to classify the product. |
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:

OSC Processing Example
The steps are:
- The Buyer places the goods in their basket and they click Pay.
- 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"
}
}
'
- Vertex for Marketplaces passes the product tax code and class information to O Series Cloud in the following format:
"product": {
"value": "12341",
"productClass": "ABCD"
}
- O Series Cloud returns the rate and other information to Vertex for Marketplaces.
- 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
}
- 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:
OSC Field | Description |
---|---|
taxable_amount | This values specifies the amount of a transaction that is deemed taxable by O Series Cloud. |
nontaxable_amount | This values specifies the amount of a transaction that is deemed non-taxable by O Series Cloud. |
tax_type | This value specifies the type of tax as it is defined in O Series Cloud. |
exempt_amount | This values specifies the amount of a transaction that is deemed as exempt from tax by O Series Cloud. |
imposition | This value specifies the imposition that is defined in O Series Cloud. |
imposition_type | This value specifies the imposition type that is defined in O Series Cloud. |
tax_calculation_rule_id | An identifier for the O Series Cloud Tax Calculation Rule ID that corresponds to the tax that was applied to the transaction. If this value starts with a u , this means that a user-defined rule was applied. This field may not be returned for exemptions. |
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:
Field | Description | Numeric Range |
---|---|---|
flexibleCodeFields | Returns fields with strings. | 1 to 25 |
flexibleDateFields | Returns date fields. | 1 to 5 |
flexibleNumericFields | Returns numeric fields. | 1 to 10 |
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:
Field | Description |
---|---|
Admin Destination Tax Area ID | This value specifies the type of tax as it is defined in O Series Cloud. |
Admin Origin Tax Area ID | This value specifies the imposition that is defined in O Series Cloud. |
Destination Tax Area ID | This value specifies the imposition type that is defined in O Series Cloud. |
Physical Origin Tax Area ID | An identifier for the O Series Cloud Tax Calculation Rule ID that corresponds to the tax that was applied to the transaction. If this value starts with a u, this means that a user-defined rule was applied. This field may not be returned for exemptions. |
Updated 7 days ago