Introduction
Guides
API Reference
SPI CRM v2
SPI CRM v1
SPI Digital Receipts
SPI Discount Cards
SPI Events
SPI Gift Card
SPI Insurance
SPI Payment
SPI Product Recommendations
SPI Product Search
SPI RFID
SPI Tax Free
SPI Sales Tax
Journals v3
Media Object Storage
Purchase Prices v3
Shipments v3

SPI Sales Tax Provider

Get a tax quote

post /quotes

Gets a tax quote and returns calculated tax amounts without persisting an invoice.

PARAMETERS
store-id
string
header

The external ID of the store the register belongs to.

staff-id
string
header

The external ID of the staff.

register-id
string
header

The ID of the register used.

REQUEST BODY
object
REQUIRED
QuoteRequest
Returns

Quote created successfully

QuoteResponse
posthttps://tax.example.com/quotes
HTTP Status Code Summary
200Quote created successfully
400Bad request
401Unauthorized
403Forbidden
404Not found
409Conflict
429Too many requests
500Internal server error
502Bad gateway

Create tax invoice

post /invoices

Creates a tax invoice and returns calculated tax amounts.

PARAMETERS
store-id
string
header

The external ID of the store the register belongs to.

staff-id
string
header

The external ID of the staff.

register-id
string
header

The ID of the register used.

REQUEST BODY
object
REQUIRED
InvoiceRequest
Returns

Invoice created successfully

InvoiceResponse
posthttps://tax.example.com/invoices
HTTP Status Code Summary
201Invoice created successfully
400Bad request
401Unauthorized
403Forbidden
404Not found
409Conflict
422Unprocessable entity
429Too many requests
500Internal server error
502Bad gateway

Get tax invoice

get /invoices/{invoice_id}

Retrieves a previously created tax invoice by its ID.

PARAMETERS
invoice_id
string
path
REQUIRED

Invoice ID to retrieve

store-id
string
header

The external ID of the store the register belongs to.

staff-id
string
header

The external ID of the staff.

register-id
string
header

The ID of the register used.

Returns

Invoice retrieved successfully

InvoiceResponse
gethttps://tax.example.com/invoices/INV-2025-001
HTTP Status Code Summary
200Invoice retrieved successfully
400Bad request
401Unauthorized
403Forbidden
404Not found
409Conflict
429Too many requests
500Internal server error
502Bad gateway

Commit tax invoice

post /invoices/{invoice_id}/commit

Commits a previously created tax invoice.

PARAMETERS
invoice_id
string
path
REQUIRED

Invoice ID to commit

store-id
string
header

The external ID of the store the register belongs to.

staff-id
string
header

The external ID of the staff.

register-id
string
header

The ID of the register used.

Returns

Invoice committed successfully

InvoiceResponse
posthttps://tax.example.com/invoices/INV-2025-001/commit
HTTP Status Code Summary
200Invoice committed successfully
400Bad request
401Unauthorized
403Forbidden
404Not found
409Conflict
429Too many requests
500Internal server error
502Bad gateway

Create standalone refund invoice

post /invoices/refund

Creates a standalone refund invoice without a reference to an existing invoice.

PARAMETERS
store-id
string
header

The external ID of the store the register belongs to.

staff-id
string
header

The external ID of the staff.

register-id
string
header

The ID of the register used.

REQUEST BODY
object
REQUIRED
StandaloneRefundRequest
Returns

Refund invoice created successfully

InvoiceResponse
posthttps://tax.example.com/invoices/refund
HTTP Status Code Summary
201Refund invoice created successfully
400Bad request
401Unauthorized
403Forbidden
404Not found
409Conflict
429Too many requests
500Internal server error
502Bad gateway

Refund tax invoice

post /invoices/{invoice_id}/refund

Creates a refund against an existing tax invoice.

PARAMETERS
invoice_id
string
path
REQUIRED

Invoice ID to refund

store-id
string
header

The external ID of the store the register belongs to.

staff-id
string
header

The external ID of the staff.

register-id
string
header

The ID of the register used.

REQUEST BODY
object
REQUIRED
RefundRequest
Returns

Refund created successfully

