Calculate tax

Calculate sales tax for a transaction

curl --request POST \
  --url https://base_url/api/v1/calculate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "corporation_id": "b6d009b0-d174-463f-b030-94643c28e209",
  "transaction_date": "2023-12-25",
  "transaction_currency": "USD",
  "transaction_type": "SALE",
  "addresses": {
    "ship_to": {
      "postal_code": "90401",
      "state": "CA",
      "country": "US",
      "address_line_1": "1776 Main St",
      "address_line_2": "Apt. #123",
      "address_line_3": "<string>",
      "city": "Santa Monica"
    },
    "ship_from": {
      "postal_code": "90401",
      "state": "CA",
      "country": "US",
      "address_line_1": "1776 Main St",
      "address_line_2": "Apt. #123",
      "address_line_3": "<string>",
      "city": "Santa Monica"
    }
  },
  "customer_details": {
    "customer_id": "<string>"
  },
  "line_items": {
    "items": [
      {
        "quantity": 1.01,
        "amount": 1,
        "line_number": 2,
        "product_taxability_code": "TPP",
        "discount": 1,
        "product_id": "<string>"
      }
    ]
  },
  "discount": 0.99
}
'

{
  "data": {
    "corporation_id": "b6d009b0-d174-463f-b030-94643c28e209",
    "transaction_date": "2023-12-25",
    "transaction_currency": "USD",
    "discount": 0.99,
    "customer_details": {
      "customer_id": "<string>"
    },
    "tax_currency": "USD",
    "addresses": {
      "ship_from": {
        "postal_code": "90401",
        "state": "CA",
        "country": "US",
        "address_line_1": "1776 Main St",
        "address_line_2": "Apt. #123",
        "address_line_3": "<string>",
        "city": "Santa Monica"
      },
      "ship_to": {
        "postal_code": "90401",
        "state": "CA",
        "country": "US",
        "address_line_1": "1776 Main St",
        "address_line_2": "Apt. #123",
        "address_line_3": "<string>",
        "city": "Santa Monica"
      }
    },
    "line_items": [
      {
        "amount": 123,
        "taxable_amount": 123,
        "quantity": 123,
        "tax_code": "<string>",
        "product_id": "<string>",
        "effective_tax_rate": 123,
        "tax_breakdown": [
          {
            "jurisdiction": "California",
            "jurisdiction_type": "STATE",
            "rate": 6.25
          }
        ],
        "total_tax_due": 1.03
      }
    ]
  },
  "message": "Successfully calculated tax."
}

POST

calculate

Calculate sales tax for a transaction

curl --request POST \
  --url https://base_url/api/v1/calculate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "corporation_id": "b6d009b0-d174-463f-b030-94643c28e209",
  "transaction_date": "2023-12-25",
  "transaction_currency": "USD",
  "transaction_type": "SALE",
  "addresses": {
    "ship_to": {
      "postal_code": "90401",
      "state": "CA",
      "country": "US",
      "address_line_1": "1776 Main St",
      "address_line_2": "Apt. #123",
      "address_line_3": "<string>",
      "city": "Santa Monica"
    },
    "ship_from": {
      "postal_code": "90401",
      "state": "CA",
      "country": "US",
      "address_line_1": "1776 Main St",
      "address_line_2": "Apt. #123",
      "address_line_3": "<string>",
      "city": "Santa Monica"
    }
  },
  "customer_details": {
    "customer_id": "<string>"
  },
  "line_items": {
    "items": [
      {
        "quantity": 1.01,
        "amount": 1,
        "line_number": 2,
        "product_taxability_code": "TPP",
        "discount": 1,
        "product_id": "<string>"
      }
    ]
  },
  "discount": 0.99
}
'

