# Vertex

> 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.

App · 18 actions. Web page: https://docs.lodol.com/docs/integrations/vertex

## Actions

### 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_type`, text, required): 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_type`, text, required): What kind of purchase this is. One of: `PURCHASE`, `RENTAL`, `LEASE`.
- Document date (`document_date`, date): Date of the document. Vertex applies the tax rules in force on this date.
- Document number (`document_number`, text): Your invoice, order or quote number.
- Transaction ID (`transaction_id`, text): Your own unique ID for this transaction, up to 40 characters. Needed to check, reverse or delete it later.
- Currency (`currency`, text): Three-letter currency code, such as `USD`. Leave empty for your Vertex default.
- Company (`company`, text): Your company code in Vertex, the taxpayer making the purchase.
- Ship to street (`ship_to_street`, text): Street address of the place the goods are delivered to.
- Ship to city (`ship_to_city`, text): City of the place the goods are delivered to.
- Ship to state (`ship_to_state`, text): 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_code`, text): Postal code of the place the goods are delivered to.
- Ship to country (`ship_to_country`, text): Country of the place the goods are delivered to, such as `USA` or `United States`.
- Ship to tax area ID (`ship_to_tax_area_id`, text): 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_code`, text): Your code for the supplier.
- Ship from street (`ship_from_street`, text): Street address of the supplier's ship-from address.
- Ship from city (`ship_from_city`, text): City of the supplier's ship-from address.
- Ship from state (`ship_from_state`, text): State, province or territory of the supplier's ship-from address, as a name or postal abbreviation.
- Ship from postal code (`ship_from_postal_code`, text): Postal code of the supplier's ship-from address.
- Ship from country (`ship_from_country`, text): Country of the supplier's ship-from address, such as `USA` or `United States`.
- Ship from tax area ID (`ship_from_tax_area_id`, text): 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_tax`, number): For invoice verification: the total tax the supplier charged.
- Line items (`line_items`, list, required): The lines to calculate tax on. Each needs a line total or a unit price.

**Outputs**

- `data` (object): The response from Vertex.

**Example output**

```json
{
  "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_type`, text, required): 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_type`, text, required): What kind of sale this is. One of: `SALE`, `RENTAL`, `LEASE`.
- Document date (`document_date`, date): Date of the document. Vertex applies the tax rules in force on this date.
- Document number (`document_number`, text): Your invoice, order or quote number.
- Transaction ID (`transaction_id`, text): Your own unique ID for this transaction, up to 40 characters. Needed to check, reverse or delete it later.
- Currency (`currency`, text): Three-letter currency code, such as `USD`. Leave empty for your Vertex default.
- Company (`company`, text): Your company code in Vertex, the taxpayer making the sale.
- Ship from street (`ship_from_street`, text): Street address of the place the goods ship from.
- Ship from city (`ship_from_city`, text): City of the place the goods ship from.
- Ship from state (`ship_from_state`, text): State, province or territory of the place the goods ship from, as a name or postal abbreviation.
- Ship from postal code (`ship_from_postal_code`, text): Postal code of the place the goods ship from.
- Ship from country (`ship_from_country`, text): Country of the place the goods ship from, such as `USA` or `United States`.
- Ship from tax area ID (`ship_from_tax_area_id`, text): 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_code`, text): Your code for the customer, used for exemptions set up in Vertex.
- Ship to street (`ship_to_street`, text): Street address of the customer's delivery address.
- Ship to city (`ship_to_city`, text): City of the customer's delivery address.
- Ship to state (`ship_to_state`, text): State, province or territory of the customer's delivery address, as a name or postal abbreviation.
- Ship to postal code (`ship_to_postal_code`, text): Postal code of the customer's delivery address.
- Ship to country (`ship_to_country`, text): Country of the customer's delivery address, such as `USA` or `United States`.
- Ship to tax area ID (`ship_to_tax_area_id`, text): 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_items`, list, required): The lines to calculate tax on. Each needs a line total or a unit price.

**Outputs**

- `data` (object): The response from Vertex.

**Example output**

