Skip to main content

POS Tax Behavior

This page documents the gateway-side tax behavior a POS integration can rely on today. It is intentionally about current runtime truth, not product roadmap direction.

Current behavior summary​

TopicCurrent behavior
Calculation surfacePublic POST /api/v1/tax/calculate is live and exposed in both SDKs
Scoping modelOrganization defaults with location-specific overrides where configured
SPD supportSupported
Sourcing modelDestination-based only
Negative tax ratesRejected
Non-US handlingZero-tax result in the current manual provider path
Category taxonomyFree-text categories; no canonical vocabulary enforcement

What POS should call​

POS can use the normal public calculation surface:

  • TypeScript: client.taxConfig.calculate(...)
  • Kotlin: client.taxConfig.calculate(...)
  • HTTP: POST /api/v1/tax/calculate

That surface is appropriate for POS-side previewing or validating totals before the sale is finalized.

Current calculation rules​

Rate units​

Gateway stores and exchanges fee and tax rates as integer milli-percent units:

Stored valueDecimal percent
10.001%
10001.000%
25002.500%
88758.875%

Amount calculations use integer arithmetic:

amount_from_rate = amount_in_cents * rate_units / 100000

This keeps rate math deterministic across Kotlin, TypeScript, JSON serialization, and database comparisons while still supporting common sales-tax precision such as 8.875%.

1. Destination-based only​

The gateway calculates tax from the destination address. There is no explicit origin-based sourcing mode in the current schema or service layer.

Integration implication:

  • do not assume the gateway will derive tax from the store-of-origin
  • do not treat a populated fromAddress as a signal that origin sourcing is active

Origin-based tax requires an explicit model change rather than a silent behavior switch.

2. SPD support is live​

Special-purpose district (SPD) configuration is part of the current tax model and is already covered by gateway-side tests. POS does not need a separate feature flag or fallback path for SPD jurisdictions.

3. Negative rates are not accepted​

The gateway rejects negative tax rates in both schema and service validation. Use discounts, credits, or promotions for rebate-like behavior rather than attempting to encode a negative tax row.

4. Non-US addresses currently return zero tax​

The current manual provider path is US-only. Non-US requests do not fail, but they resolve to zero tax instead of calling an international tax engine.

Integration implication:

  • if POS is expected to compute non-US tax, the current gateway result is not authoritative
  • if zero-tax fallback is unacceptable for a market, treat that as a product product blocker rather than assuming hidden support exists

5. Categories are descriptive, not canonical​

appliesToCategory is currently free text. The gateway can warn about overlap or conflict, but it does not enforce a shared product-category taxonomy.

Integration implication:

  • POS may send category strings, but should not assume a centrally validated enum exists
  • cross-system consistency is a process/data-governance problem today, not a gateway validation guarantee

Not promised by current gateway behavior​

The following should be treated as unresolved or explicitly out of scope until the product/runtime changes:

  • origin-based sourcing rules
  • authoritative non-US tax calculation
  • canonical product-category validation across systems

Current support claims​

Support, solutions, and integrators can safely describe the current tax lane like this:

  • the gateway exposes a live tax-calculation endpoint
  • the current path is destination-based
  • SPD support is available
  • negative tax rows are rejected
  • non-US requests currently fall back to zero tax instead of an international engine

They should not describe the current lane as:

  • origin-based tax capable
  • authoritative for non-US taxation
  • backed by a canonical cross-system category taxonomy

Related docs​