{
  "data": {
    "corporation_id": "b6d009b0-d174-463f-b030-94643c28e209",
    "transaction_date": "2023-12-25",
    "transaction_currency": "USD",
    "discount": 0.99,
    "customer_details": {
      "customer_id": "<string>"
    },
    "tax_currency": "USD",
    "addresses": {
      "ship_from": {
        "postal_code": "90401",
        "state": "CA",
        "country": "US",
        "address_line_1": "1776 Main St",
        "address_line_2": "Apt. #123",
        "address_line_3": "<string>",
        "city": "Santa Monica"
      },
      "ship_to": {
        "postal_code": "90401",
        "state": "CA",
        "country": "US",
        "address_line_1": "1776 Main St",
        "address_line_2": "Apt. #123",
        "address_line_3": "<string>",
        "city": "Santa Monica"
      }
    },
    "line_items": [
      {
        "amount": 123,
        "taxable_amount": 123,
        "quantity": 123,
        "tax_code": "<string>",
        "product_id": "<string>",
        "effective_tax_rate": 123,
        "tax_breakdown": [
          {
            "jurisdiction": "California",
            "jurisdiction_type": "STATE",
            "rate": 6.25
          }
        ],
        "total_tax_due": 1.03
      }
    ]
  },
  "message": "Successfully calculated tax."
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

corporation_id

string

required

The unique identifier for the corporation associated with this transaction.

Example:

"b6d009b0-d174-463f-b030-94643c28e209"

transaction_date

string<date>

required

ISO 8601 formatted date string indicating date on which the transaction took place.

transaction_currency

string

required

ISO 4217 alpha-3 currency code for the transaction.

Example:

"USD"

transaction_type

enum<string>

required

Type of the transaction (sale or refund).

Available options:

SALE,

REFUND

addresses

object

required

The addresses for this transaction, including shipping origin and destination. If destination address is not set, we will attempt to extract it from the linked customer. If a customer is not linked, or if the linked customer does not have a shipping address, the tax calculation will fail.

Show child attributes

addresses.ship_to

object

required

Show child attributes

addresses.ship_to.postal_code

string

required

Either 5-digit ZIP code or 9-digit ZIP+4 code is accepted.

Example:

"90401"

addresses.ship_to.state

string

required

2-letter code for each state. Suffix of the ISO 3166-2 code. Ex: CA, NY, TX.

Example:

"CA"

addresses.ship_to.country

string

required

ISO 3166 2-letter country code. Ex: US, IN, GB.

Example:

"US"

addresses.ship_to.address_line_1

string

Example:

"1776 Main St"

addresses.ship_to.address_line_2

string

Example:

"Apt. #123"

addresses.ship_to.address_line_3

string

addresses.ship_to.city

string

Example:

"Santa Monica"

addresses.ship_from

object

Show child attributes

addresses.ship_from.postal_code

string

required

Either 5-digit ZIP code or 9-digit ZIP+4 code is accepted.

Example:

"90401"

addresses.ship_from.state

string

required

2-letter code for each state. Suffix of the ISO 3166-2 code. Ex: CA, NY, TX.

Example:

"CA"

addresses.ship_from.country

string

required

ISO 3166 2-letter country code. Ex: US, IN, GB.

Example:

"US"

addresses.ship_from.address_line_1

string

Example:

"1776 Main St"

addresses.ship_from.address_line_2

string

Example:

"Apt. #123"

addresses.ship_from.address_line_3

string

addresses.ship_from.city

string

Example:

"Santa Monica"

customer_details

object

required

Customer details for this transaction.

Show child attributes

customer_details.customer_id

string

Unique identifier for the customer for this transaction. Used for exemptions and for shipping address. If fields on the customer conflict with fields on this calculation, the ones on the calculation will be prioritized.

line_items

object

required

Show child attributes

line_items.items

object[]

required

Array of line items representing individual products or services in the transaction. For each line item either pass the tax_code or the product_id. If the product_id is passed the tax_code will be fetched from the product itself. If no product_taxaiblity_code is available, TPP will be used as the fallback.

Show child attributes

line_items.items.quantity

number

required

Quantity of units purchased.

Required range: x >= 0.01

line_items.items.amount

number

required

Total price for the line item.

Required range: x >= 0

line_items.items.line_number

integer

Optional line number for this item.

Required range: x >= 1

line_items.items.product_taxability_code

string

default:TPP

Code passed by the caller to determine taxability for this product. Default value, TPP, will be taxable in every jurisdiction. Additional values are available here.

Example:

"TPP"

line_items.items.discount

number

Discount amount for this line item.

Required range: x >= 0

line_items.items.product_id

string

The unique identifier for the product.

discount

number

Total discount amount applied to the subtotal.

Required range: x >= 0

Example:

0.99

Response

Successful tax calculation

data

object

Show child attributes

data.corporation_id

string

The unique identifier for the corporation associated with this transaction.

Example:

"b6d009b0-d174-463f-b030-94643c28e209"

data.transaction_date

string<date>

ISO 8601 formatted date string indicating date on which the transaction took place.

data.transaction_currency

string

ISO 4217 alpha-3 currency code for the transaction.

Example:

"USD"

data.discount

number<float>

Total discount amount applied to the transaction.

Example:

0.99

data.customer_details

object

Customer details for this transaction.

Show child attributes

data.customer_details.customer_id

string

Unique identifier for the customer for this transaction.

data.tax_currency

string

ISO 4217 alpha-3 currency code representing the currency in which tax details are reported.

Example:

"USD"

data.addresses

object

The addresses for this transaction, including shipping origin and destination.

Show child attributes

data.addresses.ship_from

object

Show child attributes

data.addresses.ship_from.postal_code

string

required

Either 5-digit ZIP code or 9-digit ZIP+4 code is accepted.

Example:

"90401"

data.addresses.ship_from.state

string

required

2-letter code for each state. Suffix of the ISO 3166-2 code. Ex: CA, NY, TX.

Example:

"CA"

data.addresses.ship_from.country

string

required

ISO 3166 2-letter country code. Ex: US, IN, GB.

Example:

"US"

data.addresses.ship_from.address_line_1

string

Example:

"1776 Main St"

data.addresses.ship_from.address_line_2

string

Example:

"Apt. #123"

data.addresses.ship_from.address_line_3

string

data.addresses.ship_from.city

string

Example:

"Santa Monica"

data.addresses.ship_to

object

Show child attributes

data.addresses.ship_to.postal_code

string

required

Either 5-digit ZIP code or 9-digit ZIP+4 code is accepted.

Example:

"90401"

data.addresses.ship_to.state

string

required

2-letter code for each state. Suffix of the ISO 3166-2 code. Ex: CA, NY, TX.

Example:

"CA"

data.addresses.ship_to.country

string

required

ISO 3166 2-letter country code. Ex: US, IN, GB.

Example:

"US"

data.addresses.ship_to.address_line_1

string

Example:

"1776 Main St"

data.addresses.ship_to.address_line_2

string

Example:

"Apt. #123"

data.addresses.ship_to.address_line_3

string

data.addresses.ship_to.city

string

Example:

"Santa Monica"

data.line_items

object[]

Show child attributes

data.line_items.amount

number<float>

Total price for the line item.

data.line_items.taxable_amount

number<float>

The amount that is considered taxable for this line item.

data.line_items.quantity

number<float>

Quantity of units purchased.

data.line_items.tax_code

string

The tax code used for this line item.

data.line_items.product_id

string

The unique identifier for the product.

data.line_items.effective_tax_rate

number<float>

The effective tax rate applied to this line item.

data.line_items.tax_breakdown

object[]

Show child attributes

data.line_items.tax_breakdown.jurisdiction

string

Name of the taxing jurisdiction.

Example:

"California"

data.line_items.tax_breakdown.jurisdiction_type

enum<string>

Type of tax jurisdiction.

Available options:

STATE,

COUNTY,

CITY,

SPECIAL_DISTRICT

data.line_items.tax_breakdown.rate

number<float>

Tax rate for this jurisdiction as a percentage.

Example:

6.25

data.line_items.total_tax_due

number<float>

Total amount of sales tax to charge for line item.

Example:

1.03

message

string

Example:

"Successfully calculated tax."

Tax Calculations Tax Transactions

⌘I

Sales Tax API

Core Concepts

Corporations

Calculate

Transactions

Nexus

Registrations

Filings

Products

Customers

Exemption Certificates

Files

Webhooks

Authorizations

Body

Response