Sitoo Sales Tax SPI

The Sales Tax SPI enables external tax calculation providers to integrate with Sitoo POS systems to provide real-time sales tax calculations during checkout.

SPI (Service Provider Interface)

The SPI is the definition of the API required to use the service in Sitoo. Therefore, the external service needs to fully implement the API definition.

Authentication

Authentication is performed using the HTTP Basic Authentication mechanism. Requests to the endpoint will add an Authorization header to the request. Example:

Authorization: Basic c2l0b286c2FsZXMtdGF4LXNwaS1pbnRlZ3JhdGlvbi1zZXJ2ZXItdG9rZW4=

Public Server

The URL used for the service needs to have public access with a valid SSL certificate.

Errors

When a request is not successful, an error object should be returned. It should consist of the request_id, an error_code and an error_data field. The error_code must be one of the following values:

• bad-request
• unauthorized
• forbidden
• not-found
• conflict
• unprocessable-entity
• too-many-requests
• bad-gateway

Example error message:

{
  "error_code": "bad-request",
  "error_data": {
    "message": "Invalid postal code format"
  },
  "request_id": "123e4567-e89b-12d3-a456-426614174123"
}

Tax Calculation Flow

The POS uses a quote/invoice model for tax calculations during checkout:

1. Quote (POST /quotes) — Estimate tax without recording a transaction. Called during checkout to display tax amounts.
2. Create Invoice (POST /invoices) — Create a recorded tax invoice. Called when a sale is finalized.
3. Commit Invoice (POST /invoices/{invoice_id}/commit) — Commit a previously created invoice for tax reporting.
4. Refund Invoice (POST /invoices/{invoice_id}/refund) — Refund a previously created invoice, partially or fully.
5. Standalone Refund (POST /invoices/refund) — Create a refund not linked to a specific invoice.

Additional Endpoints

• Exemption Codes (GET /exemption-codes) — List available tax exemption codes.
• Tax Codes (GET /tax-codes) — List available tax codes for product classification.
• Ping (GET /ping) — Health check to verify connectivity and credentials.
• Address Resolve (POST /addresses/resolve) — Validate and resolve an address.

Request Data

Tax calculation requests (quotes and invoices) include:

• Date — Date of the transaction (ISO 8601)
• Customer ID — Optional customer identifier
• Exemption Code — Optional tax exemption code
• Addresses — Shipping origin (ship_from) and destination (ship_to)
• Lines — Line items with SKU, quantity, amount, and optional tax code
• Tax Override — Optional override for tax amount, date, or exemption
• Code — Deterministic invoice code for idempotent retries (invoices only)

Response Data

The response provides:

• Total Tax — Total tax amount in smallest currency unit
• Total Taxable — Total taxable amount in smallest currency unit
• Total Amount — Total amount in smallest currency unit
• Lines — Tax breakdown per line item with jurisdiction details
• Summary — Tax summary by jurisdiction
• ID — Invoice identifier (invoice responses only)

Example quote response:

{
  "total_tax": 357,
  "total_taxable": 5498,
  "total_amount": 5498,
  "lines": [
    {
      "id": "1",
      "number": "1",
      "tax_code": "P0000000",
      "line_amount": 3998,
      "taxable_amount": 3998,
      "tax": 260,
      "details": [
        {
          "country": "US",
          "region": "WA",
          "jurisdiction_name": "WASHINGTON",
          "jurisdiction_code": "WA",
          "tax_type": "Sales",
          "tax_name": "WA STATE TAX",
          "taxable_amount": 3998,
          "rate": 0.065,
          "tax": 260
        }
      ]
    }
  ],
  "summary": [
    {
      "country": "US",
      "region": "WA",
      "jurisdiction_name": "WASHINGTON",
      "taxable": 5498,
      "rate": 0.065,
      "tax": 357
    }
  ]
}

Address Requirements

Tax calculations require accurate shipping addresses to determine the correct tax jurisdiction:

• ship_from — The origin address (warehouse, store, etc.). Optional at request level, can be provided per line.
• ship_to — The destination address (customer shipping address). Required at request level.

Addresses should include:

• postal_code (required) — Postal/ZIP code
• country_code (required) — Country code (ISO 3166-1 alpha-2)
• address_1 — Street address line 1
• address_2 — Street address line 2
• city — City name
• state — State/region code

Addresses can be provided at the request level or per line item for multi-origin shipments.