Tax Essentials

With Gotransverse Tax Essentials, you can create and manage tax tables and calculate taxes for products and services without the need for a third party tax service.

For more information, please search through the Gotransverse online documentation:

Terms of Service: Public use
Request Content-Types: application/json
Response Content-Types: application/json
Version: 1.7.0.1

Authentication

api_key_header

An authorization key that is assigned to perform an action in the system. Passed in the form of a X-Api-Key header that is attached to the call. e.g 325509ed604449279d4587c5e35e3235

type
apiKey
name
X-Api-Key
in
header

Tax Data Management

Get tax table by ID

GET /tax-tables/{id}

Retrieves the specified tax table by ID.

id: integer (int64)
in path

The ID of the tax table.

200 OK

Success

401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

Response Example (200 OK)
{
  "id": "integer (int64)",
  "name": "string",
  "description": "string"
}
Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}

Update tax table

PUT /tax-tables/{id}

Updates a tax table.

The payload for updating the specified tax table.

id: integer (int64)
in path

The ID of the tax table.

Request Example
{
  "id": "integer (int64)",
  "name": "string",
  "description": "string"
}
200 OK

Success

401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

Response Example (200 OK)
{
  "id": "integer (int64)",
  "name": "string",
  "description": "string"
}
Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}

Delete tax table

DELETE /tax-tables/{id}

Deletes the specified tax table.

id: integer (int64)
in path

The ID of the tax table to delete.

200 OK

Success

401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}

Get tax tables

GET /tax-tables

Retrieves a list of available tax tables.

name: string
in query

The name of the tax table.

description: string
in query

The description of the tax table.

200 OK

Success

type
401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

Response Example (200 OK)
[
  {
    "id": "integer (int64)",
    "name": "string",
    "description": "string"
  }
]
Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}

Create tax table

POST /tax-tables

Creates a new tax table.

The payload for creating a new tax table.

Request Example
{
  "id": "integer (int64)",
  "name": "string",
  "description": "string"
}
200 OK

Success

401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

Response Example (200 OK)
{
  "id": "integer (int64)",
  "name": "string",
  "description": "string"
}
Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}

Get tax table entries

GET /tax-tables/{id}/tax-table-entries

Retrieves a list of tax table entries for the specified tax table.

id: integer (int64)
in path

The ID of the tax table.

country: string
in query

The country where the service is being sold.

region: string
in query

The region where the service is being sold.

city: string
in query

The city where the service is being sold.

zip: string
in query

The postal code associated with this tax.

name: string
in query

The name of the tax table entry.

type: string
in query

The type of the tax table entry.

description: string
in query

The description of the tax table entry.

location_code: string
in query

The Location code is used to identify a particular location (for example, a store location) Tax liabilities can be different per location.

entity_type: string PERSONAL, BUSINESS, MATCH_ALL
in query

The tax entity type.

rate: number
in query

The rate of the tax table entry.

custom01: string
in query

A custom field.

custom02: string
in query

A custom field.

custom03: string
in query

A custom field.

200 OK

Success

401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

Response Content-Types: application/json
Response Example (200 OK)
[
  {
    "id": "integer (int64)",
    "name": "string",
    "description": "string",
    "type": "string",
    "country": "string",
    "region": "string",
    "city": "string",
    "zip": "string",
    "code": "string",
    "valid_from": "string (date-time)",
    "valid_to": "string (date-time)",
    "rate": "number",
    "location_code": "string",
    "company_code": "string",
    "custom01": "string",
    "custom02": "string",
    "custom03": "string",
    "entity_type": "string"
  }
]
Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}

Create tax table entries

POST /tax-tables/{id}/tax-table-entries

Creates one or more new tax table entries.

The payload for creating tax table entries.

TaxTableEntry
id: integer (int64)
in path

The ID of the tax table entry.

mode: string OVERWRITE_ON_EXISTING, KEEP_ON_EXISTING, FAIL_BATCH_ON_EXISTING FAIL_BATCH_ON_EXISTING
in query

A field that indicates how to update existing rates in storage if the same ones were posted.

