Calculate taxes

Authorizations

X-Api-Key

string

header

required

An API key that grants access to the Connect API. You can create and manage API keys in the portal.

Headers

X-Idempotency-Key

string

A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.

Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.

Maximum string length: 256

Body

application/json

Request to calculate taxes for line items at a specific address.

lineItems

Product Offering · object[]

required

Line items to calculate taxes for.

Minimum array length: 1

Show child attributes

lineItems.type

enum<string>

required

Line item type discriminator.

Available options:

PRODUCT_OFFERING

lineItems.productOfferingId

string

required

The product offering to calculate taxes for.

Example:

"mobile-plan-premium"

customerId

string

Optional customer ID for customer-specific tax calculations.

Example:

"123e4567-e89b-12d3-a456-426614174000"

address

object

The address where taxes should be calculated for.

If the customer ID is not provided, this address is required. If both customer ID and address are provided, the address will override the customer's default address for tax calculation.

Show child attributes

address.street1

string

required

The first line of the address, typically street and house number.

Example:

"500 S Main St"

address.city

string

required

The city or municipality of the address.

Example:

"Natick"

address.zip

string

required

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').

Example:

"01701"

address.country

string

required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

Example:

"US"

address.street2

string

The second line of the address, typically apartment, suite, unit, building, floor, etc.

Example:

"Apt 1"

address.state

string

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

Example:

"CA"

address.region

string

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

address.attention

string

An optional line for specifying a person, department, or attention to a specific entity within an address.

Promotional code to apply for discount calculation before computing taxes.

Example:

"STUDENT2024"

Response

Tax calculation completed successfully.

Tax calculation result with line-by-line breakdown and totals.

lineItems

object[]

required

Tax calculation results for each line item.

Show child attributes

lineItems.lineItem

Product Offering · object

required

The original line item that was calculated.

Show child attributes

lineItems.lineItem.type

enum<string>

required

Line item type discriminator.

Available options:

PRODUCT_OFFERING

lineItems.lineItem.productOfferingId

string

required

The product offering to calculate taxes for.

Example:

"mobile-plan-premium"

lineItems.netAmount

number<decimal>

required

Net amount before taxes (quantity x unit price).

Example:

29.99

lineItems.taxAmount

number<decimal>

required

Total tax amount for this line item.

Example:

7.5

lineItems.totalAmount

number<decimal>

required

Total amount including taxes.

Example:

37.49

lineItems.currency

string

required

Currency for all amounts.

Example:

"USD"

lineItems.taxBreakdown

object[]

Detailed breakdown of different tax components.

Show child attributes

lineItems.taxBreakdown.description

string

required

Description of this tax component.

Example:

"Sales Tax"

lineItems.taxBreakdown.amount

number<decimal>

required

Tax amount for this component.

Example:

2.4

lineItems.taxBreakdown.rate

number<decimal>

Tax rate as a percentage (optional).

Example:

8.25

totals

object

required

Summary totals across all line items.

Show child attributes

totals.netAmount

number<decimal>

required

Total net amount before taxes across all line items.

Example:

129.97

totals.taxAmount

number<decimal>

required

Total tax amount across all line items.

Example:

32.49

totals.totalAmount

number<decimal>

required

Total amount including taxes across all line items.

Example:

162.46

totals.currency

string

required

Currency for all amounts.

Example:

"USD"

totals.taxBreakdown

object[]

Aggregated tax breakdown across all line items.

Show child attributes

totals.taxBreakdown.description

string

required

Description of this tax component.

Example:

"Sales Tax"

totals.taxBreakdown.amount

number<decimal>

required

Tax amount for this component.

Example:

2.4

totals.taxBreakdown.rate

number<decimal>

Tax rate as a percentage (optional).

Example:

8.25

Getting started

Overview

API reference

Authorizations

Headers

Body

Response