POST /api/v1/tax/calculate

Calculate US sales tax for one or more lines.

Request template for this operation

Set ITMS_API_KEY to a key with the scope shown above. Use a sandbox key while developing. Create request.json from this operation’s OpenAPI request schema for cURL, and set ITMS_REQUEST_BODY to that same JSON for JavaScript or Python. Do not copy production customer data into a sandbox request.

cURL

curl --request POST \
  --url "${ITMS_BASE_URL:-https://prophit.ai}/api/v1/tax/calculate" \
  --header "Authorization: Bearer ${ITMS_API_KEY}" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

JavaScript (Node 18+)

const requiredEnv = (name) => {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name} before running this request.`);
  return value;
};
const requestBody = JSON.parse(requiredEnv("ITMS_REQUEST_BODY"));
const path = `/api/v1/tax/calculate`;
const response = await fetch(`${process.env.ITMS_BASE_URL ?? 'https://prophit.ai'}${path}`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${requiredEnv('ITMS_API_KEY')}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(requestBody),
});
const requestId = response.headers.get('x-request-id');
const payload = response.status === 204 ? null : await response.json();
if (!response.ok) throw Object.assign(new Error(payload?.error?.message), { code: payload?.error?.code, requestId });
console.log({ requestId, payload });

Python

import os
import json
import requests

def required_env(name):
    value = os.getenv(name)
    if not value:
        raise RuntimeError(f"Set {name} before running this request.")
    return value

request_body = json.loads(required_env("ITMS_REQUEST_BODY"))
path = f"/api/v1/tax/calculate"
response = requests.request(
    "POST",
    f"{os.getenv('ITMS_BASE_URL', 'https://prophit.ai')}{path}",
    headers={
        "Authorization": f"Bearer {required_env('ITMS_API_KEY')}",
    },
    json=request_body,
    timeout=30,
)
request_id = response.headers.get("x-request-id")
if not response.ok:
    error = response.json().get("error", {})
    raise RuntimeError(f"{error.get('code')}: {error.get('message')} (request_id={request_id})")
print(None if response.status_code == 204 else response.json())

Request and response shape

Request

transaction_date, ship_to, lines[]; optional customer_code, ship_from, bill_to, currency, discount, validation_mode, calculation_type. Supported fact-aware treatments may accept lines[].qualifying_use_percentage (0–100) when the caller has the required documentation. Texas remote sellers may explicitly send tx_single_local_use_tax_rate_elected=true after making that election; ITMS never infers it.

Response

Sales tax returns liability_basis=gross_expected_tax. calculation_type=consumer_use|vendor_use|reverse_charge (or legacy use_tax=true for consumer use only) returns expected tax, tax paid, and net use-tax liability. A seller-imposed tax such as Hawaii GET returns liability_basis=seller_gross_receipts with tax_incidence=seller_gross_receipts, no buyer tax, and the seller amount in total_seller_liability_tax. All modes include per-line jurisdiction metadata and warnings.

The versioned OpenAPI document is the machine-readable authority for required fields, types, enums, response schemas, and status codes. This page supplies the product and workflow context around that contract.

Integration contract

1. Use a key whose environment, organization, location, and scopes match the operation.
2. Validate the request against the customer OpenAPI document; never infer omitted required facts.
3. For create, apply, commit, refund, adjustment, or replay operations, follow the documented idempotency and duplicate semantics.
4. Persist the response request ID, result authority, warnings, and evidence references needed to reproduce the decision.
5. Handle the machine-readable error envelope and honor rate-limit retry headers.

Related documentation

• Request and response schemas
• Errors and request IDs
• Rate limits and retries
• UI workflow map and authority boundaries