> ## Documentation Index
> Fetch the complete documentation index at: https://docs.commenda.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Calculate tax
```json US request theme={null}
{
"corporation_id": "b6d009b0-d174-463f-b030-94643c28e209",
"transaction_date": "2023-12-25",
"transaction_currency": "USD",
"transaction_type": "SALE",
"discount": 0,
"addresses": {
"ship_to": {
"address_line_1": "1776 Main St",
"address_line_2": "Apt. #123",
"postal_code": "90401",
"city": "Santa Monica",
"state": "CA",
"country": "US"
},
"ship_from": {
"address_line_1": "1776 Main St",
"address_line_2": "Apt. #123",
"postal_code": "90401",
"city": "Santa Monica",
"state": "CA",
"country": "US"
}
},
"customer_details": {
"customer_id": "customer_123"
},
"line_items": {
"items": [
{
"line_number": 1,
"product_taxability_code": "TPP",
"quantity": 1,
"amount": 100.00,
"discount": 0,
"product_id": "prod_123"
}
]
}
}
```
```json UK request theme={null}
{
"corporation_id": "b6d009b0-d174-463f-b030-94643c28e209",
"transaction_date": "2025-04-01",
"transaction_currency": "GBP",
"transaction_type": "SALE",
"discount": 0,
"addresses": {
"ship_to": {
"address_line_1": "10 Downing Street",
"postal_code": "SW1A 2AA",
"city": "London",
"country": "GB"
},
"ship_from": {
"address_line_1": "1 Canada Square",
"postal_code": "E14 5AB",
"city": "London",
"country": "GB"
}
},
"customer_details": {
"customer_id": "customer_456"
},
"line_items": {
"items": [
{
"line_number": 1,
"product_taxability_code": "TPP",
"quantity": 1,
"amount": 250.00,
"discount": 0,
"product_id": "prod_456"
}
]
}
}
```
```json Cross-currency request (EUR to US) theme={null}
{
"corporation_id": "b6d009b0-d174-463f-b030-94643c28e209",
"transaction_date": "2025-04-01",
"transaction_currency": "EUR",
"transaction_type": "SALE",
"discount": 0,
"addresses": {
"ship_to": {
"address_line_1": "1776 Main St",
"postal_code": "90401",
"city": "Santa Monica",
"state": "CA",
"country": "US"
}
},
"customer_details": {
"customer_id": "customer_789"
},
"line_items": {
"items": [
{
"line_number": 1,
"product_taxability_code": "TPP",
"quantity": 1,
"amount": 100.00,
"discount": 0,
"product_id": "prod_789"
}
]
}
}
```
```json 200 (same currency) theme={null}
{
"data": {
"id": "calc_123",
"corporation_id": "b6d009b0-d174-463f-b030-94643c28e209",
"transaction_date": "2023-12-25",
"transaction_currency": "USD",
"discount": 0,
"calculation_currency": "USD",
"exchange_rate": 1.0,
"total_amount": 100.00,
"total_tax": 9.50,
"total_due": 109.50,
"customer_details": {
"customer_id": "customer_123"
},
"tax_currency": "USD",
"addresses": {
"ship_from": {
"address_line_1": "1776 Main St",
"address_line_2": "Apt. #123",
"postal_code": "90401",
"city": "Santa Monica",
"state": "CA",
"country": "US"
},
"ship_to": {
"address_line_1": "1776 Main St",
"address_line_2": "Apt. #123",
"postal_code": "90401",
"city": "Santa Monica",
"state": "CA",
"country": "US"
}
},
"line_items": [
{
"line_item_id": "line_123",
"amount": 100.00,
"taxable_amount": 100.00,
"quantity": 1,
"tax_code": "TPP",
"product_id": "prod_123",
"line_number": 1,
"effective_tax_rate": 9.5,
"base_tax_rate": 6.0,
"tax_breakdown": [
{
"jurisdiction_name": "California",
"jurisdiction_type": "STATE",
"rate": 6.0,
"base_rate": 6.0,
"tax_class": "TAXABLE",
"tax_class_reason": ""
},
{
"jurisdiction_name": "Los Angeles County",
"jurisdiction_type": "COUNTY",
"rate": 2.25,
"base_rate": 2.25,
"tax_class": "TAXABLE",
"tax_class_reason": ""
},
{
"jurisdiction_name": "Santa Monica",
"jurisdiction_type": "CITY",
"rate": 1.25,
"base_rate": 1.25,
"tax_class": "TAXABLE",
"tax_class_reason": ""
}
],
"total_tax_due": 9.50
}
]
},
"message": "Successfully calculated tax."
}
```
```json 200 Cross-currency response theme={null}
{
"data": {
"id": "calc_456",
"corporation_id": "b6d009b0-d174-463f-b030-94643c28e209",
"transaction_date": "2025-04-01",
"transaction_currency": "EUR",
"discount": 0,
"calculation_currency": "USD",
"exchange_rate": 1.08,
"total_amount": 100.00,
"total_tax": 8.80,
"total_due": 108.80,
"customer_details": {
"customer_id": "customer_789"
},
"tax_currency": "EUR",
"addresses": {
"ship_from": null,
"ship_to": {
"address_line_1": "1776 Main St",
"postal_code": "90401",
"city": "Santa Monica",
"state": "CA",
"country": "US"
}
},
"line_items": [
{
"line_item_id": "line_456",
"amount": 100.00,
"taxable_amount": 100.00,
"quantity": 1,
"tax_code": "TPP",
"product_id": "prod_789",
"line_number": 1,
"effective_tax_rate": 9.5,
"base_tax_rate": 6.0,
"tax_breakdown": [
{
"jurisdiction_name": "California",
"jurisdiction_type": "STATE",
"rate": 6.0,
"base_rate": 6.0,
"tax_class": "TAXABLE",
"tax_class_reason": "TAX_APPLIED"
},
{
"jurisdiction_name": "Los Angeles County",
"jurisdiction_type": "COUNTY",
"rate": 2.25,
"base_rate": 2.25,
"tax_class": "TAXABLE",
"tax_class_reason": "TAX_APPLIED"
},
{
"jurisdiction_name": "Santa Monica",
"jurisdiction_type": "CITY",
"rate": 1.25,
"base_rate": 1.25,
"tax_class": "TAXABLE",
"tax_class_reason": "TAX_APPLIED"
}
],
"total_tax_due": 8.80
}
]
},
"message": "Successfully calculated tax."
}
```
```json 400 Missing address theme={null}
{
"type": "INVALID_REQUEST_BODY",
"sub_type": "MISSING_SHIP_TO_ADDRESS",
"title": "Missing destination address.",
"detail": {
"description": "Missing destination address. Shipping address is picked from addresses.ship_to or picked from customer_details.customer_id (customer's default shipping address)."
},
"status": 400
}
```
```json 400 Invalid address theme={null}
{
"type": "INVALID_REQUEST_BODY",
"sub_type": "INVALID_ADDRESS",
"title": "Invalid address passed.",
"detail": {
"description": "Field 'city' is required for country US."
},
"status": 400
}
```
## OpenAPI
````yaml POST /calculate
openapi: 3.0.1
info:
title: Commenda Public APIs
description: >-
APIs for Commenda entity management, partner incorporation, indirect tax,
compliance, and corporate operations.
license:
name: NONE
url: NONE
version: 1.0.0
servers:
- url: https://api.prod.commenda.io/api/v1
description: Commenda platform APIs, including Partner Incorporation and Commenda OS.
- url: https://transaction-tax.api.in.commenda.io/api/v1
description: Global Indirect Tax API.
security:
- bearerAuth: []
paths:
/calculate:
post:
summary: Calculate sales tax for a transaction
operationId: calculateSalesTax
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TaxCalculationRequest'
responses:
'200':
description: Successful tax calculation
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/TaxCalculationResponse'
message:
type: string
example: Successfully calculated tax.
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
TaxCalculationRequest:
type: object
required:
- corporation_id
- transaction_date
- transaction_currency
- transaction_type
- addresses
- customer_details
- line_items
properties:
corporation_id:
type: string
description: >-
The unique identifier for the corporation associated with this
transaction.
example: b6d009b0-d174-463f-b030-94643c28e209
transaction_date:
type: string
format: date
description: >-
ISO 8601 formatted date string indicating date on which the
transaction took place.
transaction_currency:
$ref: '#/components/schemas/Currency'
description: >
ISO 4217 alpha-3 currency code for the transaction. If omitted,
defaults to the standard currency of the ship-to country (e.g., USD
for the US, CAD for Canada, GBP for the UK). When this differs from
the ship-to country's default currency, amounts are automatically
converted for tax calculation and converted back in the response.
transaction_type:
type: string
enum:
- SALE
- REFUND
- PURCHASE
description: >-
Type of the transaction:
- SALE: Standard sales transaction.
- REFUND: Refund/return transaction with negative line item amounts.
- PURCHASE: Purchase transaction for input tax credit tracking. Line
item amounts must be negative.
discount:
type: number
minimum: 0
example: 0.99
description: Total discount amount applied to the subtotal.
addresses:
type: object
properties:
ship_to:
$ref: '#/components/schemas/Address'
description: >
Destination address for the transaction. If omitted, the API
falls back to the default shipping address of the customer
specified in `customer_details.customer_id`. If neither is
available, the request fails with a `MISSING_SHIP_TO_ADDRESS`
error. Address fields are validated against per-country
requirements — use the `/address-requirements` endpoint to check
which fields are required for each country.
ship_from:
$ref: '#/components/schemas/Address'
description: >
Origin address for the transaction. Required for certain
destination countries (e.g., GB). If required but not provided,
the request fails with a `MISSING_SHIP_FROM_ADDRESS` error. When
the destination is US, the ship-from state must be a valid US
state code and the postal code must be a valid US ZIP code.
description: >
Shipping origin and destination addresses. The `ship_to` field is
optional when a `customer_id` is provided that has a default
shipping address on file. The `ship_from` field is required for
certain destination countries. All address fields are validated
against country-specific requirements — query
`/address-requirements` to check which fields are required,
optional, or ignored for a given country.
customer_details:
type: object
properties:
customer_id:
type: string
description: >-
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.
description: Customer details for this transaction.
exemption_reason:
$ref: '#/components/schemas/ExemptionType'
description: >-
Optional exemption reason to apply to the entire transaction. When
provided, the transaction may be fully or partially exempt from tax
based on the exemption type and applicable jurisdiction rules.
line_items:
type: object
required:
- items
properties:
items:
description: >
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.
type: array
items:
type: object
required:
- quantity
- amount
properties:
line_number:
type: integer
minimum: 1
description: Optional line number for this item.
line_item_id:
type: string
description: Optional identifier to uniquely identify this line item.
product_taxability_code:
$ref: '#/components/schemas/ProductTaxCode'
quantity:
type: number
description: >
Quantity of units. Must not be zero. For REFUND or
PURCHASE transactions, negative values are accepted.
Cannot be negative simultaneously with `amount`.
amount:
type: number
description: >
Total price for the line item. For REFUND or PURCHASE
transactions, negative values are accepted. Cannot be
negative simultaneously with `quantity`.
discount:
type: number
minimum: 0
description: Discount amount for this line item.
product_id:
type: string
description: The unique identifier for the product.
product_source_platform:
$ref: '#/components/schemas/SourcePlatform'
product_source_platform_id:
type: string
description: The identifier for the product on the source platform.
TaxCalculationResponse:
type: object
properties:
corporation_id:
type: string
description: >-
The unique identifier for the corporation associated with this
transaction.
example: b6d009b0-d174-463f-b030-94643c28e209
transaction_date:
type: string
format: date
description: >-
ISO 8601 formatted date string indicating date on which the
transaction took place.
transaction_currency:
$ref: '#/components/schemas/Currency'
calculation_currency:
type: string
description: >
ISO 4217 alpha-3 currency code representing the currency used
internally for the tax computation. This is the default currency of
the ship-to country (e.g., USD for the US, CAD for Canada, GBP for
the UK).
example: USD
exchange_rate:
type: number
format: float
description: >
The exchange rate applied between the transaction currency and the
calculation currency. When no conversion is needed (i.e., the
transaction currency matches the ship-to country's default
currency), this value is 1.0.
example: 1
discount:
type: number
format: float
example: 0.99
description: Total discount amount applied to the transaction.
customer_details:
type: object
properties:
customer_id:
type: string
description: Unique identifier for the customer for this transaction.
description: Customer details for this transaction.
tax_currency:
$ref: '#/components/schemas/Currency'
description: >-
ISO 4217 alpha-3 currency code representing the currency in which
tax details are reported. This matches the transaction currency.
addresses:
type: object
properties:
ship_from:
$ref: '#/components/schemas/Address'
ship_to:
$ref: '#/components/schemas/Address'
description: >-
The addresses for this transaction, including shipping origin and
destination.
line_items:
type: array
items:
type: object
properties:
amount:
type: number
format: float
description: Total price for the line item.
taxable_amount:
type: number
format: float
description: The amount that is considered taxable for this line item.
quantity:
type: number
format: float
description: Quantity of units purchased.
tax_code:
type: string
description: The tax code used for this line item.
product_id:
type: string
description: The unique identifier for the product.
effective_tax_rate:
type: number
format: float
description: The effective tax rate applied to this line item.
tax_breakdown:
type: array
items:
type: object
properties:
jurisdiction:
type: string
description: Name of the taxing jurisdiction.
example: California
jurisdiction_type:
type: string
enum:
- STATE
- COUNTY
- CITY
- SPECIAL_DISTRICT
- TRADEBLOC
description: Type of tax jurisdiction.
rate:
type: number
format: float
example: 6.25
description: Tax rate for this jurisdiction as a percentage.
total_tax_due:
type: number
format: float
example: 1.03
description: Total amount of sales tax to charge for line item.
Error:
type: object
required:
- error
properties:
error:
type: object
properties:
type:
type: string
description: 'Specific Error type. Example: CLIENT_INVALID_REQUEST_BODY.'
example: CLIENT_INVALID_REQUEST_BODY
doc_url:
type: string
description: >-
A link to the docs with details about this error. Example:
https://sales-tax-docs.commenda.io/
example: https://sales-tax-docs.commenda.io/
title:
type: string
description: >-
A short title describing the error. Example: Missing query
parameters.
example: Failed to validate the request body
detail:
type: string
description: >-
A json string with a description on how to fix the error.
Example {"description":"Please pass in a valid corporation_id"}
status:
type: number
description: >-
The status code. It should be the same as the HTTP protocol
status code. Example: 200
example: 400
instance:
type: string
description: >-
The relative path that was hit by the user. Example:
/api/v1/corporations/1
Errors:
type: array
items:
type: object
properties:
details:
type: string
description: More details on how to solve this particular error.
pointer:
type: string
description: >-
Relative reference to missing or invalid piece of passed
information.
Currency:
type: string
example: USD
description: ISO 4217 alpha-3 currency code for the transaction.
Address:
type: object
required:
- country
description: >
Address object. Only `country` is required at the schema level. All
other field requirements (including `postal_code` and `state`) vary by
country — use the `/address-requirements` endpoint to check which fields
are REQUIRED, OPTIONAL, or IGNORED for a given country. When provided,
postal codes and state codes are validated against country-specific
formats and allowed values.
properties:
address_line_1:
type: string
example: 1776 Main St
description: Primary street address. Required for some countries (e.g., US).
address_line_2:
type: string
example: 'Apt. #123'
description: >-
Secondary address line (apartment, suite, etc.). Optional for most
countries.
address_line_3:
type: string
description: Tertiary address line. Ignored for most countries.
postal_code:
type: string
description: >
Postal or ZIP code. Required for many countries (e.g., US, GB, DE,
FR) and optional for others (e.g., CA). Format varies by country.
For US addresses, either 5-digit ZIP or 9-digit ZIP+4 is accepted.
Use the `/address-requirements` endpoint to check whether this field
is required and to get the validation regex for each country.
example: '90401'
city:
type: string
example: Santa Monica
description: City name. Required for some countries (e.g., US).
state:
$ref: '#/components/schemas/State'
description: >
State or province code. Required for some countries (e.g., US) and
optional for others (e.g., GB, DE). Must be a valid ISO 3166-2
subdivision code for the given country when provided. Use the
`/address-requirements` endpoint to check whether this field is
required and to get the list of valid state codes for each country.
country:
$ref: '#/components/schemas/Country'
ExemptionType:
type: string
description: Reason for a sales tax exemption.
enum:
- PURPOSE_RESALE
- ENTITY_TYPE_NONPROFIT
- GOVERNMENT
- MANUFACTURER
- AGRICULTURAL
- EXEMPT_PRODUCT
- OTHER
- EXEMPT_PRODUCT
ProductTaxCode:
type: string
example: TPP
description: >-
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](/api-reference/global-indirect-tax/taxcode).
default: TPP
SourcePlatform:
type: string
description: Platform where this entity originated.
enum:
- RAZORPAY
- ZOHO_BOOKS
- QUICKBOOKS_SANDBOX
- QUICKBOOKS
- XERO
- TALLY
- SAGE_CLOUD_ACCOUNTING
- MS_DYNAMICS_365
- SAGE_ZA_CLOUD_ACCOUNTING
- MYOB_BUSINESS
- WAVE
- ODOO_ACCOUNTING
- NETSUITE
- WAFEQ
- MEKARI_JURNAL
- BUSY
- ROOTFI_SANDBOX
- QOYOD
- SHOPIFY
- STRIPE
- PAYPAL
- HUBSPOT
- ZOHO_CRM
- PIPEDRIVE
- WOOCOMMERCE
- BIGCOMMERCE
- OTHER
State:
type: string
example: CA
description: >-
2-letter code for each state. Suffix of the ISO 3166-2 code. Ex: CA, NY,
TX.
Country:
type: string
example: US
description: 'ISO 3166 2-letter country code. Ex: US, IN, GB.'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````