Getting Started with Kintsugi
Kintsugi automates sales tax end to end. It watches where your sales create an obligation, prices the right rate at checkout, registers you in the jurisdictions that require it, and files and remits on schedule. Setup is five steps, and this page covers all of them.
What to expect: the first three steps are yours to complete and take an afternoon at most. Registrations move at the speed of each state's tax authority, so plan for those to land over days rather than minutes.
The five steps, in order, from connecting data to approving your first filing.
Choose between transaction sync (L1) and the tax engine (L2) before you write code.
Create a key, then make your first authenticated request.
Every endpoint, with real request and response shapes from the live spec.
Quick Setup
Five steps, in order. Each one unlocks the next: Kintsugi cannot price a product it has not classified, and cannot file a return in a jurisdiction where you are not registered.
Kintsugi works from your sales history. Nexus, rates, and returns are all derived from the transactions you send, so connecting a data source comes first.
Open Data Sources in the app and click Connect, then choose the route that matches your stack.
Dozens of prebuilt connectors cover shopping carts, billing systems, ERPs, and accounting platforms. Pick your platform, authorize it once, and Kintsugi keeps transactions in sync from then on.
Build against the REST API or an official SDK. Start with Planning an Integration to choose your integration level, then Syncing Transaction Records for the payload shape.
SDKs are available for Python, TypeScript, Java, PHP, and Ruby, and the API Lab lets you run each workflow before you build it.
Download Kintsugi's template, fill it in, and upload it. File Upload documents every column the importer reads, and uploaded transactions behave exactly like ones created through the API.
Import Historical Data
Send transactions covering the previous full calendar year through today. Kintsugi determines nexus by looking back across that window, so without it we cannot tell you when you crossed a threshold or when your filing obligation began.
CSV is usually the fastest way to backfill: see File Upload for the template and column reference. Coming from another provider? Migrating from Avalara or TaxJar covers exporting your history and cutting over without breaking a filing period.
Skipping history does not stop Kintsugi from tracking new sales, but it does mean nexus start dates and past exposure have to be set from your own records. Import the history if you have it.
Kintsugi needs three things about your company: where you have people and property, who you are on a tax return, and how you pay.
Physical Presence
Economic nexus comes out of your transaction data automatically. Physical nexus does not, because no transaction records it. Tell Kintsugi where you have:
- Offices, stores, or warehouses
- Employees or contractors, including remote staff working from home
- Inventory held for sale, including stock in a third-party fulfillment center you have never visited
- Traveling sales representatives
If you are unsure, enter what you know and Kintsugi flags the jurisdictions worth a second look. US Sales Tax for Developers explains how each activity creates an obligation, and physical nexus can also be managed programmatically through Create physical nexus.
Physical nexus carries no grace threshold. Unlike economic nexus, it applies from your first taxable sale into that state, so record presence as soon as it exists.
Organization Details
These details appear verbatim on your registrations and returns, so match them to your incorporation documents rather than your brand name:
- Legal business name and address
- Tax ID numbers
- Entity type and industry
- Contact for jurisdiction correspondence
Banking Information
Kintsugi debits the tax it remits on your behalf, so bank details are required before your first filing rather than before setup:
- Bank account for tax payments
- ACH authorization
- Payment preferences
Banking details are encrypted at rest and used only to remit tax on your behalf.
Two inputs decide every rate Kintsugi calculates: what you sold, and where it went.
Product Classification
Taxability is decided per product, not per order. A t-shirt, a downloadable report, and a SaaS subscription are treated differently in the same state, so each product needs a category before Kintsugi can price it. Approving a product means confirming the category assigned to it.
Let Kintsugi Intelligence classify the catalog, then spot-check the results. The best starting point for a large catalog.
Use bulk approve to accept the assigned categories across the catalog in one action. Fastest when your products are uniform.
Set the category product by product. Worth the time for bundles, digital goods, and anything with unusual treatment.
Product Categories explains how categories and subcategories map to taxability, and Get product categories returns the full catalog of values. Creating products through the API instead? See Create a product.
Address Validation
A rate is a function of an address, not a state. A postal code resolves to a county, city, and any special districts on top; a state on its own does not, and the gap between the two is often several percent.
- Open Tasks to see the transactions Kintsugi could not resolve
- Use Kintsugi Intelligence to fill in missing components
- Review anything still flagged, since these are the rows most likely to be wrong on a return
Validate addresses in your own checkout before you calculate tax, and you avoid the correction later. See Address validation for the endpoint.
With data and configuration in place, Kintsugi can tell you where you owe and who is exempt.
Nexus Review
Open Nexus to see where you have crossed a threshold, where you are approaching one, and where you have no obligation yet. The exposure map on your dashboard is the same picture, by geography.
Kintsugi monitors nexus continuously and alerts you when a new obligation appears, so this is a review rather than something to recheck by hand. Reading it programmatically: Get nexus for org.
Exemption Management
If you sell to resellers, nonprofits, or government buyers, record the exemption before you collect tax you will have to refund:
- Configure customer exemptions in the Exemptions section
- Set product-level exemptions where a category is treated differently
- Upload and manage exemption certificates so they are on file for an audit
Through the API: Create an exemption and Upload an exemption certificate.
Nexus tells you where you owe. A registration is what makes filing possible, so this is the step that turns monitoring into compliance.
Register in New Jurisdictions
Click Register on the Nexus page for each jurisdiction where you have nexus. Kintsugi handles the application; processing time is set by the state, not by us.
Import Existing Registrations
Already registered somewhere? Import the registration with its effective date and filing frequency so Kintsugi picks up returns from the right period rather than the day you signed up. See Create a registration.
File and Remit
Review your returns on the Filings page and click Approve to file and remit in each jurisdiction. Get filings exposes the same records to your own systems.
Once a jurisdiction is registered and its first filing is approved, Kintsugi files and remits there on schedule without further action from you.
Next Steps
Setup is done. Where you go next depends on whether you are operating Kintsugi or building on it.
Generate a key and store it safely.
Authenticate with your key and organization ID.
Pick L1 or L2, then sequence the build.
Run each workflow interactively before you code it.
Nexus, taxability, exemptions, and sourcing explained.
Point your AI coding assistant at the live API and docs.
Day to day, the records you will read most are customers, transactions, and registrations.