InvoiceResponse
posthttps://tax.example.com/invoices/INV-2025-001/refund
HTTP Status Code Summary
200Refund created successfully
400Bad request
401Unauthorized
403Forbidden
404Not found
409Conflict
429Too many requests
500Internal server error
502Bad gateway

Get exemption codes

get /exemption-codes

Returns the list of available tax exemption codes.

PARAMETERS
store-id
string
header

The external ID of the store the register belongs to.

staff-id
string
header

The external ID of the staff.

register-id
string
header

The ID of the register used.

Returns

List of exemption codes

ExemptionCodesResponse
gethttps://tax.example.com/exemption-codes
HTTP Status Code Summary
200List of exemption codes
400Bad request
401Unauthorized
403Forbidden
404Not found
409Conflict
429Too many requests
500Internal server error
502Bad gateway

Get tax codes

get /tax-codes

Returns the list of available tax codes.

PARAMETERS
search
string
query

Search term to filter tax codes

Example: /tax-codes?search=freight
next
string
query

Cursor for pagination (base64url encoded)

Example: /tax-codes?next=eyJwYWdlIjogMn0=
num
integer
query

Number of results to return

Example: /tax-codes?num=100
store-id
string
header

The external ID of the store the register belongs to.

staff-id
string
header

The external ID of the staff.

register-id
string
header

The ID of the register used.

Returns

List of tax codes

TaxCodesResponse
gethttps://tax.example.com/tax-codes
HTTP Status Code Summary
200List of tax codes
400Bad request
401Unauthorized
403Forbidden
404Not found
409Conflict
429Too many requests
500Internal server error
502Bad gateway

Ping

get /ping

Verifies credentials and connectivity to the tax provider.

PARAMETERS
store-id
string
header

The external ID of the store the register belongs to.

staff-id
string
header

The external ID of the staff.

register-id
string
header

The ID of the register used.

Returns

Ping successful

PingResponse
gethttps://tax.example.com/ping
HTTP Status Code Summary
200Ping successful
400Bad request
401Unauthorized
403Forbidden
404Not found
409Conflict
429Too many requests
500Internal server error
502Bad gateway

Resolve address

post /addresses/resolve

Validates and resolves an address, returning the standardized address if successful.

PARAMETERS
store-id
string
header

The external ID of the store the register belongs to.

staff-id
string
header

The external ID of the staff.

register-id
string
header

The ID of the register used.

REQUEST BODY
object
REQUIRED
AddressResolveRequest
Returns

Address resolved successfully

AddressResolveResponse
posthttps://tax.example.com/addresses/resolve
HTTP Status Code Summary
200Address resolved successfully
400Bad request
401Unauthorized
403Forbidden
404Not found
409Conflict
429Too many requests
500Internal server error
502Bad gateway

Objects

ErrorCode
string

Error code describing the type of error that occurred. The error_data property might contain additional information.

Values: bad-request, unauthorized, forbidden, not-found, conflict, unprocessable-entity, too-many-requests, internal-server-error, bad-gateway

Error
object

PROPERTIES
error_code
ErrorCode
REQUIRED
error_data
REQUIRED
message
string
REQUIRED
request_id
string
REQUIRED

QuoteResponse
object

Response body for a tax quote

PROPERTIES
exemption_code
string

Exemption code for tax exemption

Example: "A"
lines
array
(ResponseLine)
REQUIRED

Tax details per line item

summary
array
(Summary)
REQUIRED

Tax summary by jurisdiction

total_amount
integer
REQUIRED

Total amount in smallest currency unit

Example: 5498
total_taxable
integer
REQUIRED

Total taxable amount in smallest currency unit

Example: 5498
total_tax
integer
REQUIRED

Total tax amount in smallest currency unit

Example: 357

ResponseLine
object

Tax details for an invoice line item

PROPERTIES
id
string
REQUIRED

Line item ID

Example: "1"
number
string
REQUIRED

Line item number

Example: "1"
tax_code
string

Product SKU or item code

Example: "WIDGET-A"
line_amount
integer
REQUIRED

Line item amount in smallest currency unit

Example: 3998
taxable_amount
integer
REQUIRED

Taxable amount in smallest currency unit

Example: 3998
tax
integer
REQUIRED

Tax amount in smallest currency unit

Example: 260
details
array
(TaxDetail)
REQUIRED

Tax breakdown by jurisdiction

TaxDetail
object