Request Example
[
  {
    "id": "integer (int64)",
    "name": "string",
    "description": "string",
    "type": "string",
    "country": "string",
    "region": "string",
    "city": "string",
    "zip": "string",
    "code": "string",
    "valid_from": "string (date-time)",
    "valid_to": "string (date-time)",
    "rate": "number",
    "location_code": "string",
    "company_code": "string",
    "custom01": "string",
    "custom02": "string",
    "custom03": "string",
    "entity_type": "string"
  }
]
200 OK

Success

401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

Response Example (200 OK)
[
  {
    "id": "integer (int64)",
    "name": "string",
    "description": "string",
    "type": "string",
    "country": "string",
    "region": "string",
    "city": "string",
    "zip": "string",
    "code": "string",
    "valid_from": "string (date-time)",
    "valid_to": "string (date-time)",
    "rate": "number",
    "location_code": "string",
    "company_code": "string",
    "custom01": "string",
    "custom02": "string",
    "custom03": "string",
    "entity_type": "string"
  }
]
Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}

Get tax table entry by ID

GET /tax-tables/{id}/tax-table-entries/{entry_id}

Retrieves the specified tax table entry by the associated tax table and tax table entry IDs.

id: integer (int64)
in path

The ID of the tax table.

entry_id: integer (int64)
in path

The ID of the tax table entry.

200 OK

Success

401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

Response Example (200 OK)
{
  "id": "integer (int64)",
  "name": "string",
  "description": "string",
  "type": "string",
  "country": "string",
  "region": "string",
  "city": "string",
  "zip": "string",
  "code": "string",
  "valid_from": "string (date-time)",
  "valid_to": "string (date-time)",
  "rate": "number",
  "location_code": "string",
  "company_code": "string",
  "custom01": "string",
  "custom02": "string",
  "custom03": "string",
  "entity_type": "string"
}
Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}

Update tax table entry

PUT /tax-tables/{id}/tax-table-entries/{entry_id}

Updates the specified tax table entry by ID.

The payload for updating the specified tax table entry.

id: integer (int64)
in path

The ID of the tax table.

entry_id: integer (int64)
in path

The ID of the tax table entry.

Request Example
{
  "id": "integer (int64)",
  "name": "string",
  "description": "string",
  "type": "string",
  "country": "string",
  "region": "string",
  "city": "string",
  "zip": "string",
  "code": "string",
  "valid_from": "string (date-time)",
  "valid_to": "string (date-time)",
  "rate": "number",
  "location_code": "string",
  "company_code": "string",
  "custom01": "string",
  "custom02": "string",
  "custom03": "string",
  "entity_type": "string"
}
200 OK

Success

401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

Response Example (200 OK)
{
  "id": "integer (int64)",
  "name": "string",
  "description": "string",
  "type": "string",
  "country": "string",
  "region": "string",
  "city": "string",
  "zip": "string",
  "code": "string",
  "valid_from": "string (date-time)",
  "valid_to": "string (date-time)",
  "rate": "number",
  "location_code": "string",
  "company_code": "string",
  "custom01": "string",
  "custom02": "string",
  "custom03": "string",
  "entity_type": "string"
}
Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}

Delete tax table entry

DELETE /tax-tables/{id}/tax-table-entries/{entry_id}

Deletes the specified tax table entry.

id: integer (int64)
in path

The ID of the tax table.

entry_id: integer (int64)
in path

The ID of the tax table entry.

200 OK

Success

401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}

Tax History

Get history of tax table

GET /tax-tables/{id}/history

Retrieves a tax table's history by ID.

id: integer (int64)
in path

The ID of the tax table.

200 OK

Success

401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

Response Example (200 OK)
[
  {
    "entity_type": "string",
    "created_on": "string (date-time)",
    "created_by": "string",
    "id": "integer (int64)",
    "entity_id": "integer (int64)",
    "root_entity_id": "integer (int64)",
    "start_date": "string (date-time)",
    "end_date": "string (date-time)",
    "change_type": "string",
    "description": "string",
    "grouping_key": "string",
    "user_id": "integer (int64)"
  }
]
Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}

Get history of tax table entry

GET /tax-tables/{id}/tax-table-entries/history

Retrieves history of the tax table entry by ID.

id: integer (int64)
in path

The ID of the tax table.

