Vertex
App · 18 actions
Calculate sales and use tax and VAT with Vertex O Series, look up tax areas for addresses, manage recorded transactions and read your tax setup.
Actions
| Action | What it does |
|---|---|
| Calculate purchase tax | Calculate the tax on a purchase as the buyer: estimate it for a purchase order, verify a supplier's invoice, or work out tax you owe yourself (accrual). |
| Calculate sales tax | Calculate the tax on a sale, rental or lease as the seller. |
| Check a tax area for changes | Check whether one tax area changed within a date range. |
| Check a transaction exists | Check whether Vertex holds a transaction with this ID in its tax journal. |
| Delete a transaction | Delete a recorded transaction from Vertex's tax journal. |
| Get location | Get one location set up in Vertex, with its address and tax area. |
| Get registration | Get one tax registration set up in Vertex. |
| Get taxability category | Get one taxability category. |
| Get taxpayer | Get one taxpayer set up in Vertex. |
| List changed tax areas | List the IDs of tax areas that changed for any reason within a date range. |
| List locations | List the locations (offices, stores, warehouses) set up in Vertex. |
| List registrations | List the tax registrations set up in Vertex: where each taxpayer is registered to collect tax, and its registration number. |
| List taxability categories | List the taxability categories (groups of goods and services taxed the same way), ordered by name. |
| List taxpayers | List the taxpayers (your companies and filing entities) set up in Vertex, ordered by name. |
| Look up a jurisdiction code | Find the Vertex tax areas for a code a government authority assigned to a jurisdiction. |
| Look up a tax area | Get the jurisdictions and details of a Vertex tax area ID. |
| Look up an address | Check and clean up a postal address and find the Vertex tax areas and jurisdictions it falls in. |
| Reverse a transaction | Cancel a recorded transaction by adding a second one with the amounts negated. |
Calculate purchase tax
Calculate the tax on a purchase as the buyer: estimate it for a purchase order, verify a supplier's invoice, or work out tax you owe yourself (accrual).
Inputs
- Calculation type
message_typetextRequired - Purchase order to estimate tax, invoice verification to check the tax a supplier charged, accrual to record tax you owe yourself, distribute tax to spread a known amount, or evaluated receipts settlement when you pay the supplier's tax yourself.One of:
PURCHASE_ORDER(Purchase order),INVOICE_VERIFICATION(Invoice verification),ACCRUAL,DISTRIBUTE_TAX(Distribute tax),ERS(Evaluated receipts settlement). - Transaction type
transaction_typetextRequired - What kind of purchase this is.One of:
PURCHASE,RENTAL,LEASE. - Document date
document_datedate - Date of the document. Vertex applies the tax rules in force on this date.
- Document number
document_numbertext - Your invoice, order or quote number.
- Transaction ID
transaction_idtext - Your own unique ID for this transaction, up to 40 characters. Needed to check, reverse or delete it later.
- Currency
currencytext - Three-letter currency code, such as `USD`. Leave empty for your Vertex default.
- Company
companytext - Your company code in Vertex, the taxpayer making the purchase.
- Ship to street
ship_to_streettext - Street address of the place the goods are delivered to.
- Ship to city
ship_to_citytext - City of the place the goods are delivered to.
- Ship to state
ship_to_statetext - State, province or territory of the place the goods are delivered to, as a name or postal abbreviation.
- Ship to postal code
ship_to_postal_codetext - Postal code of the place the goods are delivered to.
- Ship to country
ship_to_countrytext - Country of the place the goods are delivered to, such as `USA` or `United States`.
- Ship to tax area ID
ship_to_tax_area_idtext - Vertex tax area ID of the place the goods are delivered to, if you already know it. Vertex uses it instead of the address.
- Vendor code
vendor_codetext - Your code for the supplier.
- Ship from street
ship_from_streettext - Street address of the supplier's ship-from address.
- Ship from city
ship_from_citytext - City of the supplier's ship-from address.
- Ship from state
ship_from_statetext - State, province or territory of the supplier's ship-from address, as a name or postal abbreviation.
- Ship from postal code
ship_from_postal_codetext - Postal code of the supplier's ship-from address.
- Ship from country
ship_from_countrytext - Country of the supplier's ship-from address, such as `USA` or `United States`.
- Ship from tax area ID
ship_from_tax_area_idtext - Vertex tax area ID of the supplier's ship-from address, if you already know it. Vertex uses it instead of the address.
- Charged tax
charged_taxnumber - For invoice verification: the total tax the supplier charged.
- Line items
line_itemslistRequired - The lines to calculate tax on. Each needs a line total or a unit price.
Outputs
dataobject- The response from Vertex.
Example output
{
"data": {
"data": {
"currency": {
"isoCurrencyCodeAlpha": "example"
},
"documentDate": "example",
"documentNumber": "example",
"lineItems": [
{}
],
"subTotal": 1,
"total": 1,
"totalTax": 1,
"transactionId": "example",
"transactionType": "example"
},
"meta": {
"app": "example",
"timeReceived": "example"
}
}
}Calculate sales tax
Calculate the tax on a sale, rental or lease as the seller. A quotation is an estimate Vertex doesn't keep; an invoice is recorded in Vertex's tax journal for reporting and filing.
Inputs
- Calculation type
message_typetextRequired - Quotation to estimate tax, invoice to record it for reporting, or distribute tax to spread a known tax amount across jurisdictions.One of:
QUOTATION,INVOICE,DISTRIBUTE_TAX(Distribute tax). - Transaction type
transaction_typetextRequired - What kind of sale this is.One of:
SALE,RENTAL,LEASE. - Document date
document_datedate - Date of the document. Vertex applies the tax rules in force on this date.
- Document number
document_numbertext - Your invoice, order or quote number.
- Transaction ID
transaction_idtext - Your own unique ID for this transaction, up to 40 characters. Needed to check, reverse or delete it later.
- Currency
currencytext - Three-letter currency code, such as `USD`. Leave empty for your Vertex default.
- Company
companytext - Your company code in Vertex, the taxpayer making the sale.
- Ship from street
ship_from_streettext - Street address of the place the goods ship from.
- Ship from city
ship_from_citytext - City of the place the goods ship from.
- Ship from state
ship_from_statetext - State, province or territory of the place the goods ship from, as a name or postal abbreviation.
- Ship from postal code
ship_from_postal_codetext - Postal code of the place the goods ship from.
- Ship from country
ship_from_countrytext - Country of the place the goods ship from, such as `USA` or `United States`.
- Ship from tax area ID
ship_from_tax_area_idtext - Vertex tax area ID of the place the goods ship from, if you already know it. Vertex uses it instead of the address.
- Customer code
customer_codetext - Your code for the customer, used for exemptions set up in Vertex.
- Ship to street
ship_to_streettext - Street address of the customer's delivery address.
- Ship to city
ship_to_citytext - City of the customer's delivery address.
- Ship to state
ship_to_statetext - State, province or territory of the customer's delivery address, as a name or postal abbreviation.
- Ship to postal code
ship_to_postal_codetext - Postal code of the customer's delivery address.
- Ship to country
ship_to_countrytext - Country of the customer's delivery address, such as `USA` or `United States`.
- Ship to tax area ID
ship_to_tax_area_idtext - Vertex tax area ID of the customer's delivery address, if you already know it. Vertex uses it instead of the address.
- Line items
line_itemslistRequired - The lines to calculate tax on. Each needs a line total or a unit price.
Outputs
dataobject- The response from Vertex.
Example output
{
"data": {
"data": {
"currency": {
"isoCurrencyCodeAlpha": "example"
},
"documentDate": "example",
"documentNumber": "example",
"lineItems": [
{}
],
"subTotal": 1,
"total": 1,
"totalTax": 1,
"transactionId": "example",
"transactionType": "example"
},
"meta": {
"app": "example",
"timeReceived": "example"
}
}
}Check a tax area for changes
Check whether one tax area changed within a date range. Not available when your calculations run on Microsoft Azure.
Inputs
- Tax area ID
tax_area_idtextRequired - The Vertex tax area ID to check.
- Begin date
begin_datedateRequired - Look for changes from this date.
- End date
end_datedate - Look for changes up to this date.
Outputs
dataobject- The response from Vertex.
Example output
{
"data": {
"changed": true,
"tax_area_id": "example"
}
}Check a transaction exists
Check whether Vertex holds a transaction with this ID in its tax journal.
Inputs
- Transaction ID
transaction_idtextRequired - The transaction ID you gave the calculation.
Outputs
dataobject- The response from Vertex.
Example output
{
"data": {
"meta": {
"app": "example",
"timeReceived": "example"
},
"transactionExistsIndicator": "example",
"transactionId": "example"
}
}Delete a transaction
Delete a recorded transaction from Vertex's tax journal. Vertex Cloud accepts this within 90 days of the calculation.
Inputs
- Transaction ID
transaction_idtextRequired - The transaction ID you gave the calculation.
Outputs
dataobject- The response from Vertex.
Example output
{
"data": {
"meta": {
"app": "example",
"timeReceived": "example"
},
"transactionId": "example"
}
}Get location
Get one location set up in Vertex, with its address and tax area.
Inputs
- Location
location_idtextRequired - The location.
Outputs
dataobject- The response from Vertex.
Example output
{
"data": {
"endDate": "example",
"id": "example",
"locationCode": "example",
"name": "example",
"owningPartyId": "example",
"postalAddress": {
"city": "example",
"country": "example",
"mainDivision": "example",
"postalCode": "example",
"streetAddress1": "example",
"streetAddress2": "example",
"subDivision": "example"
},
"registrationCode": "example",
"startDate": "example",
"taxAreaId": "example"
}
}Get registration
Get one tax registration set up in Vertex.
Inputs
- Registration ID
registration_idtextRequired - The registration ID. Find it with List registrations.
Outputs
dataobject- The response from Vertex.
Example output
{
"data": {
"endDate": "example",
"filingCurrencyIsoCode": "example",
"id": "example",
"owningPartyId": "example",
"owningPartyType": "example",
"physicalPresence": true,
"registeredJurisdiction": {
"endDate": "example",
"level": "example",
"name": "example",
"parentCountry": "example",
"parentMainDivision": "example",
"startDate": "example",
"type": "example",
"vertexJurisdictionId": 1
},
"registrationNumber": "example",
"registrationType": "example",
"startDate": "example"
}
}Get taxability category
Get one taxability category.
Inputs
- Category ID
category_idtextRequired - The taxability category ID. Find it with List taxability categories.
Outputs
dataobject- The response from Vertex.
Example output
{
"data": {
"code": "example",
"description": "example",
"endDate": "example",
"id": "example",
"name": "example",
"parentCategoryId": "example",
"startDate": "example",
"userDefined": true
}
}Get taxpayer
Get one taxpayer set up in Vertex.
Inputs
- Taxpayer
taxpayer_idtextRequired - The taxpayer.
Outputs
dataobject- The response from Vertex.
Example output
{
"data": {
"adoptParentSetup": true,
"code": "example",
"endDate": "example",
"filingEntity": true,
"id": "example",
"name": "example",
"note": "example",
"parentTaxpayerId": "example",
"partyTypeId": 1,
"shippingTerms": "example",
"startDate": "example"
}
}List changed tax areas
List the IDs of tax areas that changed for any reason within a date range. Not available when your calculations run on Microsoft Azure.
Inputs
- Begin date
begin_datedateRequired - Look for changes from this date.
- End date
end_datedate - Look for changes up to this date.
Outputs
dataobject- The response from Vertex.
Example output
{
"data": {
"data": [
"example"
],
"meta": {
"app": "example",
"timeReceived": "example"
}
}
}List locations
List the locations (offices, stores, warehouses) set up in Vertex.
Inputs
- Taxpayer
taxpayer_idtext - Only the locations of this taxpayer.
Outputs
dataobject- The response from Vertex.
Example output
{
"data": {
"count": 1,
"locations": [
{
"endDate": "example",
"id": "example",
"locationCode": "example",
"name": "example",
"owningPartyId": "example",
"postalAddress": {
"city": "example",
"country": "example",
"mainDivision": "example",
"postalCode": "example",
"streetAddress1": "example",
"streetAddress2": "example",
"subDivision": "example"
},
"registrationCode": "example",
"startDate": "example",
"taxAreaId": "example"
}
],
"truncated": true
}
}List registrations
List the tax registrations set up in Vertex: where each taxpayer is registered to collect tax, and its registration number.
Inputs
- Taxpayer
taxpayer_idtext - Only the registrations of this taxpayer.
- Registration type
registration_typetext - Only registrations of this type, such as `VAT_REGISTRATION`.
Outputs
dataobject- The response from Vertex.
Example output
{
"data": {
"count": 1,
"registrations": [
{
"endDate": "example",
"filingCurrencyIsoCode": "example",
"id": "example",
"owningPartyId": "example",
"owningPartyType": "example",
"physicalPresence": true,
"registeredJurisdiction": {
"endDate": "example",
"level": "example",
"name": "example",
"parentCountry": "example",
"parentMainDivision": "example",
"startDate": "example",
"type": "example",
"vertexJurisdictionId": 1
},
"registrationNumber": "example",
"registrationType": "example",
"startDate": "example"
}
],
"truncated": true
}
}List taxability categories
List the taxability categories (groups of goods and services taxed the same way), ordered by name. Filter by code or name: Vertex supplies thousands.
Inputs
- Code
codetext - Only the category with this code.
- Name
nametext - Only the category with this exact name.
Outputs
dataobject- The response from Vertex.
Example output
{
"data": {
"categories": [
{
"code": "example",
"description": "example",
"endDate": "example",
"id": "example",
"name": "example",
"parentCategoryId": "example",
"startDate": "example",
"userDefined": true
}
],
"count": 1,
"truncated": true
}
}List taxpayers
List the taxpayers (your companies and filing entities) set up in Vertex, ordered by name.
Inputs
- Code
codetext - Only the taxpayer with this code.
- Name
nametext - Only the taxpayer with this exact name.
Outputs
dataobject- The response from Vertex.
Example output
{
"data": {
"count": 1,
"taxpayers": [
{
"adoptParentSetup": true,
"code": "example",
"endDate": "example",
"filingEntity": true,
"id": "example",
"name": "example",
"note": "example",
"parentTaxpayerId": "example",
"partyTypeId": 1,
"shippingTerms": "example",
"startDate": "example"
}
],
"truncated": true
}
}Look up a jurisdiction code
Find the Vertex tax areas for a code a government authority assigned to a jurisdiction.
Inputs
- Jurisdiction code
jurisdiction_codetextRequired - The jurisdiction code issued by the government authority.
- Country
countrytextRequired - Country the code belongs to, such as `USA`.
- As of date
as_of_datedate - Look up the tax areas in force on this date.
Outputs
dataobject- The response from Vertex.
Example output
{
"data": {
"data": {
"lookupResults": [
{
"addressCleansingResultMessages": [
{}
],
"asOfDate": "example",
"confidenceIndicator": "example",
"jurisdictions": [
{
"effectiveDate": "example",
"expirationDate": "example",
"externalJurisdictionCode": "example",
"jurisdictionId": "example",
"jurisdictionType": "example",
"value": "example"
}
],
"postalAddresses": [
{
"city": "example",
"country": "example",
"mainDivision": "example",
"postalCode": "example",
"streetAddress1": "example",
"streetAddress2": "example",
"subDivision": "example"
}
],
"statuses": [
{}
],
"taxAreaId": "example"
}
]
},
"meta": {
"app": "example",
"timeReceived": "example"
}
}
}Look up a tax area
Get the jurisdictions and details of a Vertex tax area ID.
Inputs
- Tax area ID
tax_area_idtextRequired - The Vertex tax area ID, such as `330612010`.
- As of date
as_of_datedate - Look up the tax areas in force on this date.
Outputs
dataobject- The response from Vertex.
Example output
{
"data": {
"data": {
"lookupResults": [
{
"addressCleansingResultMessages": [
{}
],
"asOfDate": "example",
"confidenceIndicator": "example",
"jurisdictions": [
{
"effectiveDate": "example",
"expirationDate": "example",
"externalJurisdictionCode": "example",
"jurisdictionId": "example",
"jurisdictionType": "example",
"value": "example"
}
],
"postalAddresses": [
{
"city": "example",
"country": "example",
"mainDivision": "example",
"postalCode": "example",
"streetAddress1": "example",
"streetAddress2": "example",
"subDivision": "example"
}
],
"statuses": [
{}
],
"taxAreaId": "example"
}
]
},
"meta": {
"app": "example",
"timeReceived": "example"
}
}
}Look up an address
Check and clean up a postal address and find the Vertex tax areas and jurisdictions it falls in.
Inputs
- Street
streettext - Street address, first line.
- Street 2
street_2text - Street address, second line.
- City
citytext - City.
- County
countytext - County.
- State
statetext - State, province or territory, as a name or postal abbreviation.
- Postal code
postal_codetext - Postal code.
- Country
countrytext - Country, such as `USA` or `United States`.
- As of date
as_of_datedate - Look up the tax areas in force on this date.
Outputs
dataobject- The response from Vertex.
Example output
{
"data": {
"data": {
"lookupResults": [
{
"addressCleansingResultMessages": [
{}
],
"asOfDate": "example",
"confidenceIndicator": "example",
"jurisdictions": [
{
"effectiveDate": "example",
"expirationDate": "example",
"externalJurisdictionCode": "example",
"jurisdictionId": "example",
"jurisdictionType": "example",
"value": "example"
}
],
"postalAddresses": [
{
"city": "example",
"country": "example",
"mainDivision": "example",
"postalCode": "example",
"streetAddress1": "example",
"streetAddress2": "example",
"subDivision": "example"
}
],
"statuses": [
{}
],
"taxAreaId": "example"
}
]
},
"meta": {
"app": "example",
"timeReceived": "example"
}
}
}Reverse a transaction
Cancel a recorded transaction by adding a second one with the amounts negated. Vertex Cloud accepts this within 90 days of the calculation.
Inputs
- Transaction ID
transaction_idtextRequired - The transaction ID you gave the calculation.
- Reversal transaction ID
reversal_transaction_idtext - Your own ID for the new reversing transaction, up to 40 characters.
- Posting date
posting_datedate - Date to post the reversal on.
- Document number
document_numbertext - Document number for the reversal, such as a credit note number.
Outputs
dataobject- The response from Vertex.
Example output
{
"data": {
"data": {
"documentNumber": "example",
"postingDate": "example",
"transactionId": "example"
},
"meta": {
"app": "example",
"timeReceived": "example"
}
}
}