```json
{
  "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_id`, text, required): The Vertex tax area ID to check.
- Begin date (`begin_date`, date, required): Look for changes from this date.
- End date (`end_date`, date): Look for changes up to this date.

**Outputs**

- `data` (object): The response from Vertex.

**Example output**

```json
{
  "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_id`, text, required): The transaction ID you gave the calculation.

**Outputs**

- `data` (object): The response from Vertex.

**Example output**

```json
{
  "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_id`, text, required): The transaction ID you gave the calculation.

**Outputs**

- `data` (object): The response from Vertex.

**Example output**

```json
{
  "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_id`, text, required): The location.

**Outputs**

- `data` (object): The response from Vertex.

**Example output**

```json
{
  "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_id`, text, required): The registration ID. Find it with List registrations.

**Outputs**

- `data` (object): The response from Vertex.

**Example output**

```json
{
  "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_id`, text, required): The taxability category ID. Find it with List taxability categories.

**Outputs**

- `data` (object): The response from Vertex.

**Example output**

```json
{
  "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_id`, text, required): The taxpayer.

**Outputs**

- `data` (object): The response from Vertex.

**Example output**

```json
{
  "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_date`, date, required): Look for changes from this date.
- End date (`end_date`, date): Look for changes up to this date.

**Outputs**

- `data` (object): The response from Vertex.

**Example output**

```json
{
  "data": {
    "data": [
      "example"
    ],
    "meta": {
      "app": "example",
      "timeReceived": "example"
    }
  }
}
```

### List locations

List the locations (offices, stores, warehouses) set up in Vertex.

**Inputs**

- Taxpayer (`taxpayer_id`, text): Only the locations of this taxpayer.

**Outputs**

- `data` (object): The response from Vertex.

**Example output**

```json
{
  "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_id`, text): Only the registrations of this taxpayer.
- Registration type (`registration_type`, text): Only registrations of this type, such as `VAT_REGISTRATION`.

**Outputs**

- `data` (object): The response from Vertex.

**Example output**

```json
{
  "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 (`code`, text): Only the category with this code.
- Name (`name`, text): Only the category with this exact name.

**Outputs**

- `data` (object): The response from Vertex.

**Example output**

```json
{
  "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 (`code`, text): Only the taxpayer with this code.
- Name (`name`, text): Only the taxpayer with this exact name.

**Outputs**

- `data` (object): The response from Vertex.

**Example output**

```json
{
  "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_code`, text, required): The jurisdiction code issued by the government authority.
- Country (`country`, text, required): Country the code belongs to, such as `USA`.
- As of date (`as_of_date`, date): Look up the tax areas in force on this date.

**Outputs**

- `data` (object): The response from Vertex.

**Example output**

```json
{
  "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_id`, text, required): The Vertex tax area ID, such as `330612010`.
- As of date (`as_of_date`, date): Look up the tax areas in force on this date.

**Outputs**

- `data` (object): The response from Vertex.

**Example output**

```json
{
  "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 (`street`, text): Street address, first line.
- Street 2 (`street_2`, text): Street address, second line.
- City (`city`, text): City.
- County (`county`, text): County.
- State (`state`, text): State, province or territory, as a name or postal abbreviation.
- Postal code (`postal_code`, text): Postal code.
- Country (`country`, text): Country, such as `USA` or `United States`.
- As of date (`as_of_date`, date): Look up the tax areas in force on this date.

**Outputs**

- `data` (object): The response from Vertex.

**Example output**

```json
{
  "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_id`, text, required): The transaction ID you gave the calculation.
- Reversal transaction ID (`reversal_transaction_id`, text): Your own ID for the new reversing transaction, up to 40 characters.
- Posting date (`posting_date`, date): Date to post the reversal on.
- Document number (`document_number`, text): Document number for the reversal, such as a credit note number.

**Outputs**

- `data` (object): The response from Vertex.

**Example output**

```json
{
  "data": {
    "data": {
      "documentNumber": "example",
      "postingDate": "example",
      "transactionId": "example"
    },
    "meta": {
      "app": "example",
      "timeReceived": "example"
    }
  }
}
```