200 OK

Success

401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

Response Example (200 OK)
[
  {
    "entity_type": "string",
    "created_on": "string (date-time)",
    "created_by": "string",
    "id": "integer (int64)",
    "entity_id": "integer (int64)",
    "root_entity_id": "integer (int64)",
    "start_date": "string (date-time)",
    "end_date": "string (date-time)",
    "change_type": "string",
    "description": "string",
    "grouping_key": "string",
    "user_id": "integer (int64)"
  }
]
Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}

Tax Calculation

Calculate taxes

POST /calculate

Creates a request for tax calculation.

The payload for creating a new request to calculate taxes.

Request Example
{
  "tax_table_name": "string",
  "document_type": "string",
  "document_id": "string",
  "document_date": "string (date-time)",
  "currency_code": "string",
  "location_code": "string",
  "company_code": "string",
  "tax_id_number": "string",
  "line_items": [
    {
      "id": "string",
      "item_code": "string",
      "tax_code": "string",
      "tax_included": "boolean",
      "amount": "number",
      "description": "string",
      "address": {
        "line1": "string",
        "line2": "string",
        "city": "string",
        "region": "string",
        "country": "string",
        "postal_code": "string"
      }
    }
  ]
}
200 OK

Success

401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

Response Example (200 OK)
{
  "tax_amount": "number",
  "tax_date": "string (date-time)",
  "tax_items": [
    {
      "line_item_id": "string",
      "tax_code": "string",
      "amount": "number",
      "tax_jurisdiction": [
        {
          "country": "string",
          "region": "string",
          "name": "string",
          "code": "string",
          "type": "string",
          "rate": "number",
          "amount": "number",
          "custom01": "string",
          "custom02": "string",
          "custom03": "string",
          "description": "string"
        }
      ],
      "base_amount": "number"
    }
  ],
  "result_code": "string"
}
Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}

Test Connection

Test connection

GET /test-connection

Tests the connectivity to the tax server.

tax_table_name: string
in query

The name of the tax table.

200 OK

Success

401 Unauthorized

Authentication failed.

403 Forbidden

Access denied.

404 Not Found

Entity not found.

422 Unprocessable Entity

Validation failure.

Response Example (401 Unauthorized)
{
  "code": "string",
  "message": "string"
}
Response Example (403 Forbidden)
{
  "code": "string",
  "message": "string"
}
Response Example (404 Not Found)
{
  "code": "string",
  "message": "string"
}
Response Example (422 Unprocessable Entity)
{
  "code": "string",
  "message": "string"
}

Schema Definitions

TaxTable: object

A representation of the tax table entity.

id: integer (int64)

The ID of the tax table.

name: string

The name of the tax table.

description: string

The description of the tax table.

Example
{
  "id": "integer (int64)",
  "name": "string",
  "description": "string"
}

Error: object

code: string

A code for the specific error. Used to help in determining possible root causes of an error.

message: string

A message providing additional detail for an error.

Example
{
  "code": "string",
  "message": "string"
}

TaxTableEntry: object

An individual tax rate associated with a given tax table.

id: integer (int64)

The ID of the tax table entry.

name: string

The name of the tax table entry, which is used to identify the tax to display purposes only.

description: string

The description of the tax table entry, which is used to display purposes only.

type: string

The type of tax table entry. FAIL_BATCH_ON_EXISTING (default) - select to create a tax table only if the entry with the same date doesn’t exist yet. OVERWRITE_ON_EXISTING - select to create a tax table entry which will update the data in the existing tax table entries. KEEP_ON_EXISTING - select to create a tax table entry but not to duplicate data in the existing tax table entries.

country: string

The country where the service is being sold. Tax requests will match on this field.

region: string

The region where the service is being sold. Tax requests will match on this field.

city: string

The city where the service is being sold. Tax requests will match on this field.

zip: string

The postal code associated with this tax. Tax requests will match on this field.

code: string

The code for this tax table entry. You will need it when configuring the Tax Processor. Tax requests will match on this field.

valid_from: string (date-time)

The date and time since when the tax table entry is valid. Tax requests will match on this field.

valid_to: string (date-time)

The date and time until when the tax table entry is valid. Tax requests will match on this field.

