{ "openapi": "3.1.2", "info": { "title": "Sales Tax Calculator API", "version": "1.0.0", "summary": "Calculate, record, explain, and adjust indirect tax.", "description": "A resource-oriented API for qualified sales tax calculations, including supported VAT and GST transactions. The API fails closed when a jurisdiction, product, evidence, or seller configuration is not qualified. It 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": "Immutable tax decisions." }, { "name": "Transactions", "description": "Finalized commercial records and exact adjustments." }, { "name": "Batches", "description": "Durable asynchronous sales tax calculation batches." }, { "name": "Coverage", "description": "Dated qualification for a specific combination." } ], "paths": { "/v1/calculations": { "post": { "operationId": "createCalculation", "tags": [ "Calculations" ], "summary": "Create a sales tax calculation", "description": "Creates one immutable sales tax calculation from seller, customer, product, and billing facts supplied in the request. Determinate tax is returned only for a qualified combination.", "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 created.", "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" } } } }, "/v1/calculations/{calculation_id}": { "get": { "operationId": "getCalculation", "tags": [ "Calculations" ], "summary": "Retrieve a sales tax calculation", "description": "Retrieves one sales tax calculation owned by the authenticated 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" } } } }, "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" } } } }, "/v1/transactions": { "post": { "operationId": "createTransaction", "tags": [ "Transactions" ], "summary": "Create a transaction", "description": "Finalizes a completed sales tax calculation as an immutable commercial transaction and stores its exact line and tax-component snapshot.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ExpandAudit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionCreate" } } } }, "responses": { "201": { "description": "The transaction was finalized.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "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" } } } }, "/v1/transactions/{transaction_id}": { "get": { "operationId": "getTransaction", "tags": [ "Transactions" ], "summary": "Retrieve a transaction", "description": "Retrieves one finalized transaction owned by the authenticated 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" } } } }, "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" } } } }, "/v1/transactions/{transaction_id}/adjustments": { "post": { "operationId": "createTransactionAdjustment", "tags": [ "Transactions" ], "summary": "Create an adjustment", "description": "Creates an immutable adjustment by reversing exact stored original line components. Cumulative adjustments cannot exceed the reversible original.", "parameters": [ { "$ref": "#/components/parameters/TransactionId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ExpandAudit" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentCreate" } } } }, "responses": { "201": { "description": "The adjustment was created.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Adjustment" } } } }, "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" } } }, "get": { "operationId": "listTransactionAdjustments", "tags": [ "Transactions" ], "summary": "List transaction adjustments", "description": "Lists adjustments for one transaction, newest first, using an opaque cursor.", "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" } } } }, "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" } } } }, "/v1/transactions/{transaction_id}/adjustments/{adjustment_id}": { "get": { "operationId": "getTransactionAdjustment", "tags": [ "Transactions" ], "summary": "Retrieve an adjustment", "description": "Retrieves one adjustment belonging to 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" } } } }, "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" } } } }, "/v1/calculation-batches": { "post": { "operationId": "createCalculationBatch", "tags": [ "Batches" ], "summary": "Create a sales tax calculation batch", "description": "Durably accepts between 1 and 100 independent sales tax calculations for asynchronous processing.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalculationBatchCreate" } } } }, "responses": { "202": { "description": "The batch was durably accepted.", "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" } } } }, "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" } } } }, "/v1/calculation-batches/{batch_id}": { "get": { "operationId": "getCalculationBatch", "tags": [ "Batches" ], "summary": "Retrieve a sales tax calculation batch", "description": "Returns durable batch status and per-item results when available.", "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" } } } }, "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" } } } }, "/v1/coverage": { "get": { "operationId": "checkCoverage", "tags": [ "Coverage" ], "summary": "Check qualified coverage", "description": "Checks the dated qualification state for one jurisdiction, product, transaction type, customer type, and date. A country list alone is not a coverage guarantee.", "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": "The exact qualification result. Unsupported and review-required combinations are successful coverage lookups, not transport errors.", "headers": { "Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coverage" } } } }, "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" } } } } }, "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": "Opaque cursor from 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" } } } }, "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 idempotency key or current immutable resource state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unprocessable": { "description": "The request is structurally valid but cannot produce the requested effect, such as an unqualified fact combination or over-adjustment.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "RateLimited": { "description": "The request exceeded the uniform operational safety limit. No public API usage unit was reserved.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unavailable": { "description": "A required service is temporarily unavailable and the request failed closed.", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "examples": { "CalculationResponse": { "summary": "Qualified one-line 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" } } }, "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" } } } } } } }