Tax detail for a specific jurisdiction

PROPERTIES
country
string
REQUIRED

Country code

Example: "US"
region
string
REQUIRED

State/region code

Example: "WA"
jurisdiction_name
string
REQUIRED

Jurisdiction name

Example: "WASHINGTON"
jurisdiction_code
string
REQUIRED

Jurisdiction code

Example: "WA"
tax_type
string
REQUIRED

Tax type

Example: "Sales"
tax_name
string
REQUIRED

Name of the tax

Example: "WA STATE TAX"
taxable_amount
integer
REQUIRED

Taxable amount in smallest currency unit

Example: 3998
rate
number
REQUIRED

Tax rate

Example: 0.065
tax
integer
REQUIRED

Tax amount in smallest currency unit

Example: 260

Summary
object

Tax summary for a jurisdiction

PROPERTIES
country
string
REQUIRED

Country code

Example: "US"
region
string
REQUIRED

State/region code

Example: "WA"
jurisdiction_name
string
REQUIRED

Jurisdiction name

Example: "WASHINGTON"
taxable
integer
REQUIRED

Total taxable amount in smallest currency unit

Example: 5498
rate
number
REQUIRED

Tax rate

Example: 0.065
tax
integer
REQUIRED

Total tax amount in smallest currency unit

Example: 357

QuoteRequest
object

Request body for getting a tax quote

PROPERTIES
customer_id
string

Customer identifier

Example: "CUST-001"
Max Length: 128
Min Length: 1
date
string
(date)
REQUIRED

Date (ISO 8601)

Example: "2025-06-15"
exemption_code
string

Exemption code for tax exemption

Example: "A"
Max Length: 64
Min Length: 1
tax_override
TaxOverride
addresses
RequestAddresses
REQUIRED
lines
array
(Line)
REQUIRED

Line items

TaxOverride

Override applied to tax calculation

oneOf:

TaxAmountOverride
object

PROPERTIES
type
string
REQUIRED
VALUES
tax-amount
tax_amount
integer
REQUIRED

Override tax amount (in smallest currency unit)

Example: 0
reason
string
REQUIRED

Reason for the tax override

Example: "Tax exempt purchase"
Max Length: 512
Min Length: 1

TaxDateOverride
object

PROPERTIES
type
string
REQUIRED
VALUES
tax-date
tax_date
string
(date)
REQUIRED

Override tax date (ISO 8601 date)

Example: "2025-06-15"
reason
string
REQUIRED

Reason for the tax override

Example: "Tax exempt purchase"
Max Length: 512
Min Length: 1

ExemptionOverride
object

PROPERTIES
type
string
REQUIRED
VALUES
exemption
reason
string
REQUIRED

Reason for the tax override

Example: "Tax exempt purchase"
Max Length: 512
Min Length: 1

RequestAddresses
object

Shipping addresses for the request

PROPERTIES
ship_from
AddressWithStore
ship_to
AddressWithStore
REQUIRED

AddressWithStore

Address with optional store information

PROPERTIES
address_1
string

Street address line 1

Example: "2000 Main Street"
Max Length: 128
Min Length: 1
address_2
string

Street address line 2

Example: "Suite 100"
Max Length: 128
Min Length: 1
city
string

City name

Example: "Irvine"
Max Length: 128
Min Length: 1
state
string

State/region code

Example: "CA"
Max Length: 2
Min Length: 2
postal_code
string
REQUIRED

Postal/ZIP code

Example: "92614"
Max Length: 16
Min Length: 1
country_code
string
REQUIRED

Country code (ISO 3166-1 alpha-2)

Example: "US"
Max Length: 2
Min Length: 2
store
Store

Store
object

Store information

PROPERTIES
external_id
string
REQUIRED

External identifier for the store

Example: "store-123456"
Max Length: 128
Min Length: 1

Address
object

Address for tax calculation

PROPERTIES
address_1
string

Street address line 1

Example: "2000 Main Street"
Max Length: 128
Min Length: 1
address_2
string

Street address line 2

Example: "Suite 100"
Max Length: 128
Min Length: 1
city
string

City name

Example: "Irvine"
Max Length: 128
Min Length: 1
state
string

State/region code

Example: "CA"
Max Length: 2
Min Length: 2
postal_code
string
REQUIRED