rate: number

A percent of the tax to be applied. For example, the 10% tax rate is specified as 0.1.

location_code: string

The local code is used to identify a particular location (for example, a store location). Tax liabilities can be different per location.

company_code: string

The company code is used to identify a particular company. There can be several companies defined under a single tenant.

custom01: string

A custom field.

custom02: string

A custom field.

custom03: string

A custom field.

entity_type: string BUSINESS, PERSONAL, MATCH_ALL

The type of entity for taxation (BUSINESS, PERSONAL, MATCH_ALL).

Example
{
  "id": "integer (int64)",
  "name": "string",
  "description": "string",
  "type": "string",
  "country": "string",
  "region": "string",
  "city": "string",
  "zip": "string",
  "code": "string",
  "valid_from": "string (date-time)",
  "valid_to": "string (date-time)",
  "rate": "number",
  "location_code": "string",
  "company_code": "string",
  "custom01": "string",
  "custom02": "string",
  "custom03": "string",
  "entity_type": "string"
}

TaxAuditEvent:

entity_type: string TABLE, ENTRY

The type of entity that was modified

  • TABLE - An entity within the Table management function was affected
  • ENTRY - An entity within the Entry Rate Management function was affected .
created_on: string (date-time)

The date and time when the event occurred.

created_by: string

The name of the user who modified the entity.

Example
{
  "entity_type": "string",
  "created_on": "string (date-time)",
  "created_by": "string",
  "id": "integer (int64)",
  "entity_id": "integer (int64)",
  "root_entity_id": "integer (int64)",
  "start_date": "string (date-time)",
  "end_date": "string (date-time)",
  "change_type": "string",
  "description": "string",
  "grouping_key": "string",
  "user_id": "integer (int64)"
}

TaxRequest: object

tax_table_name: string

The name of the tax table used for the tax lookups.

document_type: string

The incoming document type. For example, Order or Invoice.

document_id: string

The ID associated with the document type. For example, the Order Number or the Invoice Number.

document_date: string (date-time)

The date of the document type. For example, the Order Date or the Invoice Date. It represents the date what is used during the lookup in the tax table entry during the tax calculation.

currency_code: CurrencyEnum
location_code: string

The local code is used to identify a particular location. For example, a store location. The tax liabilities can be different according to the location.

company_code: string

The company code is used to identify a particular company. There can be several companies defined under a single tenant.

tax_id_number: string

The tax ID number of an Organization or a Company.

line_items: LineItem
LineItem
Example
{
  "tax_table_name": "string",
  "document_type": "string",
  "document_id": "string",
  "document_date": "string (date-time)",
  "currency_code": "string",
  "location_code": "string",
  "company_code": "string",
  "tax_id_number": "string",
  "line_items": [
    {
      "id": "string",
      "item_code": "string",
      "tax_code": "string",
      "tax_included": "boolean",
      "amount": "number",
      "description": "string",
      "address": {
        "line1": "string",
        "line2": "string",
        "city": "string",
        "region": "string",
        "country": "string",
        "postal_code": "string"
      }
    }
  ]
}

TaxResponse: object

tax_amount: number

The total amount of the tax for line items.

tax_date: string (date-time)

The date when the tax is applied.

tax_items: TaxItem
TaxItem
result_code: string

An arbitrary response code that some gateways may want to return to signify what may have happened on the request.

Example
{
  "tax_amount": "number",
  "tax_date": "string (date-time)",
  "tax_items": [
    {
      "line_item_id": "string",
      "tax_code": "string",
      "amount": "number",
      "tax_jurisdiction": [
        {
          "country": "string",
          "region": "string",
          "name": "string",
          "code": "string",
          "type": "string",
          "rate": "number",
          "amount": "number",
          "custom01": "string",
          "custom02": "string",
          "custom03": "string",
          "description": "string"
        }
      ],
      "base_amount": "number"
    }
  ],
  "result_code": "string"
}

AuditEvent: object

An audit record of an event within the system indicating that something has happened to an underlying entity.

id: integer (int64)

The id of the audit event. Auto-generated by system on creation of event.

entity_id: integer (int64)

The id of the entity being changed.

