1. Overview: Building Sales Tax as a Service

Building a Sales Tax as a Service (STaaS) platform enables you to offer comprehensive tax compliance solutions to your clients without building the complex tax logic yourself. This guide series walks through building a complete white label tax compliance application using Kintsugi’s API.

​

What You’ll Build

A complete STaaS platform includes:

• Client Onboarding: Automated organization setup with business details, addresses, and banking information
• Nexus Management: Track physical and economic nexus across jurisdictions
• Registration Management: Automate tax registrations in states where clients have nexus
• Product Catalog: Manage product tax classifications for accurate calculations
• Transaction Processing: L1 (sync transactions for compliance) and L2 (calculate tax at checkout when the tax engine is enabled)
• Compliance Management: Track filings, approvals, and compliance status

​

Integration Architecture

Show 🏗️ STaaS Platform Architecture

​

API Endpoints Overview

A complete STaaS integration uses 19 distinct API endpoints across 5 phases:

​

Phase 1: Organization Setup & Onboarding (8 endpoints)

Initial client setup endpoints:

• Create organization
• Generate API keys
• Configure business details, addresses, contacts, owners
• Set banking information

​

Phase 2: Product Catalog Management (1 endpoint)

• Create and manage products with tax classifications

​

Phase 3: Nexus & Registration Management (3 endpoints)

• Physical nexus creation
• Economic nexus registrations
• Registration status tracking

​

Phase 4: Transaction Processing (4 endpoints)

• Tax calculation
• Transaction creation
• Transaction retrieval

​

Phase 5: Compliance & Filing Management (3 endpoints)

• Filing list retrieval
• Filing details
• Filing approval

​

Integration Patterns

​

Choosing HTTP REST or SDK

All Kintsugi API endpoints are accessible via HTTP REST. The SDK is an optional wrapper that provides convenience methods and built-in error handling, but it calls the same REST API endpoints under the hood. You can use either approach:

• HTTP REST: Direct API calls using your preferred HTTP client. Gives you full control over requests and responses.
• SDK: Optional convenience wrapper around the REST API. Provides type safety, built-in pagination helpers, and simplified error handling.

Choose based on your preference:

• Use HTTP REST if you prefer direct control, want to use your existing HTTP client, or are building in a language without an SDK
• Use the SDK if you want convenience methods, type safety, and built-in helpers for pagination and error handling

Both approaches access the same API endpoints and provide the same functionality.

​

Sequential Setup Pattern

Organization onboarding requires sequential API calls. Each step depends on the previous one:

1. Create organization → Get organization_id
2. Create API key → Get api_key
3. Use both for all subsequent operations

​

Complete Integration Workflow

Show 🔄 Complete Client Lifecycle

​

What’s Next?

This guide series is organized into 6 articles:

1. Overview (this article) - Understanding the complete integration
2. Organization Setup & Onboarding - Setting up new clients with 8 sequential API calls
3. Nexus & Registration Management - Establishing tax presence and registrations
4. Transaction Processing - Calculating tax and syncing transactions
5. Product Catalog Management - Managing product tax classifications
6. Compliance & Filing Management - Tracking and approving tax filings

Each guide includes:

• Step-by-step instructions
• Code examples
• Mermaid diagrams showing data flow
• Best practices and error handling
• Integration patterns specific to STaaS platforms

​

Prerequisites

Before starting, ensure you have:

• Kintsugi Partner Account: Access to the Partner API. Partner organizations are their own organizations in PropelAuth (separate from client organizations) and are provisioned for you; there is no manual org-creation step, and partner-user invite emails are sent automatically when a user is added to the Partner Experience.
• API Credentials: A Client API key. Manage keys in the Partner Experience under Settings → API Keys, or programmatically via POST /v2/partner/api_keys (see Authentication and API keys).
• Development Environment: Ability to make HTTP REST calls (SDK is optional)
• Database: Storage for client records, organization IDs, and API keys

​

Authentication and API keys

All requests authenticate with the x-api-key header. Requests against a specific organization also send x-organization-id. Kintsugi uses header-based API keys, not bearer tokens. Client API keys come in two scopes: Key management (owner/admin role required): The create response returns apiKeyId and apiKeyToken; the token is shown once. When operating across multiple partners with a bearer session, select the active partner with the x-partner-id header. For programmatic client onboarding, POST /v1/organizations/api_keys also remains available to mint a per-client org key (see Organization Setup, Step 2).