Postal/ZIP code

Example: "92614"
Max Length: 16
Min Length: 1
country_code
string
REQUIRED

Country code (ISO 3166-1 alpha-2)

Example: "US"
Max Length: 2
Min Length: 2

Line
object

A line item in an invoice

PROPERTIES
number
string
REQUIRED

Line item identifier

Example: "1"
Max Length: 64
Min Length: 1
sku
string
REQUIRED

Product SKU

Example: "WIDGET-A"
Max Length: 128
Min Length: 1
product_group
string

Product group for tax classification

Example: "electronics"
Max Length: 128
Min Length: 1
tax_code
string

Tax code for the item

Example: "P0000000"
Max Length: 64
Min Length: 1
exemption_code
string

Exemption code for tax exemption

Example: "A"
Max Length: 64
Min Length: 1
quantity
integer
REQUIRED

Quantity of items

Example: 2
Minimum: 0
amount
integer
REQUIRED

Line item amount in smallest currency unit

Example: 3998
description
string

Item description

Example: "Widget A"
Max Length: 512
Min Length: 1
tax_override
TaxOverride
addresses
LineAddresses

LineAddresses
object

Per-line shipping addresses

PROPERTIES
ship_from
AddressWithStore
ship_to
AddressWithStore

InvoiceResponse
object

Response body for a tax invoice

PROPERTIES
exemption_code
string

Exemption code for tax exemption

Example: "A"
lines
array
(ResponseLine)
REQUIRED

Tax details per line item

summary
array
(Summary)
REQUIRED

Tax summary by jurisdiction

total_amount
integer
REQUIRED

Total amount in smallest currency unit

Example: 5498
total_taxable
integer
REQUIRED

Total taxable amount in smallest currency unit

Example: 5498
total_tax
integer
REQUIRED

Total tax amount in smallest currency unit

Example: 357
id
string
REQUIRED

Invoice code

Example: "INV-2025-001"

InvoiceRequest

Request body for creating an invoice

PROPERTIES
customer_id
string

Customer identifier

Example: "CUST-001"
Max Length: 128
Min Length: 1
date
string
(date)
REQUIRED

Date (ISO 8601)

Example: "2025-06-15"
exemption_code
string

Exemption code for tax exemption

Example: "A"
Max Length: 64
Min Length: 1
tax_override
TaxOverride
addresses
RequestAddresses
REQUIRED
lines
array
(Line)
REQUIRED

Line items

code
string
REQUIRED

Deterministic invoice code for idempotent retries

Example: "1001-2-98765"
Max Length: 128
Min Length: 1
store
Store

BaseSalesTaxRequest
object

PROPERTIES
customer_id
string

Customer identifier

Example: "CUST-001"
Max Length: 128
Min Length: 1
date
string
(date)
REQUIRED

Date (ISO 8601)

Example: "2025-06-15"
exemption_code
string

Exemption code for tax exemption

Example: "A"
Max Length: 64
Min Length: 1
tax_override
TaxOverride
addresses
RequestAddresses
REQUIRED
lines
array
(Line)
REQUIRED

Line items

StandaloneRefundRequest

Request body for creating a standalone refund invoice

PROPERTIES
customer_id
string

Customer identifier

Example: "CUST-001"
Max Length: 128
Min Length: 1
date
string
(date)
REQUIRED

Date (ISO 8601)

Example: "2025-06-15"
exemption_code
string

Exemption code for tax exemption

Example: "A"
Max Length: 64
Min Length: 1
tax_override
TaxOverride
addresses
RequestAddresses
REQUIRED
lines
array
(Line)
REQUIRED

Line items

code
string
REQUIRED

Deterministic invoice code for idempotent retries

Example: "1001-2-98765"
Max Length: 128
Min Length: 1
store
Store
tax_override
RefundTaxOverride
lines
array
(RefundLine)
REQUIRED

Refund line items

reference_code
string

Reference to the original receipt or transaction being refunded

Example: "1001-2-98765"
Max Length: 128
Min Length: 1

RefundTaxOverride

Tax override for refund transactions

RefundLine

A line item in a refund invoice

PROPERTIES
number
string
REQUIRED

Line item identifier

Example: "1"
Max Length: 64
Min Length: 1
sku
string
REQUIRED

