{ "openapi": "3.1.2", "info": { "title": "Sales Tax Calculator API", "version": "1.0.0", "summary": "Calculate sales tax and save transaction records.", "description": "Use this API to calculate sales tax, VAT, and GST where supported. Save transactions, record adjustments, submit batches, and check coverage. Each sales tax calculation response includes an outcome; check it before using the returned amounts. The API does not provide legal advice.", "license": { "name": "Proprietary", "url": "https://salestaxcalculatorapi.com/terms" } }, "servers": [ { "url": "https://api.salestaxcalculatorapi.com", "description": "Stable customer API origin." } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Calculations", "description": "Create and retrieve sales tax calculations. Check the outcome before using returned amounts." }, { "name": "Transactions", "description": "Save completed sales tax calculations and record adjustments against them." }, { "name": "Batches", "description": "Submit up to 100 sales tax calculations together and retrieve their results." }, { "name": "Coverage", "description": "Check whether the API supports a transaction's details and date." } ], "paths": { "/v1/calculations": { "post": { "operationId": "createCalculation", "tags": [ "Calculations" ], "summary": "Create a sales tax calculation", "description": "Creates and saves a sales tax calculation from seller, customer, item, and transaction details. Check the outcome to see whether the result is final, needs review, or is unsupported.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ExpandAudit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculationCreate" }, "examples": { "oneLineSaas": { "summary": "One-line SaaS sales tax calculation", "value": { "reference": "order-1001", "transaction_date": "2026-08-29", "currency": "CAD", "tax_behavior": "exclusive", "billing_event": "subscription_start", "seller": { "country": "CA", "channel_role": "direct_legal_supplier", "registrations": [ { "country": "CA", "state": "ON", "type": "gst_hst", "effective_from": "2026-01-01" } ] }, "customer": { "type": "consumer", "address": { "country": "CA", "state": "ON", "postal_code": "M5V 2T6" } }, "lines": [ { "reference": "subscription", "amount": "100.00", "quantity": "1", "tax_code": "saas" } ] } } } } } }, "responses": { "201": { "description": "The sales tax calculation was saved.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Calculation" }, "examples": { "calculated": { "$ref": "#/components/examples/CalculationResponse" } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl --request POST \\\n --url \"https://api.salestaxcalculatorapi.com/v1/calculations\" \\\n --header \"Authorization: Bearer $SALESTAX_API_KEY\"\n --header \"Content-Type: application/json\" \\\n --header \"Idempotency-Key: order-1001-calc\" \\\n --data '{\"reference\":\"order-1001\",\"transaction_date\":\"2026-08-29\",\"currency\":\"CAD\",\"tax_behavior\":\"exclusive\",\"billing_event\":\"subscription_start\",\"seller\":{\"country\":\"CA\",\"channel_role\":\"direct_legal_supplier\",\"registrations\":[{\"country\":\"CA\",\"state\":\"ON\",\"type\":\"gst_hst\",\"effective_from\":\"2026-01-01\"}]},\"customer\":{\"type\":\"consumer\",\"address\":{\"country\":\"CA\",\"state\":\"ON\",\"postal_code\":\"M5V 2T6\"}},\"lines\":[{\"reference\":\"subscription\",\"amount\":\"100.00\",\"quantity\":\"1\",\"tax_code\":\"saas\"}]}'" }, { "lang": "Node.js", "label": "Node.js", "source": "import { SalesTaxClient } from 'salestax-node'\n\nconst client = SalesTaxClient.fromEnv()\nconst result = await client.calculations.create({\n \"reference\": \"order-1001\",\n \"transaction_date\": \"2026-08-29\",\n \"currency\": \"CAD\",\n \"tax_behavior\": \"exclusive\",\n \"billing_event\": \"subscription_start\",\n \"seller\": {\n \"country\": \"CA\",\n \"channel_role\": \"direct_legal_supplier\",\n \"registrations\": [\n {\n \"country\": \"CA\",\n \"state\": \"ON\",\n \"type\": \"gst_hst\",\n \"effective_from\": \"2026-01-01\"\n }\n ]\n },\n \"customer\": {\n \"type\": \"consumer\",\n \"address\": {\n \"country\": \"CA\",\n \"state\": \"ON\",\n \"postal_code\": \"M5V 2T6\"\n }\n },\n \"lines\": [\n {\n \"reference\": \"subscription\",\n \"amount\": \"100.00\",\n \"quantity\": \"1\",\n \"tax_code\": \"saas\"\n }\n ]\n}, { idempotencyKey: \"order-1001-calc\" })\nconsole.log(JSON.stringify(result, null, 2))" }, { "lang": "Python", "label": "Python", "source": "from salestax import SalesTaxClient\n\nwith SalesTaxClient() as client:\n result = client.calculations.create(**{\n \"reference\": \"order-1001\",\n \"transaction_date\": \"2026-08-29\",\n \"currency\": \"CAD\",\n \"tax_behavior\": \"exclusive\",\n \"billing_event\": \"subscription_start\",\n \"seller\": {\n \"country\": \"CA\",\n \"channel_role\": \"direct_legal_supplier\",\n \"registrations\": [\n {\n \"country\": \"CA\",\n \"state\": \"ON\",\n \"type\": \"gst_hst\",\n \"effective_from\": \"2026-01-01\"\n }\n ]\n },\n \"customer\": {\n \"type\": \"consumer\",\n \"address\": {\n \"country\": \"CA\",\n \"state\": \"ON\",\n \"postal_code\": \"M5V 2T6\"\n }\n },\n \"lines\": [\n {\n \"reference\": \"subscription\",\n \"amount\": \"100.00\",\n \"quantity\": \"1\",\n \"tax_code\": \"saas\"\n }\n ]\n}, idempotency_key=\"order-1001-calc\")\n print(result)" } ] } }, "/v1/calculations/{calculation_id}": { "get": { "operationId": "getCalculation", "tags": [ "Calculations" ], "summary": "Retrieve a sales tax calculation", "description": "Returns a saved sales tax calculation from your workspace.", "parameters": [ { "$ref": "#/components/parameters/CalculationId" }, { "$ref": "#/components/parameters/ExpandAudit" } ], "responses": { "200": { "description": "The sales tax calculation.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Calculation" }, "examples": { "calculation": { "$ref": "#/components/examples/CalculationResponse" } } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl --request GET \\\n --url \"https://api.salestaxcalculatorapi.com/v1/calculations/calc_01J6A3S8Z6K4M6T2Y2W9M5X8Q0\" \\\n --header \"Authorization: Bearer $SALESTAX_API_KEY\"" }, { "lang": "Node.js", "label": "Node.js", "source": "import { SalesTaxClient } from 'salestax-node'\n\nconst client = SalesTaxClient.fromEnv()\nconst result = await client.calculations.get(\"calc_01J6A3S8Z6K4M6T2Y2W9M5X8Q0\")\nconsole.log(JSON.stringify(result, null, 2))" }, { "lang": "Python", "label": "Python", "source": "from salestax import SalesTaxClient\n\nwith SalesTaxClient() as client:\n result = client.calculations.get(\"calc_01J6A3S8Z6K4M6T2Y2W9M5X8Q0\")\n print(result)" } ] } }, "/v1/transactions": { "post": { "operationId": "createTransaction", "tags": [ "Transactions" ], "summary": "Create a transaction", "description": "Saves a completed sales tax calculation as a transaction with its original line items and tax amounts. Transactions cannot be edited; use an adjustment to record a refund or correction.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ExpandAudit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionCreate" }, "examples": { "finalizeSale": { "summary": "Record the completed sales tax calculation after payment succeeds", "value": { "calculation_id": "calc_01J6A3S8Z6K4M6T2Y2W9M5X8Q0", "reference": "order-1001" } } } } } }, "responses": { "201": { "description": "The transaction record was saved.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "transaction": { "$ref": "#/components/examples/TransactionResponse" } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl --request POST \\\n --url \"https://api.salestaxcalculatorapi.com/v1/transactions\" \\\n --header \"Authorization: Bearer $SALESTAX_API_KEY\"\n --header \"Content-Type: application/json\" \\\n --header \"Idempotency-Key: order-1001-txn\" \\\n --data '{\"calculation_id\":\"calc_01J6A3S8Z6K4M6T2Y2W9M5X8Q0\",\"reference\":\"order-1001\"}'" }, { "lang": "Node.js", "label": "Node.js", "source": "import { SalesTaxClient } from 'salestax-node'\n\nconst client = SalesTaxClient.fromEnv()\nconst result = await client.transactions.create({\n \"calculation_id\": \"calc_01J6A3S8Z6K4M6T2Y2W9M5X8Q0\",\n \"reference\": \"order-1001\"\n}, { idempotencyKey: \"order-1001-txn\" })\nconsole.log(JSON.stringify(result, null, 2))" }, { "lang": "Python", "label": "Python", "source": "from salestax import SalesTaxClient\n\nwith SalesTaxClient() as client:\n result = client.transactions.create(calculation_id=\"calc_01J6A3S8Z6K4M6T2Y2W9M5X8Q0\", reference=\"order-1001\", idempotency_key=\"order-1001-txn\")\n print(result)" } ] } }, "/v1/transactions/{transaction_id}": { "get": { "operationId": "getTransaction", "tags": [ "Transactions" ], "summary": "Retrieve a transaction", "description": "Returns a saved transaction from your workspace.", "parameters": [ { "$ref": "#/components/parameters/TransactionId" }, { "$ref": "#/components/parameters/ExpandAudit" } ], "responses": { "200": { "description": "The transaction.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "transaction": { "$ref": "#/components/examples/TransactionResponse" } } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl --request GET \\\n --url \"https://api.salestaxcalculatorapi.com/v1/transactions/txn_01J6A4DN7ZAVC0QJ2KP6NQYB8M\" \\\n --header \"Authorization: Bearer $SALESTAX_API_KEY\"" }, { "lang": "Node.js", "label": "Node.js", "source": "import { SalesTaxClient } from 'salestax-node'\n\nconst client = SalesTaxClient.fromEnv()\nconst result = await client.transactions.get(\"txn_01J6A4DN7ZAVC0QJ2KP6NQYB8M\")\nconsole.log(JSON.stringify(result, null, 2))" }, { "lang": "Python", "label": "Python", "source": "from salestax import SalesTaxClient\n\nwith SalesTaxClient() as client:\n result = client.transactions.get(\"txn_01J6A4DN7ZAVC0QJ2KP6NQYB8M\")\n print(result)" } ] } }, "/v1/transactions/{transaction_id}/adjustments": { "post": { "operationId": "createTransactionAdjustment", "tags": [ "Transactions" ], "summary": "Create an adjustment", "description": "Records a refund or correction by reversing amounts from the original line items and tax components. Combined adjustments cannot exceed the amounts still available to reverse.", "parameters": [ { "$ref": "#/components/parameters/TransactionId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ExpandAudit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentCreate" }, "examples": { "partialRefund": { "summary": "Refund part of a saved sales tax transaction", "value": { "reference": "refund-1001", "reason": "refund", "lines": [ { "line_id": "line_01J6A3T26X8BS4Y8XJKZ0H8F3P", "amount": "40.00" } ] } } } } } }, "responses": { "201": { "description": "The adjustment was saved.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Adjustment" }, "examples": { "adjustment": { "$ref": "#/components/examples/AdjustmentResponse" } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl --request POST \\\n --url \"https://api.salestaxcalculatorapi.com/v1/transactions/txn_01J6A4DN7ZAVC0QJ2KP6NQYB8M/adjustments\" \\\n --header \"Authorization: Bearer $SALESTAX_API_KEY\"\n --header \"Content-Type: application/json\" \\\n --header \"Idempotency-Key: refund-1001-001\" \\\n --data '{\"reference\":\"refund-1001\",\"reason\":\"refund\",\"lines\":[{\"line_id\":\"line_01J6A3T26X8BS4Y8XJKZ0H8F3P\",\"amount\":\"40.00\"}]}'" }, { "lang": "Node.js", "label": "Node.js", "source": "import { SalesTaxClient } from 'salestax-node'\n\nconst client = SalesTaxClient.fromEnv()\nconst result = await client.transactions.adjustments.create(\"txn_01J6A4DN7ZAVC0QJ2KP6NQYB8M\", {\n \"reference\": \"refund-1001\",\n \"reason\": \"refund\",\n \"lines\": [\n {\n \"line_id\": \"line_01J6A3T26X8BS4Y8XJKZ0H8F3P\",\n \"amount\": \"40.00\"\n }\n ]\n}, { idempotencyKey: \"refund-1001-001\" })\nconsole.log(JSON.stringify(result, null, 2))" }, { "lang": "Python", "label": "Python", "source": "from salestax import SalesTaxClient\n\nwith SalesTaxClient() as client:\n result = client.transactions.adjustments.create(\"txn_01J6A4DN7ZAVC0QJ2KP6NQYB8M\", reference=\"refund-1001\", reason=\"refund\", lines=[\n {\n \"line_id\": \"line_01J6A3T26X8BS4Y8XJKZ0H8F3P\",\n \"amount\": \"40.00\"\n }\n], idempotency_key=\"refund-1001-001\")\n print(result)" } ] }, "get": { "operationId": "listTransactionAdjustments", "tags": [ "Transactions" ], "summary": "List transaction adjustments", "description": "Returns adjustments for this transaction, newest first. Use the cursor to get the next page.", "parameters": [ { "$ref": "#/components/parameters/TransactionId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/StartingAfter" }, { "$ref": "#/components/parameters/ExpandAudit" } ], "responses": { "200": { "description": "A page of transaction adjustments.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentPage" }, "examples": { "adjustments": { "$ref": "#/components/examples/AdjustmentPageResponse" } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl --request GET \\\n --url \"https://api.salestaxcalculatorapi.com/v1/transactions/txn_01J6A4DN7ZAVC0QJ2KP6NQYB8M/adjustments\" \\\n --header \"Authorization: Bearer $SALESTAX_API_KEY\"" }, { "lang": "Node.js", "label": "Node.js", "source": "import { SalesTaxClient } from 'salestax-node'\n\nconst client = SalesTaxClient.fromEnv()\nconst result = await client.transactions.adjustments.list(\"txn_01J6A4DN7ZAVC0QJ2KP6NQYB8M\")\nconsole.log(JSON.stringify(result, null, 2))" }, { "lang": "Python", "label": "Python", "source": "from salestax import SalesTaxClient\n\nwith SalesTaxClient() as client:\n result = client.transactions.adjustments.list(\"txn_01J6A4DN7ZAVC0QJ2KP6NQYB8M\")\n print(result)" } ] } }, "/v1/transactions/{transaction_id}/adjustments/{adjustment_id}": { "get": { "operationId": "getTransactionAdjustment", "tags": [ "Transactions" ], "summary": "Retrieve an adjustment", "description": "Returns an adjustment from the specified transaction.", "parameters": [ { "$ref": "#/components/parameters/TransactionId" }, { "$ref": "#/components/parameters/AdjustmentId" }, { "$ref": "#/components/parameters/ExpandAudit" } ], "responses": { "200": { "description": "The adjustment.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Adjustment" }, "examples": { "adjustment": { "$ref": "#/components/examples/AdjustmentResponse" } } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl --request GET \\\n --url \"https://api.salestaxcalculatorapi.com/v1/transactions/txn_01J6A4DN7ZAVC0QJ2KP6NQYB8M/adjustments/adj_01J6A5PFTFM2SMT5KRFN7K2R6A\" \\\n --header \"Authorization: Bearer $SALESTAX_API_KEY\"" }, { "lang": "Node.js", "label": "Node.js", "source": "import { SalesTaxClient } from 'salestax-node'\n\nconst client = SalesTaxClient.fromEnv()\nconst result = await client.transactions.adjustments.get(\"txn_01J6A4DN7ZAVC0QJ2KP6NQYB8M\", \"adj_01J6A5PFTFM2SMT5KRFN7K2R6A\")\nconsole.log(JSON.stringify(result, null, 2))" }, { "lang": "Python", "label": "Python", "source": "from salestax import SalesTaxClient\n\nwith SalesTaxClient() as client:\n result = client.transactions.adjustments.get(\"txn_01J6A4DN7ZAVC0QJ2KP6NQYB8M\", \"adj_01J6A5PFTFM2SMT5KRFN7K2R6A\")\n print(result)" } ] } }, "/v1/calculation-batches": { "post": { "operationId": "createCalculationBatch", "tags": [ "Batches" ], "summary": "Create a sales tax calculation batch", "description": "Saves and queues 1 to 100 sales tax calculations for background processing. The response includes a batch ID.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculationBatchCreate" }, "examples": { "erpImport": { "summary": "Submit sales tax calculations as a batch", "value": { "reference": "erp-import-2026-08", "calculations": [ { "reference": "invoice-1001", "transaction_date": "2026-08-29", "currency": "CAD", "tax_behavior": "exclusive", "billing_event": "subscription_start", "seller": { "country": "CA", "channel_role": "direct_legal_supplier", "registrations": [ { "country": "CA", "state": "ON", "type": "gst_hst", "effective_from": "2026-01-01" } ] }, "customer": { "type": "consumer", "address": { "country": "CA", "state": "ON", "postal_code": "M5V 2T6" } }, "lines": [ { "reference": "subscription", "amount": "100.00", "quantity": "1", "tax_code": "saas" } ] } ] } } } } } }, "responses": { "202": { "description": "The batch was saved and queued for processing.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" }, "Location": { "description": "Canonical URL for the accepted batch.", "schema": { "type": "string", "format": "uri-reference" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculationBatch" }, "examples": { "accepted": { "$ref": "#/components/examples/CalculationBatchAccepted" } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Unprocessable" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl --request POST \\\n --url \"https://api.salestaxcalculatorapi.com/v1/calculation-batches\" \\\n --header \"Authorization: Bearer $SALESTAX_API_KEY\"\n --header \"Content-Type: application/json\" \\\n --header \"Idempotency-Key: erp-import-2026-08\" \\\n --data '{\"reference\":\"erp-import-2026-08\",\"calculations\":[{\"reference\":\"invoice-1001\",\"transaction_date\":\"2026-08-29\",\"currency\":\"CAD\",\"tax_behavior\":\"exclusive\",\"billing_event\":\"subscription_start\",\"seller\":{\"country\":\"CA\",\"channel_role\":\"direct_legal_supplier\",\"registrations\":[{\"country\":\"CA\",\"state\":\"ON\",\"type\":\"gst_hst\",\"effective_from\":\"2026-01-01\"}]},\"customer\":{\"type\":\"consumer\",\"address\":{\"country\":\"CA\",\"state\":\"ON\",\"postal_code\":\"M5V 2T6\"}},\"lines\":[{\"reference\":\"subscription\",\"amount\":\"100.00\",\"quantity\":\"1\",\"tax_code\":\"saas\"}]}]}'" }, { "lang": "Node.js", "label": "Node.js", "source": "import { SalesTaxClient } from 'salestax-node'\n\nconst client = SalesTaxClient.fromEnv()\nconst result = await client.calculations.createBatch({\n \"reference\": \"erp-import-2026-08\",\n \"calculations\": [\n {\n \"reference\": \"invoice-1001\",\n \"transaction_date\": \"2026-08-29\",\n \"currency\": \"CAD\",\n \"tax_behavior\": \"exclusive\",\n \"billing_event\": \"subscription_start\",\n \"seller\": {\n \"country\": \"CA\",\n \"channel_role\": \"direct_legal_supplier\",\n \"registrations\": [\n {\n \"country\": \"CA\",\n \"state\": \"ON\",\n \"type\": \"gst_hst\",\n \"effective_from\": \"2026-01-01\"\n }\n ]\n },\n \"customer\": {\n \"type\": \"consumer\",\n \"address\": {\n \"country\": \"CA\",\n \"state\": \"ON\",\n \"postal_code\": \"M5V 2T6\"\n }\n },\n \"lines\": [\n {\n \"reference\": \"subscription\",\n \"amount\": \"100.00\",\n \"quantity\": \"1\",\n \"tax_code\": \"saas\"\n }\n ]\n }\n ]\n}, { idempotencyKey: \"erp-import-2026-08\" })\nconsole.log(JSON.stringify(result, null, 2))" }, { "lang": "Python", "label": "Python", "source": "from salestax import SalesTaxClient\n\nwith SalesTaxClient() as client:\n result = client.calculations.create_batch([\n {\n \"reference\": \"invoice-1001\",\n \"transaction_date\": \"2026-08-29\",\n \"currency\": \"CAD\",\n \"tax_behavior\": \"exclusive\",\n \"billing_event\": \"subscription_start\",\n \"seller\": {\n \"country\": \"CA\",\n \"channel_role\": \"direct_legal_supplier\",\n \"registrations\": [\n {\n \"country\": \"CA\",\n \"state\": \"ON\",\n \"type\": \"gst_hst\",\n \"effective_from\": \"2026-01-01\"\n }\n ]\n },\n \"customer\": {\n \"type\": \"consumer\",\n \"address\": {\n \"country\": \"CA\",\n \"state\": \"ON\",\n \"postal_code\": \"M5V 2T6\"\n }\n },\n \"lines\": [\n {\n \"reference\": \"subscription\",\n \"amount\": \"100.00\",\n \"quantity\": \"1\",\n \"tax_code\": \"saas\"\n }\n ]\n }\n], reference=\"erp-import-2026-08\", idempotency_key=\"erp-import-2026-08\")\n print(result)" } ] } }, "/v1/calculation-batches/{batch_id}": { "get": { "operationId": "getCalculationBatch", "tags": [ "Batches" ], "summary": "Retrieve a sales tax calculation batch", "description": "Returns the batch status and the results available so far.", "parameters": [ { "$ref": "#/components/parameters/BatchId" }, { "$ref": "#/components/parameters/ExpandAudit" } ], "responses": { "200": { "description": "The batch.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "description": "Suggested polling delay in seconds while work remains.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculationBatch" }, "examples": { "partiallyFailed": { "$ref": "#/components/examples/CalculationBatchPartial" } } } } }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl --request GET \\\n --url \"https://api.salestaxcalculatorapi.com/v1/calculation-batches/batch_01J6A6X3DWHGCY7G2XXEXAMPLE\" \\\n --header \"Authorization: Bearer $SALESTAX_API_KEY\"" }, { "lang": "Node.js", "label": "Node.js", "source": "import { SalesTaxClient } from 'salestax-node'\n\nconst client = SalesTaxClient.fromEnv()\nconst result = await client.batches.get(\"batch_01J6A6X3DWHGCY7G2XXEXAMPLE\")\nconsole.log(JSON.stringify(result, null, 2))" }, { "lang": "Python", "label": "Python", "source": "from salestax import SalesTaxClient\n\nwith SalesTaxClient() as client:\n result = client.batches.get(\"batch_01J6A6X3DWHGCY7G2XXEXAMPLE\")\n print(result)" } ] } }, "/v1/coverage": { "get": { "operationId": "checkCoverage", "tags": [ "Coverage" ], "summary": "Check coverage", "description": "Checks whether the API supports the supplied jurisdiction, item tax code, transaction type, customer type, and date. A country list alone does not confirm support.", "parameters": [ { "name": "country", "in": "query", "required": true, "description": "ISO 3166-1 alpha-2 country code.", "schema": { "$ref": "#/components/schemas/CountryCode" } }, { "name": "state", "in": "query", "required": false, "description": "Subdivision code when applicable.", "schema": { "$ref": "#/components/schemas/SubdivisionCode" } }, { "name": "tax_code", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/TaxCode" } }, { "name": "transaction_type", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/TransactionType" } }, { "name": "customer_type", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/CustomerType" } }, { "name": "date", "in": "query", "required": false, "description": "ISO date to evaluate. Defaults to the server's current UTC date.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "All three coverage outcomes use HTTP 200. Check the response's outcome field.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coverage" }, "examples": { "qualified": { "$ref": "#/components/examples/CoverageResponse" } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/AuthenticationRequired" }, "403": { "$ref": "#/components/responses/PermissionDenied" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl --request GET \\\n --url \"https://api.salestaxcalculatorapi.com/v1/coverage?country=CA&state=ON&tax_code=saas&transaction_type=sale&customer_type=consumer&date=2026-08-29\" \\\n --header \"Authorization: Bearer $SALESTAX_API_KEY\"" }, { "lang": "Node.js", "label": "Node.js", "source": "import { SalesTaxClient } from 'salestax-node'\n\nconst client = SalesTaxClient.fromEnv()\nconst result = await client.coverage.check({ country: \"CA\", state: \"ON\", tax_code: \"saas\", transaction_type: \"sale\", customer_type: \"consumer\", date: \"2026-08-29\" })\nconsole.log(JSON.stringify(result, null, 2))" }, { "lang": "Python", "label": "Python", "source": "from salestax import SalesTaxClient\n\nwith SalesTaxClient() as client:\n result = client.coverage.check(country=\"CA\", state=\"ON\", tax_code=\"saas\", transaction_type=\"sale\", customer_type=\"consumer\", on_date=\"2026-08-29\")\n print(result)" } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "stca_ API key", "description": "Use a server-side API key. Never embed a secret key in browser or mobile application code." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "A caller-generated key. Reusing it with the same canonical request returns the original effect. Reusing it with different content returns a conflict.", "schema": { "type": "string", "minLength": 8, "maxLength": 255, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,254}$" } }, "ExpandAudit": { "name": "expand", "in": "query", "required": false, "description": "Set to audit for an authorized customer-safe audit expansion.", "schema": { "type": "string", "const": "audit" } }, "CalculationId": { "name": "calculation_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/CalculationId" } }, "TransactionId": { "name": "transaction_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TransactionId" } }, "AdjustmentId": { "name": "adjustment_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/AdjustmentId" } }, "BatchId": { "name": "batch_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/BatchId" } }, "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "StartingAfter": { "name": "starting_after", "in": "query", "required": false, "description": "Cursor returned by the previous page.", "schema": { "type": "string", "minLength": 16, "maxLength": 512 } } }, "headers": { "RequestId": { "description": "Stable identifier for support and request tracing.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "IdempotentReplayed": { "description": "True when the original response was replayed without another business or billing effect.", "schema": { "type": "boolean" } }, "RateLimitLimit": { "description": "Maximum requests in the active rate-limit window.", "schema": { "type": "integer", "minimum": 0 } }, "RateLimitRemaining": { "description": "Requests remaining in the active rate-limit window.", "schema": { "type": "integer", "minimum": 0 } } }, "responses": { "InvalidRequest": { "description": "The request shape, parameter, or header is invalid.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalidRequest": { "$ref": "#/components/examples/InvalidRequestProblem" } } } } }, "AuthenticationRequired": { "description": "A valid API key is required.", "headers": { "WWW-Authenticate": { "schema": { "type": "string", "const": "Bearer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "PermissionDenied": { "description": "The authenticated key cannot perform this operation.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "The resource does not exist in the authenticated workspace.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Conflict": { "description": "The request conflicts with an existing idempotency key or the current state of a saved record.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unprocessable": { "description": "The request is valid, but the API cannot complete it. For example, the facts may not qualify or an adjustment may exceed the amounts left to reverse.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "RateLimited": { "description": "The request exceeded an API safety limit. It did not count toward API usage.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unavailable": { "description": "A required service is unavailable, so the API could not process the request.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "examples": { "CalculationResponse": { "summary": "Supported sales tax calculation", "value": { "id": "calc_01J6A3S8Z6K4M6T2Y2W9M5X8Q0", "object": "calculation", "reference": "order-1001", "outcome": "calculated", "currency": "CAD", "subtotal": "100.00", "taxable_amount": "100.00", "tax": "13.00", "total": "113.00", "lines": [ { "id": "line_01J6A3T26X8BS4Y8XJKZ0H8F3P", "reference": "subscription", "outcome": "calculated", "subtotal": "100.00", "taxable_amount": "100.00", "tax": "13.00", "total": "113.00", "explanation": "Tax was calculated for this sale." } ], "explanation": "Tax was calculated for this sale.", "request_id": "req_01J6A3RZ1HT2K3W2X8R7P1J4C9", "created_at": "2026-08-29T12:00:00Z" } }, "TransactionResponse": { "summary": "Finalized transaction", "value": { "id": "txn_01J6A4DN7ZAVC0QJ2KP6NQYB8M", "object": "transaction", "reference": "order-1001", "calculation_id": "calc_01J6A3S8Z6K4M6T2Y2W9M5X8Q0", "currency": "CAD", "subtotal": "100.00", "taxable_amount": "100.00", "tax": "13.00", "total": "113.00", "adjusted_amount": "0.00", "adjusted_tax": "0.00", "request_id": "req_01J6A3RZ1HT2K3W2X8R7P1J4C9", "created_at": "2026-08-29T12:01:00Z" } }, "AdjustmentResponse": { "summary": "Partial refund adjustment", "value": { "id": "adj_01J6A5PFTFM2SMT5KRFN7K2R6A", "object": "adjustment", "transaction_id": "txn_01J6A4DN7ZAVC0QJ2KP6NQYB8M", "reference": "refund-1001", "reason": "refund", "currency": "CAD", "subtotal": "-40.00", "tax": "-5.20", "total": "-45.20", "lines": [ { "line_id": "line_01J6A3T26X8BS4Y8XJKZ0H8F3P", "subtotal": "-40.00", "tax": "-5.20", "total": "-45.20" } ], "request_id": "req_01J6A3RZ1HT2K3W2X8R7P1J4C9", "created_at": "2026-08-30T09:30:00Z" } }, "AdjustmentPageResponse": { "summary": "One adjustment in the transaction history", "value": { "object": "list", "items": [ { "id": "adj_01J6A5PFTFM2SMT5KRFN7K2R6A", "object": "adjustment", "transaction_id": "txn_01J6A4DN7ZAVC0QJ2KP6NQYB8M", "reference": "refund-1001", "reason": "refund", "currency": "CAD", "subtotal": "-40.00", "tax": "-5.20", "total": "-45.20", "lines": [ { "line_id": "line_01J6A3T26X8BS4Y8XJKZ0H8F3P", "subtotal": "-40.00", "tax": "-5.20", "total": "-45.20" } ], "request_id": "req_01J6A3RZ1HT2K3W2X8R7P1J4C9", "created_at": "2026-08-30T09:30:00Z" } ], "has_more": false, "next_cursor": null } }, "CalculationBatchAccepted": { "summary": "Batch accepted for processing", "value": { "id": "batch_01J6A6X3DWHGCY7G2XXE5MPA2R", "object": "calculation_batch", "reference": "erp-import-2026-08", "status": "queued", "total_count": 1, "succeeded_count": 0, "failed_count": 0, "items": [ { "index": 0, "status": "queued" } ], "request_id": "req_01J6A3RZ1HT2K3W2X8R7P1J4C9", "created_at": "2026-08-29T12:01:00Z" } }, "CalculationBatchPartial": { "summary": "Batch with one successful and one failed item", "value": { "id": "batch_01J6A6X3DWHGCY7G2XXE5MPA2R", "object": "calculation_batch", "reference": "erp-import-2026-08", "status": "partially_failed", "total_count": 2, "succeeded_count": 1, "failed_count": 1, "items": [ { "index": 0, "status": "succeeded", "calculation": { "id": "calc_01J6A3S8Z6K4M6T2Y2W9M5X8Q0", "object": "calculation", "reference": "order-1001", "outcome": "calculated", "currency": "CAD", "subtotal": "100.00", "taxable_amount": "100.00", "tax": "13.00", "total": "113.00", "lines": [ { "id": "line_01J6A3T26X8BS4Y8XJKZ0H8F3P", "reference": "subscription", "outcome": "calculated", "subtotal": "100.00", "taxable_amount": "100.00", "tax": "13.00", "total": "113.00", "explanation": "Tax was calculated for this sale." } ], "explanation": "Tax was calculated for this sale.", "request_id": "req_01J6A3RZ1HT2K3W2X8R7P1J4C9", "created_at": "2026-08-29T12:00:00Z" } }, { "index": 1, "status": "failed", "problem": { "type": "https://api.salestaxcalculatorapi.com/problems/invalid_request", "title": "Invalid request", "status": 400, "detail": "The amount field is invalid.", "instance": "/v1/calculation-batches/batch_01J6A6X3DWHGCY7G2XXE5MPA2R", "code": "invalid_request", "request_id": "req_01J6A3RZ1HT2K3W2X8R7P1J4C9", "retryable": false, "errors": [ { "pointer": "/lines/0/amount", "message": "Use a decimal string with the currency scale." } ] } } ], "request_id": "req_01J6A3RZ1HT2K3W2X8R7P1J4C9", "created_at": "2026-08-29T12:01:00Z", "completed_at": "2026-08-29T12:02:00Z" } }, "CoverageResponse": { "summary": "Coverage in Ontario, Canada", "value": { "object": "coverage", "qualification": "qualified", "country": "CA", "state": "ON", "tax_code": "saas", "transaction_type": "sale", "customer_type": "consumer", "calculation": "supported", "obligation": "derived", "tax_id_validation": "not_available", "evidence_required": [ "customer_address" ], "source_basis": "official", "effective_from": "2026-01-01", "effective_through": null, "as_of": "2026-08-29", "next_review_due_at": null, "message": "This combination is available for calculation with the supplied transaction facts.", "request_id": "req_01J6A3RZ1HT2K3W2X8R7P1J4C9" } }, "InvalidRequestProblem": { "summary": "Malformed request body", "value": { "type": "https://api.salestaxcalculatorapi.com/problems/invalid_request", "title": "Invalid request", "status": 400, "detail": "The request body must be valid JSON.", "instance": "/v1/calculations", "code": "invalid_request", "request_id": "req_01J6A3RZ1HT2K3W2X8R7P1J4C9", "retryable": false } } }, "schemas": { "Currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code." }, "Money": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,3})?$", "description": "Non-negative decimal amount in the currency's ordinary unit. Currency-specific scale is enforced." }, "SignedMoney": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]{1,3})?$", "description": "Signed decimal amount in the currency's ordinary unit." }, "Quantity": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$", "description": "Positive decimal quantity. Defaults to 1 when omitted.", "not": { "const": "0" } }, "Rate": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{1,8})?$" }, "CountryCode": { "type": "string", "pattern": "^[A-Z]{2}$" }, "SubdivisionCode": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[A-Z0-9-]+$" }, "TaxCode": { "type": "string", "minLength": 2, "maxLength": 64, "pattern": "^[a-z][a-z0-9_.-]+$" }, "Reference": { "type": "string", "minLength": 1, "maxLength": 200 }, "RequestId": { "type": "string", "pattern": "^req_[0-9A-HJKMNP-TV-Z]{26}$" }, "CalculationId": { "type": "string", "pattern": "^calc_[0-9A-HJKMNP-TV-Z]{26}$" }, "CalculationLineId": { "type": "string", "pattern": "^line_[0-9A-HJKMNP-TV-Z]{26}$" }, "TransactionId": { "type": "string", "pattern": "^txn_[0-9A-HJKMNP-TV-Z]{26}$" }, "AdjustmentId": { "type": "string", "pattern": "^adj_[0-9A-HJKMNP-TV-Z]{26}$" }, "BatchId": { "type": "string", "pattern": "^batch_[0-9A-HJKMNP-TV-Z]{26}$" }, "Outcome": { "type": "string", "enum": [ "calculated", "not_taxable", "not_obligated", "reverse_charge_or_self_assess", "exempt", "no_general_tax", "review_required", "unsupported" ] }, "CustomerType": { "type": "string", "enum": [ "consumer", "business", "government", "nonprofit" ] }, "TransactionType": { "type": "string", "enum": [ "sale", "refund", "credit" ] }, "TaxBehavior": { "type": "string", "enum": [ "exclusive", "inclusive" ] }, "BillingEvent": { "type": "string", "enum": [ "one_time_charge", "subscription_start", "subscription_renewal", "metered_usage", "free_trial", "paid_trial", "discount", "proration", "supported_bundle" ] }, "SellerChannelRole": { "type": "string", "enum": [ "direct_legal_supplier", "marketplace_operator", "marketplace_seller", "merchant_of_record", "disclosed_agent", "reseller_principal" ] }, "Address": { "type": "object", "additionalProperties": false, "required": [ "country" ], "properties": { "line1": { "type": "string", "minLength": 1, "maxLength": 200 }, "line2": { "type": "string", "minLength": 1, "maxLength": 200 }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "state": { "$ref": "#/components/schemas/SubdivisionCode" }, "postal_code": { "type": "string", "minLength": 1, "maxLength": 32 }, "country": { "$ref": "#/components/schemas/CountryCode" } } }, "TaxIdInput": { "type": "object", "additionalProperties": false, "required": [ "type", "country", "value" ], "properties": { "type": { "type": "string", "enum": [ "eu_vat", "gb_vat", "gst", "business_tax_id", "other" ] }, "country": { "$ref": "#/components/schemas/CountryCode" }, "value": { "type": "string", "minLength": 2, "maxLength": 64 } } }, "LocationEvidence": { "type": "object", "additionalProperties": false, "required": [ "kind", "country" ], "properties": { "kind": { "type": "string", "enum": [ "billing_address", "ip_address", "payment_method", "self_declaration" ] }, "country": { "$ref": "#/components/schemas/CountryCode" }, "state": { "$ref": "#/components/schemas/SubdivisionCode" } } }, "SellerRegistration": { "type": "object", "additionalProperties": false, "required": [ "country", "type", "effective_from" ], "properties": { "country": { "$ref": "#/components/schemas/CountryCode" }, "state": { "$ref": "#/components/schemas/SubdivisionCode" }, "type": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_.-]*$" }, "effective_from": { "type": "string", "format": "date" }, "effective_to": { "type": "string", "format": "date" } } }, "Seller": { "type": "object", "additionalProperties": false, "required": [ "country", "channel_role", "registrations" ], "properties": { "country": { "$ref": "#/components/schemas/CountryCode" }, "channel_role": { "$ref": "#/components/schemas/SellerChannelRole" }, "registrations": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/SellerRegistration" } } } }, "Customer": { "type": "object", "additionalProperties": false, "required": [ "address" ], "properties": { "type": { "$ref": "#/components/schemas/CustomerType" }, "address": { "$ref": "#/components/schemas/Address" }, "tax_ids": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/TaxIdInput" } }, "location_evidence": { "type": "array", "maxItems": 5, "items": { "$ref": "#/components/schemas/LocationEvidence" } } } }, "CalculationLineCreate": { "type": "object", "additionalProperties": false, "description": "One separately classified line. Amount is the total line amount, not a per-unit price. Quantity is retained for proportional adjustments.", "required": [ "reference", "amount", "tax_code" ], "properties": { "reference": { "$ref": "#/components/schemas/Reference" }, "amount": { "$ref": "#/components/schemas/Money" }, "quantity": { "$ref": "#/components/schemas/Quantity" }, "tax_code": { "$ref": "#/components/schemas/TaxCode" }, "tax_behavior": { "$ref": "#/components/schemas/TaxBehavior" } } }, "CalculationCreate": { "type": "object", "additionalProperties": false, "required": [ "currency", "tax_behavior", "billing_event", "seller", "customer", "lines" ], "properties": { "reference": { "$ref": "#/components/schemas/Reference" }, "transaction_date": { "type": "string", "format": "date", "description": "The commercial transaction date in YYYY-MM-DD form. It defaults to the current UTC date when omitted. Send it explicitly for reproducible sales tax calculations." }, "currency": { "$ref": "#/components/schemas/Currency" }, "tax_behavior": { "$ref": "#/components/schemas/TaxBehavior" }, "billing_event": { "$ref": "#/components/schemas/BillingEvent" }, "seller": { "$ref": "#/components/schemas/Seller" }, "customer": { "$ref": "#/components/schemas/Customer" }, "ship_from": { "$ref": "#/components/schemas/Address" }, "ship_to": { "$ref": "#/components/schemas/Address" }, "lines": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/CalculationLineCreate" } } } }, "CalculationLine": { "type": "object", "additionalProperties": false, "required": [ "id", "reference", "outcome", "subtotal", "taxable_amount", "tax", "total" ], "properties": { "id": { "$ref": "#/components/schemas/CalculationLineId" }, "reference": { "$ref": "#/components/schemas/Reference" }, "outcome": { "$ref": "#/components/schemas/Outcome" }, "subtotal": { "$ref": "#/components/schemas/Money" }, "taxable_amount": { "$ref": "#/components/schemas/Money" }, "tax": { "$ref": "#/components/schemas/Money" }, "total": { "$ref": "#/components/schemas/Money" }, "explanation": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "Jurisdiction": { "type": "object", "additionalProperties": false, "required": [ "country", "level" ], "properties": { "country": { "$ref": "#/components/schemas/CountryCode" }, "state": { "$ref": "#/components/schemas/SubdivisionCode" }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "level": { "type": "string", "enum": [ "country", "state", "province", "county", "city", "district", "special" ] } } }, "TaxComponent": { "type": "object", "additionalProperties": false, "required": [ "jurisdiction", "rate", "taxable_amount", "tax" ], "properties": { "jurisdiction": { "$ref": "#/components/schemas/Jurisdiction" }, "rate": { "$ref": "#/components/schemas/Rate" }, "taxable_amount": { "$ref": "#/components/schemas/SignedMoney" }, "tax": { "$ref": "#/components/schemas/SignedMoney" } } }, "EvidenceResult": { "type": "object", "additionalProperties": false, "required": [ "kind", "status" ], "properties": { "kind": { "type": "string", "enum": [ "customer_address", "ship_from", "ship_to", "tax_id" ] }, "status": { "type": "string", "enum": [ "accepted", "conflicting", "missing", "format_valid", "format_invalid", "valid", "invalid", "not_checked", "provider_unavailable" ] }, "authority": { "type": "string", "minLength": 1, "maxLength": 120 }, "jurisdiction": { "$ref": "#/components/schemas/CountryCode" }, "checked_at": { "type": "string", "format": "date-time" }, "consultation_reference": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "AuditExpansion": { "type": "object", "additionalProperties": false, "required": [ "coverage_as_of", "source_basis", "components", "evidence" ], "properties": { "coverage_as_of": { "type": "string", "format": "date" }, "source_basis": { "type": "string", "enum": [ "official", "licensed" ] }, "effective_from": { "type": "string", "format": "date" }, "effective_through": { "type": [ "string", "null" ], "format": "date" }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/TaxComponent" } }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/EvidenceResult" } } } }, "Calculation": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "outcome", "currency", "subtotal", "taxable_amount", "tax", "total", "lines", "explanation", "request_id", "created_at" ], "properties": { "id": { "$ref": "#/components/schemas/CalculationId" }, "object": { "type": "string", "const": "calculation" }, "reference": { "$ref": "#/components/schemas/Reference" }, "outcome": { "$ref": "#/components/schemas/Outcome" }, "currency": { "$ref": "#/components/schemas/Currency" }, "subtotal": { "$ref": "#/components/schemas/Money" }, "taxable_amount": { "$ref": "#/components/schemas/Money" }, "tax": { "$ref": "#/components/schemas/Money" }, "total": { "$ref": "#/components/schemas/Money" }, "lines": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/CalculationLine" } }, "explanation": { "type": "string", "minLength": 1, "maxLength": 1000 }, "expanded": { "type": "array", "items": { "type": "string", "const": "audit" }, "uniqueItems": true }, "audit": { "$ref": "#/components/schemas/AuditExpansion" }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "created_at": { "type": "string", "format": "date-time" } } }, "TransactionCreate": { "type": "object", "additionalProperties": false, "required": [ "calculation_id", "reference" ], "properties": { "calculation_id": { "$ref": "#/components/schemas/CalculationId" }, "reference": { "$ref": "#/components/schemas/Reference" }, "occurred_at": { "type": "string", "format": "date-time" } } }, "Transaction": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "reference", "calculation_id", "currency", "subtotal", "taxable_amount", "tax", "total", "adjusted_amount", "adjusted_tax", "request_id", "created_at" ], "properties": { "id": { "$ref": "#/components/schemas/TransactionId" }, "object": { "type": "string", "const": "transaction" }, "reference": { "$ref": "#/components/schemas/Reference" }, "calculation_id": { "$ref": "#/components/schemas/CalculationId" }, "currency": { "$ref": "#/components/schemas/Currency" }, "subtotal": { "$ref": "#/components/schemas/Money" }, "taxable_amount": { "$ref": "#/components/schemas/Money" }, "tax": { "$ref": "#/components/schemas/Money" }, "total": { "$ref": "#/components/schemas/Money" }, "adjusted_amount": { "$ref": "#/components/schemas/Money" }, "adjusted_tax": { "$ref": "#/components/schemas/Money" }, "expanded": { "type": "array", "items": { "type": "string", "const": "audit" }, "uniqueItems": true }, "audit": { "$ref": "#/components/schemas/AuditExpansion" }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "created_at": { "type": "string", "format": "date-time" } } }, "AdjustmentLineCreate": { "oneOf": [ { "$ref": "#/components/schemas/AdjustmentAmountLineCreate" }, { "$ref": "#/components/schemas/AdjustmentQuantityLineCreate" } ] }, "AdjustmentAmountLineCreate": { "type": "object", "additionalProperties": false, "required": [ "line_id", "amount" ], "properties": { "line_id": { "$ref": "#/components/schemas/CalculationLineId" }, "amount": { "$ref": "#/components/schemas/Money" } } }, "AdjustmentQuantityLineCreate": { "type": "object", "additionalProperties": false, "required": [ "line_id", "quantity" ], "properties": { "line_id": { "$ref": "#/components/schemas/CalculationLineId" }, "quantity": { "$ref": "#/components/schemas/Quantity" } } }, "AdjustmentCreate": { "type": "object", "additionalProperties": false, "required": [ "reference", "reason", "lines" ], "properties": { "reference": { "$ref": "#/components/schemas/Reference" }, "reason": { "type": "string", "enum": [ "refund", "credit", "correction" ] }, "lines": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/AdjustmentLineCreate" } } } }, "AdjustmentLine": { "type": "object", "additionalProperties": false, "required": [ "line_id", "subtotal", "tax", "total" ], "properties": { "line_id": { "$ref": "#/components/schemas/CalculationLineId" }, "subtotal": { "$ref": "#/components/schemas/SignedMoney" }, "tax": { "$ref": "#/components/schemas/SignedMoney" }, "total": { "$ref": "#/components/schemas/SignedMoney" }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/TaxComponent" } } } }, "Adjustment": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "transaction_id", "reference", "reason", "currency", "subtotal", "tax", "total", "lines", "request_id", "created_at" ], "properties": { "id": { "$ref": "#/components/schemas/AdjustmentId" }, "object": { "type": "string", "const": "adjustment" }, "transaction_id": { "$ref": "#/components/schemas/TransactionId" }, "reference": { "$ref": "#/components/schemas/Reference" }, "reason": { "type": "string", "enum": [ "refund", "credit", "correction" ] }, "currency": { "$ref": "#/components/schemas/Currency" }, "subtotal": { "$ref": "#/components/schemas/SignedMoney" }, "tax": { "$ref": "#/components/schemas/SignedMoney" }, "total": { "$ref": "#/components/schemas/SignedMoney" }, "lines": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/AdjustmentLine" } }, "expanded": { "type": "array", "items": { "type": "string", "const": "audit" }, "uniqueItems": true }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "created_at": { "type": "string", "format": "date-time" } } }, "AdjustmentPage": { "type": "object", "additionalProperties": false, "required": [ "object", "items", "has_more" ], "properties": { "object": { "type": "string", "const": "list" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Adjustment" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "CalculationBatchCreate": { "type": "object", "additionalProperties": false, "required": [ "calculations" ], "properties": { "reference": { "$ref": "#/components/schemas/Reference" }, "calculations": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/CalculationCreate" } } } }, "CalculationBatchItem": { "type": "object", "additionalProperties": false, "required": [ "index", "status" ], "properties": { "index": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "queued", "processing", "succeeded", "failed" ] }, "calculation": { "$ref": "#/components/schemas/Calculation" }, "problem": { "$ref": "#/components/schemas/Problem" } } }, "CalculationBatch": { "type": "object", "additionalProperties": false, "required": [ "id", "object", "status", "total_count", "succeeded_count", "failed_count", "items", "request_id", "created_at" ], "properties": { "id": { "$ref": "#/components/schemas/BatchId" }, "object": { "type": "string", "const": "calculation_batch" }, "reference": { "$ref": "#/components/schemas/Reference" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "partially_failed", "failed" ] }, "total_count": { "type": "integer", "minimum": 1, "maximum": 100 }, "succeeded_count": { "type": "integer", "minimum": 0, "maximum": 100 }, "failed_count": { "type": "integer", "minimum": 0, "maximum": 100 }, "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/CalculationBatchItem" } }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Coverage": { "type": "object", "additionalProperties": false, "required": [ "object", "qualification", "country", "tax_code", "transaction_type", "calculation", "obligation", "tax_id_validation", "source_basis", "as_of", "request_id" ], "properties": { "object": { "type": "string", "const": "coverage" }, "qualification": { "type": "string", "enum": [ "qualified", "review_required", "unsupported" ] }, "country": { "$ref": "#/components/schemas/CountryCode" }, "state": { "$ref": "#/components/schemas/SubdivisionCode" }, "tax_code": { "$ref": "#/components/schemas/TaxCode" }, "transaction_type": { "$ref": "#/components/schemas/TransactionType" }, "customer_type": { "$ref": "#/components/schemas/CustomerType" }, "calculation": { "type": "string", "enum": [ "supported", "review_required", "unsupported" ] }, "obligation": { "type": "string", "enum": [ "derived", "review_required", "unsupported" ] }, "tax_id_validation": { "type": "string", "enum": [ "authoritative", "format_only", "not_available" ] }, "evidence_required": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "customer_address", "ship_from", "ship_to", "tax_id", "exemption_certificate" ] } }, "source_basis": { "type": "string", "enum": [ "official", "licensed", "none" ] }, "effective_from": { "type": "string", "format": "date" }, "effective_through": { "type": [ "string", "null" ], "format": "date" }, "as_of": { "type": "string", "format": "date" }, "next_review_due_at": { "type": [ "string", "null" ], "format": "date-time" }, "message": { "type": "string", "minLength": 1, "maxLength": 1000 }, "request_id": { "$ref": "#/components/schemas/RequestId" } } }, "ProblemCode": { "type": "string", "enum": [ "invalid_request", "unknown_field", "request_too_large", "unsupported_currency", "invalid_api_key", "invalid_cursor", "invalid_idempotency_key", "rate_limit_exceeded", "forbidden", "internal_error", "runtime_not_configured", "resource_not_found", "subscription_required", "usage_cap_reached", "idempotency_conflict", "idempotency_unavailable", "request_in_progress", "tax_data_ambiguous", "adjustment_amount_invalid", "adjustment_amount_too_small", "adjustment_conflict", "adjustment_exceeds_original", "adjustment_line_invalid", "calculation_already_finalized", "calculation_not_finalizable" ] }, "FieldProblem": { "type": "object", "additionalProperties": false, "required": [ "pointer", "message" ], "properties": { "pointer": { "type": "string", "pattern": "^(/([^/~]|~0|~1)*)*$" }, "message": { "type": "string", "minLength": 1, "maxLength": 500 } } }, "Problem": { "type": "object", "additionalProperties": false, "required": [ "type", "title", "status", "detail", "instance", "code", "request_id", "retryable" ], "properties": { "type": { "type": "string", "format": "uri", "pattern": "^https://api\\.salestaxcalculatorapi\\.com/problems/" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "detail": { "type": "string", "minLength": 1, "maxLength": 1000 }, "instance": { "type": "string", "format": "uri-reference" }, "code": { "$ref": "#/components/schemas/ProblemCode" }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "retryable": { "type": "boolean" }, "retry_after_seconds": { "type": "integer", "minimum": 1 }, "errors": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/FieldProblem" } } } } } } }