Get Started with Tax Configuration
Learn about integrating your host system with the O Series Tax Configuration API.
About the O Series Tax Configuration API
Tax in Vertex® O Series is configured by creating and maintaining business entities that impact transaction taxation. In the O Series platform, this configuration takes place in the My Enterprise suite of features. The O Series Tax Configuration API contains requests that create, update, delete, and otherwise manage these business entities to customize tax results for a specific organization.
Use the API to:
- Create or update taxpayers, retrieve all taxpayers, or retrieve taxpayers by ID.
- Create, update, or delete taxability drivers, or retrieve taxability drivers by code or by ID.
- Retrieve taxability categories by name or by ID.
- Create or delete taxability mappings, or retrieve mappings by category or by ID.
- Create, update, or delete locations, or retrieve locations by owning party or by ID.
- Create, update, or delete registrations, or retrieve registrations by owning party or by ID.
- Retrieve Commodity Codes by type or by code.
Tax Configuration OAS file
See OAS - Tax Configuration API to download the OpenAPI Specification (OAS) file for the Tax Configuration API.
About taxpayers
Taxpayers, and how you choose to set them up, reflect your organization's structure and filing entity structure. They also identify the jurisdictions in which you are registered to collect and remit tax.
Entering complete taxpayer information enables O Series to more precisely determine the tax jurisdictions and tax amounts for your transactions. The taxpayer setups are shared across Supplies and Procurement business events.
For details on configuring taxpayers, see Set up your organization’s taxpayers in O Series on Vertex Community.
About taxability drivers
Taxability drivers represent the core parts of your business that drive taxability – mostly the products and services that you sell and purchase. They can also represent other factors that affect a tax outcome, such as the usage of a product or the payment type on a lease transaction.
However, taxability drivers alone do not mean anything for tax calculation in Vertex® O Series. You must map each driver to a taxability category so that O Series knows what tax rules and tax rates to use when calculating tax.
For details on configuring taxability drivers, see Set up your taxability drivers in O Series on Vertex Community.
About taxability categories
A key to applying the proper tax in O Series is mapping your products, services, and other conditions to the appropriate taxability categories. Taxability categories in O Series are groups of similar goods or services that have similar taxability and may have conditional rules.
Vertex Tax Research supplies a great number of taxability categories for which it maintains current rules and rates. The up-to-date taxability categories are provided in the monthly data update file. If the Vertex-supplied categories are not sufficient for your tax situation, you can create user-defined taxability categories.
For details on configuring taxability categories, see Taxability categories are the key to O Series rates and rules on Vertex Community.
About taxability mappings
For each product and service that your taxpayer produces or purchases, you need to let O Series know which taxability category applies the appropriate taxation by mapping the entity to a taxability category.
In the Taxability Mapping feature, you can map a single entity – such as a taxability driver, taxpayer, customer, vendor, or code flexible field – to a taxability category. The most commonly used entity when mapping to a taxability category is a taxability driver.
For details on configuring taxability mappings, see Map O Series entities to taxability categories on Vertex Community.
About Locations
Whether a taxpayer, customer, or vendor has a corporate office, retail stores, warehouses, or other facilities may be important to calculating and reporting tax accurately in O Series.
In general, physical locations don’t impact taxation. However, in some jurisdictions, physical location determines whether tax is charged and the appropriate tax type. You may only need to set up locations if there's an impact on situs or place of supply, if it's required for reporting, or if you're using an O Series retail solution.
For details on configuring locations, see these articles on Vertex Community:
- Enter taxpayer locations in O Series
- Enter customer locations in O Series
- Enter vendor locations in O Series
About registrations
O Series tracks tax registration details for taxpayers, customers, and vendors. Registrations impact tax calculation and reporting in multiple ways:
- If a taxpayer is a filing entity, you’ll need to identify the jurisdictions where the taxpayer has nexus and is registered to file taxes
- Customer and Vendor registrations matter for both U.S. indirect tax and global value added tax (VAT).
You can pass customer or vendor registration details in a Calculate Tax request or add them in to your O Series configuration. Keep in mind that O Series gives precedence to the information in the Calculate Tax request over the information in a customer or vendor record when calculating tax.
For details on configuring registrations, see these articles on Vertex Community:
- Set up taxpayer registrations in O Series
- Set up customer registrations in O Series
- Set up vendor registrations in O Series
About commodity codes
The United Nations Standard Products and Services Code (UNSPSC) classification system is a global electronic commerce standard that provides a hierarchical framework for classifying goods and services.
O Series includes the UNSPSC codes that correspond to the taxability categories that are available in Vertex-supplied data, but you may have tax situations for which Vertex-supplied commodity codes do not provide the appropriate taxation. If this is the case, you may want to create user-defined Commodity Codes.
For details on commodity codes, see UNSPSC commodity codes in O Series on Vertex Community.
URL for accessing Tax Configuration API endpoints
The server URL pattern for accessing the Tax Configuration RESTful API endpoints is in the following format:
<server:port>/tax-config-api/config/<version>/<endpoint>
where:
<server:port>identifies your network address.tax-config-api/configdesignates the Vertex O Series Configuration web service APIs.<version>is the version of the API.<endpoint>is the target of the interaction.
For example:
<https://example.server.com:8095/tax-config-api/config/v2/taxability-catagories>
Tax Configuration API endpoints
There are Tax Configuration endpoints for each of the seven types of requests that can be submitted via the API: Category, Commodity Code, Driver, Location, Mapping, Registration, and Taxpayer.
Category configuration endpoints
| Version | Endpoint | Description |
|---|---|---|
/v2 | /taxability-categories | GET - Returns a list of taxability categories ordered by name. You can filter by code and name using the eq operator. |
/v2 | /taxability-categories/{id} | GET - Retrieves a category by id. |
/v2 | /taxability-categories/{id}/hierarchy | GET - Returns a list of the requested taxability category and all its descendants, using pre-order tree traversal. |
Commodity code configuration endpoints
| Version | Endpoint | Description |
|---|---|---|
/v2 | commodity-codes | GET - Returns a list of supported commodity code types.. |
/v2 | /commodity-codes/{type} | GET - Retrieves a category by id. |
/v2 | /commodity-codes/{type}/{codevalue} | GET - Returns commodity code mapping information for a commodity code. |
Driver configuration endpoints
| Version | Endpoint | Description |
|---|---|---|
/v2 | /taxability-drivers | POST - Create a taxability driver. |
/v2 | /taxability-drivers | GET - Returns a list of taxability drivers ordered by code. You can filter by code, name and owningTaxpayerId using the eq operator. |
/v2 | /taxability-drivers/{id} | GET - Retrieve a taxability driver by id. PUT - Update a taxability driver. DELETE - Delete a taxability driver. |
Location configuration endpoints
| Version | Endpoint | Description |
|---|---|---|
/v2 | /locations | POST - Create a taxability driver. GET - Returns a list of taxability drivers ordered by code. You can filter by code, name and owningTaxpayerId using the eq operator. |
/v2 | /locations/{id} | GET - Retrieve a taxability driver by id. PUT - Update a taxability driver. DELETE - Delete a taxability driver. |
Mapping configuration endpoints
| Version | Endpoint | Description |
|---|---|---|
/v2 | /taxability-mappings | POST - Create a taxability mapping. GET - Returns a list of taxability mappings ordered by taxability category id. You can filter by categoryId and driverId using the eq operator. |
/v2 | /taxability-mappings/{id} | GET - Retrieve a mapping by id. DELETE - Delete a mapping by id. |
Registration configuration endpoints
| Version | Endpoint | Description |
|---|---|---|
/v2 | /registrations | POST - Create one or more registrations. GET - Returns a list of registrations ordered by owningPartyId. You can filter by owningPartyId and registrationType using the eq operator. |
/v2 | /registrations/{id} | GET - Retrieve a registration by id. PUT - Update a registration configuration by id. All elements are replaced. DELETE - Delete a registration by id. |
Taxpayer configuration endpoints
| Version | Endpoint | Description |
|---|---|---|
/v2 | /taxpayers | POST - Create a taxpayer. GET - Returns a list of taxpayers ordered by name. You can filter by code and name using the eq operator. |
/v2 | /taxpayers/{id} | GET - Retrieve a taxpayer by id. PUT - Update a taxpayer by id. |
Updated about 1 month ago