Product SKU

Example: "WIDGET-A"
Max Length: 128
Min Length: 1
product_group
string

Product group for tax classification

Example: "electronics"
Max Length: 128
Min Length: 1
tax_code
string

Tax code for the item

Example: "P0000000"
Max Length: 64
Min Length: 1
exemption_code
string

Exemption code for tax exemption

Example: "A"
Max Length: 64
Min Length: 1
quantity
integer
REQUIRED

Quantity of items

Example: 2
Minimum: 0
amount
integer
REQUIRED

Line item amount in smallest currency unit

Example: 3998
description
string

Item description

Example: "Widget A"
Max Length: 512
Min Length: 1
tax_override
TaxOverride
addresses
LineAddresses
amount
integer
REQUIRED

Line item amount in smallest currency unit (must be negative for refunds)

Example: -3998
Maximum: 0
tax_override
RefundTaxOverride

RefundRequest
object

Request body for refunding an invoice

PROPERTIES
code
string
REQUIRED

Deterministic invoice code for idempotent retries

Example: "1001-2-98765"
Max Length: 128
Min Length: 1
refund_date
string
(date)
REQUIRED

Date of the refund (ISO 8601)

Example: "2025-06-16"
refund_type
string

Type of refund

Example: "full"
VALUES
full
partial
tax-only
percentage
refund_percentage
number

Percentage to refund (used when refund_type is percentage)

Example: 50
Minimum: 0
Maximum: 100
refund_lines
array
(string)

Line numbers to refund (used when refund_type is partial)

Example: [ "1", "2" ]
reference_code
string

Reference code for the refund

Example: "REFUND-2025-001"
Max Length: 128
Min Length: 1

ExemptionCodesResponse
object

Response body for listing exemption codes

PROPERTIES
exemption_codes
array
(ExemptionCode)
REQUIRED

List of exemption codes

ExemptionCode
object

An exemption code for tax-exempt purchases

PROPERTIES
code
string
REQUIRED

Exemption code

Example: "A"
name
string
REQUIRED

Exemption code name

Example: "Federal Government"
description
string
REQUIRED

Exemption code description

Example: "United States federal government entities"
valid_countries
array
(string)
REQUIRED

Countries where this exemption code is valid

Example: [ "US" ]

TaxCodesResponse
object

Response body for listing tax codes

PROPERTIES
tax_codes
array
(TaxCode)
REQUIRED

List of tax codes

next
string

Cursor for the next page of results

TaxCode
object

A tax code for categorizing products and services

PROPERTIES
tax_code
string
REQUIRED

Tax code identifier

Example: "P0000000"
description
string
REQUIRED

Description of the tax code

Example: "Tangible personal property"

PingResponse
object

Ping response

PROPERTIES
status
string
REQUIRED
Example: "ok"
VALUES
ok

AddressResolveResponse
object

Address resolution result

PROPERTIES
success
boolean
REQUIRED

Whether the address was successfully resolved

Example: true
resolved_address
ResolvedAddress

ResolvedAddress
object

Standardized address from the tax provider. Present when success is true for supported countries.

PROPERTIES
address_1
string

Resolved street address line 1

Example: "1000 MAIN ST"
address_2
string

Resolved street address line 2

city
string

Resolved city name

Example: "IRVINE"
state
string

Resolved state/region code

Example: "CA"
postal_code
string

Resolved postal/ZIP code (may include ZIP+4)

Example: "92614-6715"
country_code
string

Resolved country code

Example: "US"

AddressResolveRequest
object

Address to resolve for tax calculation

PROPERTIES
address_1
string

Street address line 1

Example: "2000 Main Street"
Max Length: 128
Min Length: 1
address_2
string

Street address line 2

Example: "Suite 100"
Max Length: 128
Min Length: 1
city
string

City name

Example: "Irvine"
Max Length: 128
Min Length: 1
state
string

State/region code

Example: "CA"
Max Length: 2
Min Length: 2
postal_code
string

Postal/ZIP code

Example: "92614"
Max Length: 16
Min Length: 1
country_code
string
REQUIRED

Country code (ISO 3166-1 alpha-2)

Example: "US"
Max Length: 2
Min Length: 2
Copyright © 2026 Sitoo AB. All rights reserved.