SDKs

SDK Quick Start

This page gets your first call working. For the detail behind it, including async, retries and error types, see the Python, TypeScript, Java, PHP and Ruby guides.

Prerequisites

A Kintsugi account
An API key, created in the app (see Creating and managing API keys)

Keep your API key out of version control and out of browser bundles. Read it from an environment variable, and call the API from your server.

Install and call

Install the SDK for your language, then fetch a customer by id. That is the whole loop: authenticate once, call a method, read a typed response.

pip install kintsugi-tax-platform-sdk

import os
from kintsugi_tax_platform_sdk import SDK, models

with SDK(
    security=models.Security(
        api_key_header=os.environ["KINTSUGI_API_KEY"],
    ),
) as sdk:

    res = sdk.customers.get(customer_id="cust_abc123")

    # Handle response
    print(res)

npm add @kintsugi-tax/tax-platform-sdk

import { SDK } from "@kintsugi-tax/tax-platform-sdk";

const sdk = new SDK({
  security: {
    apiKeyHeader: process.env.KINTSUGI_API_KEY ?? "",
  },
});

async function run() {
  const result = await sdk.customers.get({
    customerId: "cust_abc123",
  });

  console.log(result);
}

run();

implementation 'com.trykintsugi:kintsugi-tax-java-sdk:0.15.3'

package hello.world;

import com.kintsugi.taxplatform.SDK;
import com.kintsugi.taxplatform.models.components.Security;
import com.kintsugi.taxplatform.models.operations.GetCustomerByIdV1CustomersCustomerIdGetResponse;

public class Application {

    public static void main(String[] args) throws Exception {

        SDK sdk = SDK.builder()
                .security(Security.builder()
                    .apiKeyHeader(System.getenv().getOrDefault("KINTSUGI_API_KEY", ""))
                    .build())
            .build();

        GetCustomerByIdV1CustomersCustomerIdGetResponse res = sdk.customers().getById()
                .customerId("cust_abc123")
                .call();

        if (res.customerRead().isPresent()) {
            System.out.println(res.customerRead().get());
        }
    }
}

composer require "kintsugi-tax/tax-platform-sdk"

declare(strict_types=1);

require 'vendor/autoload.php';

use KintsugiTax\SDK;
use KintsugiTax\SDK\Models\Components;

$sdk = SDK\SDK::builder()
    ->setSecurity(
        new Components\Security(
            apiKeyHeader: getenv('KINTSUGI_API_KEY'),
        )
    )
    ->build();

$response = $sdk->customers->getById(
    customerId: 'cust_abc123'
);

if ($response->customerRead !== null) {
    // handle response
}

gem install kintsugi_sdk

require 'kintsugi_sdk'

Models = ::KintsugiSDK::Models
s = ::KintsugiSDK::OpenApiSDK.new(
  security: Models::Shared::Security.new(
    api_key_header: ENV.fetch('KINTSUGI_API_KEY')
  )
)

req = Models::Ops::GetCustomerByIdV1CustomersCustomerIdGetRequest.new(
  customer_id: 'cust_abc123'
)
res = s.customers.get(request: req)

unless res.nil?
  # handle response
end

Estimate tax

Tax estimation is where most integrations begin. Send the line items and addresses, get back the tax owed, and nothing is recorded against the organization:

import os
from kintsugi_tax_platform_sdk import SDK, models
from kintsugi_tax_platform_sdk.utils import parse_datetime

with SDK(
    security=models.Security(api_key_header=os.environ["KINTSUGI_API_KEY"]),
) as sdk:

    res = sdk.tax_estimation.estimate(
        date_=parse_datetime("2025-01-23T13:01:29.949Z"),
        external_id="txn_12345",
        currency=models.CurrencyEnum.USD,
        transaction_items=[
            {
                "external_id": "item_A",
                "date_": parse_datetime("2025-01-23T13:01:29.949Z"),
                "external_product_id": "prod_abc",
                "quantity": 2,
                "amount": 100,
            },
        ],
        addresses=[
            {
                "type": models.TransactionEstimatePublicRequestType.SHIP_TO,
                "street_1": "789 Pine St",
                "city": "Austin",
                "state": "TX",
                "postal_code": "78701",
                "country": "US",
            },
        ],
        marketplace=False,
    )

    print(res)

import { SDK } from "@kintsugi-tax/tax-platform-sdk";

const sdk = new SDK({
  security: { apiKeyHeader: process.env.KINTSUGI_API_KEY ?? "" },
});

const result = await sdk.taxEstimation.estimate({
  transactionEstimatePublicRequest: {
    date: new Date("2025-01-23T13:01:29.949Z"),
    externalId: "txn_12345",
    currency: "USD",
    transactionItems: [
      {
        externalId: "item_A",
        date: new Date("2025-01-23T13:01:29.949Z"),
        externalProductId: "prod_abc",
        quantity: 2,
        amount: 100,
      },
    ],
    addresses: [
      {
        type: "SHIP_TO",
        street1: "789 Pine St",
        city: "Austin",
        state: "TX",
        postalCode: "78701",
        country: "US",
      },
    ],
  },
});

