Resources


Technical Overview

REST is a data architecture and design methodology that produces consistent, predictable outputs and behaviors. This is achieved by using the HTTP/HTTPS transport protocol and standard methods, called verbs. 

An API comprises a set of dedicated URLs that return standardized data in the JSON messaging format, referred to here as the resource . An API uses standard HTTPS features and verbs to communicate data between the server and application without having to render the presentation overhead of the graphical user interface on the client. 

A call includes the following elements:

  • An HTTPS header that contains authentication information and other relevant instructions.
  • A verb such as GET, PUT, POST, PATCH, or DELETE.
  • A Uniform Resource Indicator (URI) endpoint that identifies the server, web service, and resource.
  • The input parameters and attributes supplied with the request, known as the call payload.

A response payload is returned with an HTTPS status code.

Once you get an API key, you can communicate securely from your web application with the API. All API responses are returned in JSON, and then converted to language-specific objects.

The URI that is used to communicate with Vertex Cloud depends on the type of call that you are making:


Buyer Transactions

These transactions calculate tax from the buyer’s perspective. The value of the PurchaseMessageType property determines how tax is calculated and whether the tax calculation is stored for reporting and tax remittance.

The following message types apply to buyer transactions:

Message Type Description
PurchaseOrder  This message type estimates the tax on intended purchases for a buyer. The purchase amount, including tax, is used as input to generate the purchase order. The ultimate use of the goods or services typically dictates the taxability of the purchase. PurchaseOrder transactions are not stored for reporting or remittance.
Accrual This message type initiates a self-accrual calculation. This situation occurs when the buyer must remit tax on tangible personal property or services (used or consumed) when tax on the transaction has not been paid. Accrual transactions are stored for reporting and remittance.
InvoiceVerification  This message type verifies tax on incoming invoices to the buyer for tangible personal property, rentals, and leases. The invoice is recreated from the seller’s perspective to validate that the proper tax was applied. The total vendor-charged or supplier-charged tax amount from the original invoice is compared with the Vertex-calculated tax amount. If any user-defined verification thresholds are set up, the tax engine validates for tolerances at the transaction level and returns an indicator to the host system for undercharges and overcharges outside the threshold limits. The invoice might display no tax if the buyer filed a direct pay permit with the vendor or supplier. InvoiceVerification transactions are not stored for reporting and remittance.
DistributeTax This message type accepts a combined total tax amount for a purchase and distributes the tax amount to the appropriate jurisdictions. The tax engine uses the total tax amount with the combined rates for the taxing jurisdictions to determine the taxable base, and then redistributes the calculated taxes to each jurisdiction. This message type is used for a tax-only adjustment (debit or credit) to reconcile a tax underpayment or overpayment.

The tax engine uses Vertex taxability rules that are effective on the date specified in the documentDate attribute. The tax engine processes records for jurisdiction registration, product exemption, or customer exemption if they are dated on or before that date.

This transaction impacts revenue unless you designate it as a tax-only adjustment. DistributeTax transactions are stored for reporting.


Seller Transactions

These transactions calculate tax from the seller’s perspective. The value of the SaleMessageType property determines how tax is calculated and whether the tax calculation is stored for reporting and tax remittance.

The following message types apply to seller transactions:

Message Type Description
Quotation This message type estimates tax on a proposed sale or rental by the seller. Because it is an estimate, a quotation is subject to change until the transaction is finalized. Quotation transactions are not stored for reporting or remittance.
Invoice This message type initiates tax calculation on a transaction. Tax is calculated at the time of shipping, billing, or invoicing from the seller’s perspective. Invoice transactions are stored for reporting and remittance.
DistributeTax This message type accepts a combined total tax amount for a purchase and distributes the tax amount to the appropriate jurisdictions. The tax engine uses the total tax amount with the combined rates for the taxing jurisdictions to determine the taxable base, and then redistributes the calculated taxes to each jurisdiction for remittance. This message type is used for a tax-only adjustment (debit or credit) to reconcile a tax underpayment or overpayment. This transaction might impact revenue. DistributeTax transactions are stored for reporting and remittance.

Seller Transaction Features

Freight

Freight can be managed in three different ways, each with its own benefits and drawbacks. The way freight is implemented depends on the capabilities of the host system.

