Create Calculations

Get tax information for a given product and address

Authorizations

Authorization

string

header

required

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

Body

application/json

customer

object

required

Customer details. Address is required. Optionally accepts a customer ID for order tracking and exemptions.

Show child attributes

customer.address

object

required

Show child attributes

customer.address.address_line_1

string

required

Example:

"3990 N County Rd 300 E"

customer.address.address_city

string

required

Example:

"Danville"

customer.address.address_province

string

required

The province of the transaction. Must be a valid 2 digit ISO 3166-2 province code.

Example:

"IN"

customer.address.address_postal_code

string

required

Example:

"46122"

customer.address.address_country

string

required

The country code of the transaction. Must be a valid ISO 3166-1 alpha-2 country code.

Example:

"US"

customer.address.address_type

string

required

The type of address. Must be one of: shipping or billing. For physical goods, shipping should be used. For software and digital goods, billing is more appropriate

Example:

"shipping"

customer.address.address_line_2

string

Example:

"Unit 2"

customer.id

string

The ID of the customer that you created in our system. Can be used to log customer information or indicate that a purchaser is tax exempt. For more, see Creating a Customer.

Example:

"cus_123456789"

order_details

object

required

Show child attributes

order_details.customer_currency_code

string

required

The currency code of the transaction. Must be either 'USD' or 'CAD'.

Example:

"USD"

order_details.tax_included_in_amount

boolean

required

This should almost always be false for sales in the United States. For the line items in this transaction, does the amount include tax?

Example:

false

order_details.line_items

object[]

required

Each line item should represent one type of product. For compliance, we require either a reference_product_id or a product_category. See this guide for more.

Show child attributes

order_details.line_items.amount

number

required

The price of this line item. We will calculate tax against this value.

Example:

200

order_details.line_items.quantity

number

required

The quantity of this product being sold. Primarily used for record keeping.

Example:

2

order_details.line_items.reference_line_item_id

string

The ID of the line item from your system. This field is optional and will be primarily used for record keeping.

Example:

"line_123456789"

order_details.line_items.reference_product_id

string

The product ID is used to uniquely reference this product in your system as well as in Numeral. Required if no product_category.

Example:

"p-1233543"

order_details.line_items.product_category

string

A tax category from our category taxonomy. Required if no reference_product_id.

Example:

"GENERAL_MERCHANDISE"

origin_address

object

Optional, but relevant for tax collection in certain states. The address that a product is shipped from.

Show child attributes

origin_address.address_line_1

string

required

Example:

"3990 N County Rd 300 E"

origin_address.address_city

string

required

Example:

"Danville"

origin_address.address_province

string

required

The province of the transaction. Must be a valid 2 digit ISO 3166-2 province code.

Example:

"IN"

origin_address.address_postal_code

string

required

Example:

"46122"

origin_address.address_country

string

required

The country code of the transaction. Must be a valid ISO 3166-1 alpha-2 country code.

Example:

"US"

origin_address.address_line_2

string

Example:

"Unit 2"

metadata

object

You can store arbitrary keys and values in the metadata. Any valid JSON object whose values are less than 255 characters long is accepted.

Show child attributes

metadata.example_key

string

Storing things like an order number may be useful for reporting and reconciliation.

Example:

"example_value"

Response

200

application/json

Calculate response

id

string

The ID of the calculation. You will use this to create a transaction.

Example:

"calc_123456789"

object

string

The type of object: tax.calculation.

Example:

"tax.calculation"

customer_currency_code

string

The ISO-4217 currency code of the transaction.

Example:

"USD"

line_items

object[]

Show child attributes

line_items.product

object

Show child attributes

line_items.product.reference_product_name

string

Example:

"Widget"

line_items.product.reference_line_item_id

string

Example:

"line_987654321"

line_items.product.reference_product_id

string

Example:

"p-1233543"

line_items.product.product_tax_code

string

Example:

"GENERAL_MERCHANDISE"

line_items.tax_jurisdictions

array

Show child attributes

line_items.tax_jurisdictions.tax_rate

number

The tax rate percentage applied to this transaction.

Example:

0.07

line_items.tax_jurisdictions.rate_type

string

Example:

"STATE SALES TAX"

line_items.tax_jurisdictions.jurisdiction_name

string

Example:

"Indiana"

line_items.tax_jurisdictions.fee_amount

number

The flat fee that is added to this transaction. Like all numeric values, this will be returned in cents and should be added directly to the tax amount independent of other percentages. For example, a $100 transaction taxed at 5% and with a fee_amount: 50 will lead to ($100 * 5% + 0.50) = $5.50 in tax being charged

Example:

0

line_items.quantity

number

Example:

2

line_items.tax_amount

number

Example:

14

line_items.amount_excluding_tax

number

Example:

200

line_items.amount_including_tax

number

Example:

214

tax_included_in_amount

boolean

Example:

false

total_tax_amount

number

Total tax to charge on this calculation.

Example:

14

total_amount_excluding_tax

number

Total sale charge, excluding tax.

Example:

200

total_amount_including_tax

number

Total sale charge plus tax. What you should charge your customer.

Example:

214

expires_at

number

Epoch datetime representing the date and time the tax rates are valid until.

Example:

1714787673

testmode

boolean

True if using a production API key. False if using a test API key.

Example:

"false"

metadata

object

You can store arbitrary keys and values in the metadata. Any valid JSON object whose values are less than 255 characters long is accepted.

Show child attributes

metadata.example_key

string

Storing things like an order number may be useful for reporting and reconciliation.

Example:

"example_value"