​
Overview

The /calculate endpoint allows you to determine the amount of sales tax to charge on a transaction. By providing details such as customer information, line items, and pricing, you’ll receive accurate tax calculations based on applicable jurisdictions and rates.

​
Factors Affecting Tax Rates

Our system considers the following factors to determine the appropriate tax for a transaction:

  1. Seller Information

    • State Registrations:
      • If your corporation is not registered to pay taxes in a state, the /calculate endpoint will return a tax amount of 0 for that state.
      • If your corporation is registered in a state, we calculate the tax amount based on that state’s rates and rules.

  2. Product-Specific Information

    • Product Taxability:
      • Product Configuration: Each corporation can define and manage its product catalog via our /products endpoints. (Coming soon)
      • Product Code Assignment: For every product in the catalog, you can assign a specific product code using the API.
      • Tax Rate Computation: When the /calculate endpoint is called, each line item includes a product id. We use this id to retrieve the pre-configured product code for that product, determining its taxability for the transaction.
        • If a product is classified as non-taxable based on its product code, the tax amount for that specific line item will be 0.
        • If a product is taxable, the tax is calculated based on the product’s price and applicable tax rates.

  3. Customer Information

    • Shipping Address: We compute the tax rate based on the shipping address provided for each transaction.
    • Customer Exemptions: Transactions can be exempted from sales tax based on properties of the customer making the purchase. You can read more about these exemptions here.

​
Sample Calculation Object

The /calculate endpoint returns a JSON object containing the transaction details and calculated taxes.

Example response:

{
  "message": "Successfully calculated tax.",
  "data": {
    "corporation_id": "corp_12345abcde",
    "transacted_at": "2023-09-15",
    "customer_details": {
      "shipping_address": {
        "address_line_1": "123 Main St",
        "address_line_2": "Apt 4B",
        "address_line_3": "",
        "postal_code": "90210",
        "city": "Beverly Hills",
        "state": "CA",
        "country": "US"
      },
      "customer_id": "cust_98765zyxwv"
    },
    "invoice_currency": "USD",
    "subtotal": 119.98,
    "discount": 0,
    "shipping_and_handling": 0,
    "line_items": [
      {
        "raw_amount": 99.99,
        "taxable_amount": 99.99,
        "quantity": 2,
        "tax_code": "TPP",
        "product_id": "",
        "external_id": "item_111aaa",
        "total_tax_rate": 8.25,
        "total_tax_due": 8.25,
        "tax_breakdown": {
          "rates": [
            {
              "jurisdiction_name": "California",
              "jurisdiction_type": "STATE",
              "rate": 6.0
            },
            {
              "jurisdiction_name": "Los Angeles County",
              "jurisdiction_type": "COUNTY",
              "rate": 1.5
            },
            {
              "jurisdiction_name": "Beverly Hills",
              "jurisdiction_type": "CITY",
              "rate": 0.75
            }
          ]
        }
      },
      {
        "raw_amount": 19.99,
        "taxable_amount": 19.99,
        "quantity": 1,
        "tax_code": "TPP",
        "product_id": "",
        "external_id": "item_333ccc",
        "total_tax_rate": 8.25,
        "total_tax_due": 1.65,
        "tax_breakdown": {
          "rates": [
            {
              "jurisdiction_name": "California",
              "jurisdiction_type": "STATE",
              "rate": 6.0
            },
            {
              "jurisdiction_name": "Los Angeles County",
              "jurisdiction_type": "COUNTY",
              "rate": 1.5
            },
            {
              "jurisdiction_name": "Beverly Hills",
              "jurisdiction_type": "CITY",
              "rate": 0.75
            }
          ]
        }
      }
    ],
    "tax_currency": "USD",
    "total_tax_due": 9.90,
    "validation_results": []
  }
}