Apply a Freight Amount Field per Line Item

This method applies a freight amount to each line item and calculates the freight tax for each item individually. This method is the simplest way to manage freight within Vertex Cloud and is one of the most common means of managing freight within host systems. 

Apply a Freight Element

This field sets the freight charge associated with the line item. Note that the preferred method for dealing with freight is to create a separate line item with an item type mapped to one of the Vertex-provided item categories. However, this method calculates tax for the default Freight Item category and rolls it into this line item.

Create a Child Line Item for Freight Charges for Each Order Line Item

With this method, a child line item is created for the appropriately apportioned freight charges for each line. This is the most elegant approach to freight management, because freight can be distributed with finely tuned freight rules to each line item. The customer can control which items are applicable and non-applicable for freight (product vs service), avoiding issues with automatic apportionment. This, however, is the most difficult solution to implement because it requires more functionality within the host system.

Discounts

If there is a discount amount, the extended price should be the net price (minus the discount amount), not the gross price. Then populate discount appropriately. For example, a customer buys shoes that are priced at $100 and sold for $90. The extended price should be $90, considering the $10 discount. This discount field should be marked as $10.

This approach ensures that the order is taxed as a $100 order, even though the customer is only paying $90. This is an important differentiator. If the extended price is marked as $100, and the discount is marked as $10, the order will be taxed as if it were a $110 order.

It is important to know whether the host system can categorize discounts. For example, manufacturer discounts are taxed differently than promotional discounts.

If Discount is passed, you must include the user-defined discount code, if mapped, and either Discount Percent or Discount Amount. Extended price always reflects the discount.

NOTE: Most host systems deduct the discount amount from the extended price.


Configuration Components

The following components can be configured in Vertex Cloud. This data is present in the test environment.

Configuration Component Description
Taxpayer (Company) A taxpayer is an entity in your organization that collects and remits tax on transactions. Taxpayers define your organization’s structure, filing entity structure, and the jurisdictions in which you are registered to remit tax. A taxpayer can be a single entity or can exist in a hierarchy with a maximum of three levels.
Location A location is a geographical place where the taxpayer has a physical presence within a jurisdiction. In general, physical locations do not have an impact on taxation. However, in some jurisdictions, physical locations determine whether tax is charged and the appropriate tax type.
Customer Exemption A customer exemption is a customer who has non-standard taxability. A customer exemption must be set up before you can create user-defined tax rules and associate these rules to the customer.
Taxability Mapping A taxability mapping is a record that maps a taxability driver (such as a product code, usage code, or cost center) to the appropriate taxability category in the taxability mapping hierarchy. The taxability category defines the tax rates and tax rules that Vertex Cloud uses to calculate tax for the taxability driver.

Registered Jurisdiction

A registered jurisdiction is a state or local authority where the taxpayer is registered to collect and remit tax on transactions.  When you define a taxpayer as a filing entity, you define the jurisdictions in which the taxpayer is registered to collect tax. This includes states, counties, school districts within the US, provinces in Canada, and other countries around the globe where VAT, GST, and HST require registration IDs.
Discount Code A discount code is used by your host system and mapped to a Vertex-supplied discount category.
Custom Category A taxability category is a group of similar goods or services that have similar taxability and may have special or conditional rules. Users can create custom categories if the Vertex-supplied categories do not fit the special rules.
Tax Assist Rule A pre-calculation Tax Assist rule provides data to the tax engine for tax calculation when such data cannot be passed directly from your host system or cannot be used as-is. A post-calculation Tax Assist rule allows you to append additional information to a calculated tax before that tax is posted to the Tax Journal or passed back to your host system.
Tax Assist Lookup Table A Tax Assist lookup table contains lookup values that can be used to look up a single value for use as an input field in a Tax Assist rule when corresponding pieces of data, or parameters, are present in a transaction that is passed from your host system.
Tax Assist Allocation Table A Tax Assist allocation table allows you to create multiple line items from a single line item that is passed from your host system. The table specifies how the created line items should differ from the original line item.
Flex Field A flex field accepts specific data that is passed from the host system and then used to make complex taxability decisions and to report data that is not normally reported in Vertex Cloud.