Abacus Tax Engine

Quick Start

Get your first tax transaction running in minutes. This guide walks you through the three steps every integration follows: authenticate, create a customer, and submit a transaction - whether you're calculating US Sales Tax, VAT, or GST.

The API Reference includes an interactive request builder with generated code samples in cURL, Python, JavaScript, Java, and more.

Your First Transaction

Every integration follows the same three steps:

  1. Authenticate - exchange your credentials for an access token
  2. Create a customer - register the buyer once and reuse on every order
  3. Submit a transaction - send the sale for tax determination

Sales Tax and VAT use the same endpoint. Abacus Tax Engine resolves the tax regime automatically from the transaction's shipping address. A US address triggers Sales Tax logic. A German address triggers VAT. You change one field, nothing else.

Step 1: Authenticate

Exchange your client_id and client_secret for a Bearer token. Tokens are valid for 24 hours. See the Authentication guide for token management patterns and security best practices.

Your client_id and client_secret are issued when your account is provisioned. Contact your account administrator if you haven't received them.

The response includes an access_token. Pass it as Authorization: Bearer <access_token> on every subsequent request. See the Auth API Reference for the full response schema.

Step 2: Create a Customer

Register the buyer before submitting transactions. Abacus Tax Engine uses the customer record to apply exemptions, resolve VAT treatment, and accumulate jurisdiction thresholds.

The customer endpoint is an upsert - safe to call on every order. If a customer with the same external_id and source already exists, the record is updated in place.

The response includes an id - Abacus Tax Engine's UUID for this customer. You can reference it on transactions, or use external_id + source if you prefer your own identifiers.

See the Customers API Reference for the full request schema, all optional fields, and customer management endpoints.

Customer types and their effect:

Type Description
retail Standard end consumer. Standard tax rates apply.
wholesale B2B reseller. Taxable by default unless paired with an active exemption certificate.
retail_exempt Retail customer with a blanket exemption - tax is never charged regardless of jurisdiction.
marketplace Marketplace facilitator - transactions are treated as non-taxable to you.

Note: wholesale customers are taxable by default. Tax is only suppressed once an active exemption certificate is attached. See the Exemptions guide.

Step 3: Submit a Transaction

Send the sale to Abacus Tax Engine for determination. The engine resolves the jurisdiction, classifies each line item, and returns the calculated tax.

The response includes a tax object with the determined amount and effective rate, a full amounts breakdown, and per-item jurisdiction_tax_breakdown. See the Transactions API Reference for the complete response schema.

Submitting a VAT transaction: Change the shipping address to a VAT jurisdiction - everything else stays identical. Abacus Tax Engine detects the country and resolves the applicable regime automatically.

How External IDs and Source Work Together

The external_id is your system's identifier for the record. The source is a namespace - preventing collisions when multiple systems write to the same tenant (e.g. "my-store", "erp-system").

Together they form a unique key. Submitting the same pair again performs an upsert, not a duplicate. This makes it safe to re-send transactions after network errors.

Transaction Types

Type Description
sales_order Pre-invoice commitment, calculated for reference, not filed
invoice Confirmed sale, tax is reportable
estimate Quote or proposal, calculated for reference only
refund Full reversal of a previous transaction
taxable_refund Partial or taxable return

What's Next

Previous
Introduction
Next
Authentication