console.log(result);

package hello.world;

import com.kintsugi.taxplatform.SDK;
import com.kintsugi.taxplatform.models.components.*;
import com.kintsugi.taxplatform.models.operations.EstimateTaxV1TaxEstimatePostResponse;
import java.time.OffsetDateTime;
import java.util.List;

public class Application {

    public static void main(String[] args) throws Exception {

        SDK sdk = SDK.builder()
                .security(Security.builder()
                    .apiKeyHeader(System.getenv().getOrDefault("KINTSUGI_API_KEY", ""))
                    .build())
            .build();

        EstimateTaxV1TaxEstimatePostResponse res = sdk.taxEstimation().estimate()
                .transactionEstimatePublicRequest(TransactionEstimatePublicRequest.builder()
                    .date(OffsetDateTime.parse("2025-01-23T13:01:29.949Z"))
                    .externalId("txn_12345")
                    .currency(CurrencyEnum.USD)
                    .transactionItems(List.of(
                        TransactionItemEstimateBase.builder()
                            .date(OffsetDateTime.parse("2025-01-23T13:01:29.949Z"))
                            .amount(100d)
                            .externalId("item_A")
                            .externalProductId("prod_abc")
                            .quantity(2d)
                            .build()))
                    .addresses(List.of(
                        TransactionEstimatePublicRequestAddress.builder()
                            .type(TransactionEstimatePublicRequestType.SHIP_TO)
                            .street1("789 Pine St")
                            .city("Austin")
                            .state("TX")
                            .postalCode("78701")
                            .country("US")
                            .build()))
                    .build())
                .call();

        if (res.pageTransactionEstimateResponse().isPresent()) {
            System.out.println(res.pageTransactionEstimateResponse().get());
        }
    }
}

declare(strict_types=1);

require 'vendor/autoload.php';

use KintsugiTax\SDK;
use KintsugiTax\SDK\Models\Components;
use KintsugiTax\SDK\Utils;

$sdk = SDK\SDK::builder()
    ->setSecurity(
        new Components\Security(
            apiKeyHeader: getenv('KINTSUGI_API_KEY'),
        )
    )
    ->build();

$transactionEstimatePublicRequest = new Components\TransactionEstimatePublicRequest(
    date: Utils\Utils::parseDateTime('2025-01-23T13:01:29.949Z'),
    externalId: 'txn_12345',
    currency: Components\CurrencyEnum::Usd,
    transactionItems: [
        new Components\TransactionItemEstimateBase(
            externalId: 'item_A',
            date: Utils\Utils::parseDateTime('2025-01-23T13:01:29.949Z'),
            externalProductId: 'prod_abc',
            quantity: 2,
            amount: 100,
        ),
    ],
    addresses: [
        new Components\TransactionEstimatePublicRequestAddress(
            type: Components\TransactionEstimatePublicRequestType::ShipTo,
            street1: '789 Pine St',
            city: 'Austin',
            state: 'TX',
            postalCode: '78701',
            country: 'US',
        ),
    ],
);

$response = $sdk->taxEstimation->estimate(
    transactionEstimatePublicRequest: $transactionEstimatePublicRequest
);

if ($response->pageTransactionEstimateResponse !== null) {
    // handle response
}

require 'kintsugi_sdk'

Models = ::KintsugiSDK::Models
s = ::KintsugiSDK::OpenApiSDK.new(
  security: Models::Shared::Security.new(
    api_key_header: ENV.fetch('KINTSUGI_API_KEY')
  )
)

req = Models::Ops::EstimateTaxV1TaxEstimatePostRequest.new(
  transaction_estimate_public_request: Models::Shared::TransactionEstimatePublicRequest.new(
    date: DateTime.iso8601('2025-01-23T13:01:29.949Z'),
    external_id: 'txn_12345',
    currency: Models::Shared::CurrencyEnum::USD,
    transaction_items: [
      Models::Shared::TransactionItemEstimateBase.new(
        external_id: 'item_A',
        date: DateTime.iso8601('2025-01-23T13:01:29.949Z'),
        external_product_id: 'prod_abc',
        quantity: 2.0,
        amount: 100.0
      ),
    ],
    addresses: [
      Models::Shared::Addresses.new(
        type: Models::Shared::Type::SHIP_TO,
        street_1: '789 Pine St',
        city: 'Austin',
        state: 'TX',
        postal_code: '78701',
        country: 'US'
      ),
    ]
  )
)
res = s.tax_estimation.estimate_tax(request: req)

unless res.nil?
  # handle response
end

The Estimate tax reference page lists every field, with a sample in each language.

Next steps

API reference

Every endpoint, with a sample per language

Error handling

What the API returns, and when to retry

Calculate tax

A worked end-to-end recipe

Integration guide

How the pieces fit together