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

ActionWhat it does
Calculate purchase taxCalculate 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 taxCalculate the tax on a sale, rental or lease as the seller.
Check a tax area for changesCheck whether one tax area changed within a date range.
Check a transaction existsCheck whether Vertex holds a transaction with this ID in its tax journal.
Delete a transactionDelete a recorded transaction from Vertex's tax journal.
Get locationGet one location set up in Vertex, with its address and tax area.
Get registrationGet one tax registration set up in Vertex.
Get taxability categoryGet one taxability category.
Get taxpayerGet one taxpayer set up in Vertex.
List changed tax areasList the IDs of tax areas that changed for any reason within a date range.
List locationsList the locations (offices, stores, warehouses) set up in Vertex.
List registrationsList the tax registrations set up in Vertex: where each taxpayer is registered to collect tax, and its registration number.
List taxability categoriesList the taxability categories (groups of goods and services taxed the same way), ordered by name.
List taxpayersList the taxpayers (your companies and filing entities) set up in Vertex, ordered by name.
Look up a jurisdiction codeFind the Vertex tax areas for a code a government authority assigned to a jurisdiction.
Look up a tax areaGet the jurisdictions and details of a Vertex tax area ID.
Look up an addressCheck and clean up a postal address and find the Vertex tax areas and jurisdictions it falls in.
Reverse a transactionCancel 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 typemessage_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 typetransaction_typetextRequired
What kind of purchase this is.One of: PURCHASE, RENTAL, LEASE.
Document datedocument_datedate
Date of the document. Vertex applies the tax rules in force on this date.
Document numberdocument_numbertext
Your invoice, order or quote number.
Transaction IDtransaction_idtext
Your own unique ID for this transaction, up to 40 characters. Needed to check, reverse or delete it later.
Currencycurrencytext
Three-letter currency code, such as `USD`. Leave empty for your Vertex default.
Companycompanytext
Your company code in Vertex, the taxpayer making the purchase.
Ship to streetship_to_streettext
Street address of the place the goods are delivered to.
Ship to cityship_to_citytext
City of the place the goods are delivered to.
Ship to stateship_to_statetext
State, province or territory of the place the goods are delivered to, as a name or postal abbreviation.
Ship to postal codeship_to_postal_codetext
Postal code of the place the goods are delivered to.
Ship to countryship_to_countrytext
Country of the place the goods are delivered to, such as `USA` or `United States`.
Ship to tax area IDship_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 codevendor_codetext
Your code for the supplier.
Ship from streetship_from_streettext
Street address of the supplier's ship-from address.
Ship from cityship_from_citytext
City of the supplier's ship-from address.
Ship from stateship_from_statetext
State, province or territory of the supplier's ship-from address, as a name or postal abbreviation.
Ship from postal codeship_from_postal_codetext
Postal code of the supplier's ship-from address.
Ship from countryship_from_countrytext
Country of the supplier's ship-from address, such as `USA` or `United States`.
Ship from tax area IDship_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 taxcharged_taxnumber
For invoice verification: the total tax the supplier charged.
Line itemsline_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 typemessage_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 typetransaction_typetextRequired
What kind of sale this is.One of: SALE, RENTAL, LEASE.
Document datedocument_datedate
Date of the document. Vertex applies the tax rules in force on this date.
Document numberdocument_numbertext
Your invoice, order or quote number.
Transaction IDtransaction_idtext
Your own unique ID for this transaction, up to 40 characters. Needed to check, reverse or delete it later.
Currencycurrencytext
Three-letter currency code, such as `USD`. Leave empty for your Vertex default.
Companycompanytext
Your company code in Vertex, the taxpayer making the sale.
Ship from streetship_from_streettext
Street address of the place the goods ship from.
Ship from cityship_from_citytext
City of the place the goods ship from.
Ship from stateship_from_statetext
State, province or territory of the place the goods ship from, as a name or postal abbreviation.
Ship from postal codeship_from_postal_codetext
Postal code of the place the goods ship from.
Ship from countryship_from_countrytext
Country of the place the goods ship from, such as `USA` or `United States`.
Ship from tax area IDship_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 codecustomer_codetext
Your code for the customer, used for exemptions set up in Vertex.
Ship to streetship_to_streettext
Street address of the customer's delivery address.
Ship to cityship_to_citytext
City of the customer's delivery address.
Ship to stateship_to_statetext
State, province or territory of the customer's delivery address, as a name or postal abbreviation.
Ship to postal codeship_to_postal_codetext
Postal code of the customer's delivery address.
Ship to countryship_to_countrytext
Country of the customer's delivery address, such as `USA` or `United States`.
Ship to tax area IDship_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 itemsline_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 IDtax_area_idtextRequired
The Vertex tax area ID to check.
Begin datebegin_datedateRequired
Look for changes from this date.
End dateend_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 IDtransaction_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 IDtransaction_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

Locationlocation_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 IDregistration_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 IDcategory_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

Taxpayertaxpayer_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 datebegin_datedateRequired
Look for changes from this date.
End dateend_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

Taxpayertaxpayer_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

Taxpayertaxpayer_idtext
Only the registrations of this taxpayer.
Registration typeregistration_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

Codecodetext
Only the category with this code.
Namenametext
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

Codecodetext
Only the taxpayer with this code.
Namenametext
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 codejurisdiction_codetextRequired
The jurisdiction code issued by the government authority.
CountrycountrytextRequired
Country the code belongs to, such as `USA`.
As of dateas_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 IDtax_area_idtextRequired
The Vertex tax area ID, such as `330612010`.
As of dateas_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

Streetstreettext
Street address, first line.
Street 2street_2text
Street address, second line.
Citycitytext
City.
Countycountytext
County.
Statestatetext
State, province or territory, as a name or postal abbreviation.
Postal codepostal_codetext
Postal code.
Countrycountrytext
Country, such as `USA` or `United States`.
As of dateas_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 IDtransaction_idtextRequired
The transaction ID you gave the calculation.
Reversal transaction IDreversal_transaction_idtext
Your own ID for the new reversing transaction, up to 40 characters.
Posting dateposting_datedate
Date to post the reversal on.
Document numberdocument_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"
    }
  }
}

On this page