root_entity_id: integer (int64)

Typically the same as the entity_id. If a parent entity is owning this change, then the parent's entity id. Same value as entity_id if not provided.

start_date: string (date-time)

The time the event started

end_date: string (date-time)

The time the event started. Same value as start_date if not provided.

change_type: string INSERT, UPDATE, DELETE

The type of change performed on the entity.

description: string

A description of what is getting changed.

grouping_key: string

A hash value for a group of events that occured together as part of a transaction. An internally generated UUID value if not provided.

user_id: integer (int64)

The id of the user making the change.

Example
{
  "id": "integer (int64)",
  "entity_id": "integer (int64)",
  "root_entity_id": "integer (int64)",
  "start_date": "string (date-time)",
  "end_date": "string (date-time)",
  "change_type": "string",
  "description": "string",
  "grouping_key": "string",
  "user_id": "integer (int64)"
}

CurrencyEnum: string

The currency code based upon ISO 4217

string USD, GBP, EUR, SEK, NOK, DKK, CAD, AUD, ZAR, NZD, MXN, INR, JPY, SAR, QAR, EGP, AED, BHD, KWD, OMR, HKD, CHF, BRL, PLN, CNY, ILS, COP, PEN, RUB, SGD, IDR, MYR, KRW, TWD, PKR, ARS, CLP, CRC, CZK, HUF, ISK, PHP, RON, THB, TRY, BWP, NGN USD

LineItem: object

id: string

The ID for tax calculation.

item_code: string

The SKU or unique identifier for the item being taxed.

tax_code: string

The taxabilty code for a line item. In Gotransverse, this will align with the price category tax code.

tax_included: boolean

Specifies whether the tax is already included in the amount specified.

amount: number

The amount of money being taxed.

description: string

The description of the taxed item.

address: Address
Example
{
  "id": "string",
  "item_code": "string",
  "tax_code": "string",
  "tax_included": "boolean",
  "amount": "number",
  "description": "string",
  "address": {
    "line1": "string",
    "line2": "string",
    "city": "string",
    "region": "string",
    "country": "string",
    "postal_code": "string"
  }
}

TaxItem: object

line_item_id: string

A reference back to the original line item that is taxed.

tax_code: string

The taxability code for a line item. In Gotransverse, this will align with the price category tax code.

amount: number 0

The amount of tax for this line item.

tax_jurisdiction: TaxJurisdiction
TaxJurisdiction
base_amount: number

The base product price without the included tax.

Example
{
  "line_item_id": "string",
  "tax_code": "string",
  "amount": "number",
  "tax_jurisdiction": [
    {
      "country": "string",
      "region": "string",
      "name": "string",
      "code": "string",
      "type": "string",
      "rate": "number",
      "amount": "number",
      "custom01": "string",
      "custom02": "string",
      "custom03": "string",
      "description": "string"
    }
  ],
  "base_amount": "number"
}

Address: object

The address that is used for taxation.

line1: string

The primary address used for taxation.

line2: string

The secondary address used for taxation.

city: string

The city where the service is being sold.

region: string

The region where the service is being sold.

country: string

The country where the service is being sold.

postal_code: string

The postal code associated with this tax.

Example
{
  "line1": "string",
  "line2": "string",
  "city": "string",
  "region": "string",
  "country": "string",
  "postal_code": "string"
}

TaxJurisdiction: object

The taxation authority that imposes the tax.

country: string

The country where the service is being sold.

region: string

The region where the service is being sold.

name: string

The name of the tax jurisdiction that imposes the tax.

code: string

The taxability code for a line item. In Gotransverse, this will align with the price category tax code.

type: string

The type of tax to be applied. For example, State, Federal, or Local.

rate: number

The tax rate to be applied.

amount: number

The amount of tax for the specified jurisdiction.

custom01: string

A custom field.

custom02: string

A custom field.

custom03: string

A custom field.

description: string

Additional information about the tax jurisdiction.

Example
{
  "country": "string",
  "region": "string",
  "name": "string",
  "code": "string",
  "type": "string",
  "rate": "number",
  "amount": "number",
  "custom01": "string",
  "custom02": "string",
  "custom03": "string",
  "description": "string"
}