POST

transactions

Create Transaction

curl --request POST \
  --url https://api.trykintsugi.com/v1/transactions \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'x-organization-id: <api-key>' \
  --data '
{
  "organization_id": "orgn_YourOrgIdHere",
  "external_id": "YourUniqueOrder123",
  "date": "2024-01-15T14:30:00Z",
  "type": "SALE",
  "customer": {
    "organization_id": "orgn_YourOrgIdHere",
    "external_id": "Cust456",
    "name": "John Doe"
  },
  "addresses": [
    {
      "type": "SHIP_TO",
      "country": "US",
      "state": "CA",
      "city": "San Francisco",
      "postal_code": "94107",
      "street_1": "123 Main St"
    }
  ],
  "transaction_items": [
    {
      "organization_id": "orgn_YourOrgIdHere",
      "date": "2024-01-15T14:30:00Z",
      "external_product_id": "SKU-ABC",
      "product": "Example Widget",
      "quantity": 2,
      "amount": 50
    }
  ]
}
'

[
  {
    "organization_id": "orgn_YOURORGID",
    "external_id": "tran_YOURTRANSACTIONID",
    "date": "2024-01-15T14:30:00",
    "status": "COMMITTED",
    "description": "Order with one taxable book and one exempt service",
    "processing_status": "QUEUED",
    "total_amount": "200.00",
    "customer_id": "cust_afXm2qPEycF83",
    "marketplace": false,
    "exempt": "FULLY_EXEMPT",
    "exemptions": [
      {
        "updated_at": "2025-05-22T14:48:46.056060",
        "start_date": "2025-01-23",
        "transaction_id": "tran_nc5Q4hLi97NRD",
        "reseller": true,
        "status": "ACTIVE",
        "created_at": "2025-05-22T14:48:46.193109",
        "exemption_type": "transaction",
        "customer_id": "cust_afXm2qPEycF83",
        "id": "exmp_xfLpDHxxX4Cxv",
        "organization_id": "orgn_UT7zEcgwt4Fhk"
      }
    ],
    "total_tax_amount_imported": "6.00",
    "tax_rate_imported": "0.030000000",
    "total_tax_amount_calculated": "0.00",
    "tax_rate_calculated": "0E-9",
    "total_tax_liability_amount": "6.00",
    "tax_liability_source": "COLLECTED",
    "taxable_amount": "200.00",
    "currency": "USD",
    "locked": false,
    "source": "API",
    "address_status": "UNVERIFIED",
    "id": "tran_g9WJFTdFjLzDv",
    "addresses": [
      {
        "street_1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94107",
        "country": "US",
        "type": "SHIP_TO",
        "status": "UNVERIFIED",
        "id": "addr_tWqfSwDZK7aSt",
        "transaction_id": "tran_g9WJFTdFjLzDv"
      }
    ],
    "transaction_items": [
      {
        "external_id": "LI_BOOK_TAXABLE_001",
        "organization_id": "orgn_YOURORGID",
        "date": "2025-01-24T11:00:00",
        "external_product_id": "PROD_BOOK_SCIFI_HC",
        "product": "Sci-Fi Hardcover Novel",
        "product_id": "prod_AKczKRGnAe3d3",
        "quantity": "1",
        "amount": "100.00",
        "tax_amount_imported": "6.00",
        "tax_rate_imported": "0.060000000",
        "tax_amount_calculated": "0.00",
        "tax_rate_calculated": "0E-9",
        "taxable_amount": "100.00",
        "exempt": false,
        "id": "txim_c63o27oiEhLuA",
        "tax_items": [
          {
            "rule_id": "0000",
            "rate": "0.060000000",
            "amount": "6.00",
            "name": "PA State Sales Tax",
            "type": "IMPORTED",
            "jurisdiction_type": "STATE",
            "jurisdiction_name": "PA"
          }
        ],
        "total_discount": "0.00",
        "subtotal": "100.00"
      },
      {
        "external_id": "LI_SERVICE_EXEMPT_002",
        "organization_id": "orgn_YOURORGID",
        "date": "2025-01-24T11:00:00",
        "external_product_id": "PROD_DIGITAL_SERVICE_EX",
        "product": "Digital Marketing Service (Non-Taxable in PA)",
        "product_id": "prod_zz2RshS8uweRe",
        "quantity": "1",
        "amount": "100.00",
        "tax_amount_imported": "0.00",
        "tax_rate_imported": "0E-9",
        "tax_amount_calculated": "0.00",
        "tax_rate_calculated": "0E-9",
        "taxable_amount": "100.00",
        "tax_exemption": "PRODUCT",
        "exempt": false,
        "id": "txim_eqwAKmiDpgf2m",
        "tax_items": [],
        "total_discount": "0.00",
        "subtotal": "100.00"
      }
    ],
    "customer": {
      "name": "John Doe",
      "external_id": "Cust456",
      "status": "ACTIVE",
      "email": "buyer@example.com",
      "address_status": "UNVERIFIED",
      "id": "cust_afXm2qPEycF83",
      "organization_id": "orgn_YOURORGID"
    },
    "type": "SALE",
    "total_discount": "0.00",
    "subtotal": "200.00"
  }
]

Creating Transactions

Overview

Transactions represent completed sales in Kintsugi. Each transaction records a sale with customer information, line items, addresses, and tax details. Transactions are used for compliance tracking, nexus determination, and tax filing preparation.

Only create transactions for completed sales with confirmed payment. Do not sync pending orders or estimates.

When to Create Transactions

After payment confirmation: When a sale is completed and payment is received
Order fulfillment: When an order is shipped or delivered
Invoice creation: When generating invoices for completed sales
Batch sync: Daily or periodic syncing of completed orders

Workflow

Create a Transaction - Record a completed sale
Retrieve Transactions - Search and retrieve transaction records

Step 1: Create a Transaction

Create a transaction using the interactive playground below with POST /v1/transactions.

Required Fields

external_id: Your internal transaction/order identifier (must be unique)
date: Transaction date and time (UTC)
currency: Currency code (e.g., USD, EUR)
total_amount: Total transaction amount
source: Source of the transaction (e.g., “API”, “SHOPIFY”)
status: Transaction status (use “COMMITTED” for completed sales)
type: Transaction type (typically “SALE”)
transaction_items: Array of line items
addresses: Array of addresses (at minimum: SHIP_TO or BILL_TO)

Example Request

{
  "external_id": "ORDER-12345",
  "date": "2024-01-15T10:00:00Z",
  "currency": "USD",
  "total_amount": 150.00,
  "source": "API",
  "status": "COMMITTED",
  "type": "SALE",
  "transaction_items": [
    {
      "external_id": "ITEM-001",
      "external_product_id": "PROD-001",
      "product": "Example Product",
      "quantity": "1.0",
      "amount": 100.00
    }
  ],
  "addresses": [
    {
      "type": "SHIP_TO",
      "street_1": "123 Main St",
      "city": "Seattle",
      "state": "WA",
      "postal_code": "98101",
      "country": "US"
    }
  ]
}

Step 2: Retrieve Transactions

After creating transactions, retrieve them using GET /v1/transactions. You can:

Filter by external_id using the search_query parameter
Filter by date range using date__gte and date__lte
Filter by status, state, country, and more
Paginate through results

Authentication

This endpoint requires two headers:

x-api-key: Your API key
x-organization-id: Your organization ID

Both headers are required for authentication. You can find your API key and organization ID in your Kintsugi dashboard.

Try It Out

Use the interactive playground below to create a transaction. The playground will automatically include the required authentication headers.

The playground prefills example values from the API schema. Modify the request body to test different transaction configurations.

Common Use Cases

Basic Transaction

Create a simple transaction with minimal required fields:

{
  "external_id": "ORDER-001",
  "date": "2024-01-15T10:00:00Z",
  "currency": "USD",
  "total_amount": 100.00,
  "source": "API",
  "status": "COMMITTED",
  "type": "SALE",
  "transaction_items": [
    {
      "external_id": "ITEM-001",
      "external_product_id": "PROD-001",
      "product": "Widget",
      "quantity": "1.0",
      "amount": 100.00
    }
  ],
  "addresses": [
    {
      "type": "SHIP_TO",
      "street_1": "123 Main St",
      "city": "Seattle",
      "state": "WA",
      "postal_code": "98101",
      "country": "US"
    }
  ]
}

Transaction with Customer

Include customer information:

{
  "external_id": "ORDER-002",
  "date": "2024-01-15T10:00:00Z",
  "currency": "USD",
  "total_amount": 200.00,
  "source": "API",
  "status": "COMMITTED",
  "type": "SALE",
  "customer": {
    "external_id": "CUST-001",
    "name": "John Doe",
    "email": "john@example.com",
    "street_1": "123 Main St",
    "city": "Seattle",
    "state": "WA",
    "postal_code": "98101",
    "country": "US"
  },
  "transaction_items": [
    {
      "external_id": "ITEM-001",
      "external_product_id": "PROD-001",
      "product": "Product A",
      "quantity": "2.0",
      "amount": 200.00
    }
  ],
  "addresses": [
    {
      "type": "SHIP_TO",
      "street_1": "123 Main St",
      "city": "Seattle",
      "state": "WA",
      "postal_code": "98101",
      "country": "US"
    }
  ]
}

Response Fields

The API returns detailed transaction information:

id: Kintsugi’s unique transaction identifier
external_id: Your transaction identifier
date: Transaction date
total_amount: Total transaction amount
total_tax_amount_calculated: Calculated tax amount
status: Transaction status
addresses: Array of addresses
transaction_items: Array of line items
customer: Customer information (if provided)

Next Steps

Get Transactions - List and search transactions
Get Transaction By ID - Retrieve specific transaction
Update Transaction - Modify transaction details
Syncing Transaction Records - Learn more about transaction management

Authorizations

X-API-KEY

string

header

required

x-organization-id

string

header

required

Body

application/json

organization_id

string

required

deprecated

Unique identifier of the organization. This field is deprecated, and should no longer be used. The value is populated through the 'x-organization-id' header.

external_id

string

required

External identifier of the transaction.

Minimum string length: 1

date

string<date-time>

required

Transaction date and time

addresses

TransactionAddressPublic · object[]

required

Show child attributes

transaction_items

TransactionItemBuilder · object[]

required

Show child attributes

customer

Customer · object

required

Show child attributes

type

enum<string>

required

Available options:

SALE,

FULL_CREDIT_NOTE,

PARTIAL_CREDIT_NOTE,

TAX_REFUND,

ARCHIVE

requires_exemption

ExemptionRequired · object

Indicates if transaction requires tax exemption.

Show child attributes

shop_date

string

Transaction date in the shop's local timezone

shop_date_tz

string

Timezone of the shop

description

string

Description of the transaction.

refund_status

enum<string>

Status of refund, if applicable

Available options:

FULLY_REFUNDED,

PARTIALLY_REFUNDED

total_amount

number

default:0.00

Total amount of the transaction.

customer_id

string

Unique identifier of the customer.

marketplace

boolean

default:false

Indicates if transaction is marketplace-based.

exempt

enum<string>

default:NOT_EXEMPT

Exemption status (e.g., NOT_EXEMPT)

Available options:

NOT_EXEMPT,

PARTIALLY_EXEMPT,

FULLY_EXEMPT,

ZERO_RATE_NOT_EXEMPT

exemptions

Exemption · object[]

List of exemptions applied (if any).

Show child attributes

Related transaction identifier.

secondary_external_id

string

Secondary External Identifier.

secondary_source

string

Secondary source information

external_friendly_id

string

Friendly identifier of the original item.

total_tax_amount_imported

number

default:0.00

Imported tax amount.

tax_rate_imported

number

default:0.00

Imported tax rate.

total_tax_amount_calculated

number

default:0.00

Calculated tax amount.

tax_rate_calculated

number

default:0.00

Calculated tax rate.

total_tax_liability_amount

number

default:0.00

Total tax liability amount.

tax_liability_source

enum<string>

Source of tax liability.

Available options:

CALCULATED,

COLLECTED

taxable_amount

number

default:0.00

Taxable amount.

currency

enum<string>

default:USD

Currency code (ISO 4217, e.g., USD)

Available options:

AED,

AFN,

ALL,

AMD,

ANG,

AOA,

ARS,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

BGN,

BHD,

BIF,

BMD,

BND,

BOB,

BRL,

BSD,

BTN,

BWP,

BYN,

BZD,

CAD,

CDF,

CHF,

CLP,

CNY,

COP,

CRC,

CUC,

CUP,

CVE,

CZK,

DJF,

DKK,

DOP,

DZD,

EGP,

ERN,

ETB,

EUR,

FJD,

FKP,

GBP,

GEL,

GGP,

GHS,

GIP,

GMD,

GNF,

GTQ,

GYD,

HKD,

HNL,

HRK,

HTG,

HUF,

IDR,

ILS,

IMP,

INR,

IQD,

IRR,

ISK,

JEP,

JMD,

JOD,

JPY,

KES,

KGS,

KHR,

KMF,

KPW,

KRW,

KWD,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

LYD,

MAD,

MDL,

MGA,

MKD,

MMK,

MNT,

MOP,

MRU,

MUR,

MVR,

MWK,

MXN,

MYR,

MZN,

NAD,

NGN,

NIO,

NOK,

NPR,

NZD,

OMR,

PAB,

PEN,

PGK,

PHP,

PKR,

PLN,

PYG,

QAR,

RON,

RSD,

RUB,

RWF,

SAR,

SBD,

SCR,

SDG,

SEK,

SGD,

SHP,

SLL,

SOS,

SPL,

SRD,

STN,

SVC,

SYP,

SZL,

THB,

TJS,

TMT,

TND,

TOP,

TRY,

TTD,

TVD,

TWD,

TZS,

UAH,

UGX,

USD,

UYU,

UZS,

VEF,

VND,

VUV,

WST,

XAF,

XCD,

XDR,

XOF,

XPF,

YER,

ZAR,

ZMW,

ZWD

locked

boolean

default:false

Transaction lock status.

source

enum<string>

default:OTHER

Source platform (e.g., STRIPE)

Available options:

BIGCOMMERCE,

BESTBUY,

BUNNY,

CHARGEBEE,

SHOPIFY,

STRIPE,

AMAZON,

TIKTOK,

CUSTOM,

UNKNOWN,

IMPORT,

ZUORA,

APIDECK,

QUICKBOOKS,

API,

APPLE_APP_STORE,

GOOGLE_APP_STORE,

WALMART,

PAYPAL,

NETSUITE,

XERO,

MAXIO,

RECURLY,

SALESFORCE,

ETSY,

EBAY,

WIX,

SQUARESPACE,

WOOCOMMERCE,

MAGENTO,

BILLING_PLATFORM,

DEEL,

RIPPLING,

GUSTO,

FACEBOOK,

OTHER,

ORDWAY,

INSTAGRAM,

PINTEREST,

WAYFAIR,

WISH,

POS,

TARGET,

NEWEGG,

GROUPON,

GOOGLE_EXPRESS,

NOCNOC,

MERCADO_LIBRE,

MODALYST,

NORDSTROM,

FAIRE,

SHOPWARE,

ZOHO,

SAGE-INTACCT,

AIRWALLEX,

ORB,

ZENSKAR,

MICROSOFT_DYNAMICS_365,

KICKSTARTER,

INTERNAL_ERP

connection_id

string

Connection Identifier

filing_id

string

Filing identifier.

city

string

City of the transaction address.

county

string

County of the transaction address.

state

string

State of the transaction address.

country

enum<string>

Country code (ISO Alpha-2).

Available options:

AF,

AX,

AL,

DZ,

AS,

AD,

AO,

AI,

AQ,

AG,

AR,

AM,

AW,

AU,

AT,

AZ,

BS,

BH,

BD,

BB,

BY,

BE,

BZ,

BJ,

BM,

BT,

BO,

BQ,

BA,

BW,

BV,

BR,

IO,

BN,

BG,

BF,

BI,

CV,

KH,

CM,

CA,

KY,

CF,

TD,

CL,

CN,

CX,

CC,

CO,

KM,

CG,

CD,

CK,

CR,

HR,

CU,

CW,

CY,

CZ,

DK,

DJ,

DM,

DO,

EC,

EG,

SV,

GQ,

ER,

EE,

SZ,

ET,

FK,

FO,

FJ,

FI,

FR,

GF,

PF,

TF,

GA,

GM,

GE,

DE,

GH,

GI,

GR,

GL,

GD,

GP,

GU,

GT,

GG,

GN,

GW,

GY,

HT,

HM,

VA,

HN,

HK,

HU,

IS,

IN,

ID,

IR,

IQ,

IE,

IM,

IL,

IT,

CI,

JM,

JP,

JE,

JO,

KZ,

KE,

KI,

KP,

KR,

KW,

KG,

LA,

LV,

LB,

LS,

LR,

LY,

LI,

LT,

LU,

MO,

MG,

MW,

MY,

MV,

ML,

MT,

MH,

MQ,

MR,

MU,

YT,

MX,

FM,

MD,

MC,

MN,

ME,

MS,

MA,

MZ,

MM,

NA,

NR,

NP,

NL,

NC,

NZ,

NI,

NE,

NG,

NU,

NF,

MK,

MP,

NO,

OM,

PK,

PW,

PS,

PA,

PG,

PY,

PE,

PH,

PN,

PL,

PT,

PR,

QA,

RE,

RO,

RU,

RW,

BL,

SH,

KN,

LC,

MF,

PM,

VC,

WS,

SM,

ST,

SA,

SN,

RS,

SC,

SL,

SG,

SX,

SK,

SI,

SB,

SO,

ZA,

GS,

SS,

ES,

LK,

SD,

SR,

SJ,

SE,

CH,

SY,

TW,

TJ,

TZ,

TH,

TL,

TG,

TK,

TO,

TT,

TN,

TR,

TM,

TC,

TV,

UG,

UA,

AE,

GB,

US,

UM,

UY,

UZ,

VU,

VE,

VN,

VG,

VI,

WF,

EH,

YE,

ZM,

ZW,

XK,

ZZ_EU

postal_code

string

Postal code of the transaction.

tax_id

string

deprecated

Tax ID associated with the transaction. DEPRECATED: This field is only populated for QuickBooks integrations and will be removed in a future version.

status

enum<string>

default:COMMITTED

Transaction status (e.g., COMMITTED)

Available options:

PENDING,

COMMITTED,

CANCELLED,

FULLY_REFUNDED,

PARTIALLY_REFUNDED,

INVALID,

ARCHIVED

Response

Successfully created transaction

Creating Credit NotesInteractive playground for creating credit notes (refunds) for sale transactions

⌘I

Create Transaction

curl --request POST \
  --url https://api.trykintsugi.com/v1/transactions \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'x-organization-id: <api-key>' \
  --data '
{
  "organization_id": "orgn_YourOrgIdHere",
  "external_id": "YourUniqueOrder123",
  "date": "2024-01-15T14:30:00Z",
  "type": "SALE",
  "customer": {
    "organization_id": "orgn_YourOrgIdHere",
    "external_id": "Cust456",
    "name": "John Doe"
  },
  "addresses": [
    {
      "type": "SHIP_TO",
      "country": "US",
      "state": "CA",
      "city": "San Francisco",
      "postal_code": "94107",
      "street_1": "123 Main St"
    }
  ],
  "transaction_items": [
    {
      "organization_id": "orgn_YourOrgIdHere",
      "date": "2024-01-15T14:30:00Z",
      "external_product_id": "SKU-ABC",
      "product": "Example Widget",
      "quantity": 2,
      "amount": 50
    }
  ]
}
'

[
  {
    "organization_id": "orgn_YOURORGID",
    "external_id": "tran_YOURTRANSACTIONID",
    "date": "2024-01-15T14:30:00",
    "status": "COMMITTED",
    "description": "Order with one taxable book and one exempt service",
    "processing_status": "QUEUED",
    "total_amount": "200.00",
    "customer_id": "cust_afXm2qPEycF83",
    "marketplace": false,
    "exempt": "FULLY_EXEMPT",
    "exemptions": [
      {
        "updated_at": "2025-05-22T14:48:46.056060",
        "start_date": "2025-01-23",
        "transaction_id": "tran_nc5Q4hLi97NRD",
        "reseller": true,
        "status": "ACTIVE",
        "created_at": "2025-05-22T14:48:46.193109",
        "exemption_type": "transaction",
        "customer_id": "cust_afXm2qPEycF83",
        "id": "exmp_xfLpDHxxX4Cxv",
        "organization_id": "orgn_UT7zEcgwt4Fhk"
      }
    ],
    "total_tax_amount_imported": "6.00",
    "tax_rate_imported": "0.030000000",
    "total_tax_amount_calculated": "0.00",
    "tax_rate_calculated": "0E-9",
    "total_tax_liability_amount": "6.00",
    "tax_liability_source": "COLLECTED",
    "taxable_amount": "200.00",
    "currency": "USD",
    "locked": false,
    "source": "API",
    "address_status": "UNVERIFIED",
    "id": "tran_g9WJFTdFjLzDv",
    "addresses": [
      {
        "street_1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94107",
        "country": "US",
        "type": "SHIP_TO",
        "status": "UNVERIFIED",
        "id": "addr_tWqfSwDZK7aSt",
        "transaction_id": "tran_g9WJFTdFjLzDv"
      }
    ],
    "transaction_items": [
      {
        "external_id": "LI_BOOK_TAXABLE_001",
        "organization_id": "orgn_YOURORGID",
        "date": "2025-01-24T11:00:00",
        "external_product_id": "PROD_BOOK_SCIFI_HC",
        "product": "Sci-Fi Hardcover Novel",
        "product_id": "prod_AKczKRGnAe3d3",
        "quantity": "1",
        "amount": "100.00",
        "tax_amount_imported": "6.00",
        "tax_rate_imported": "0.060000000",
        "tax_amount_calculated": "0.00",
        "tax_rate_calculated": "0E-9",
        "taxable_amount": "100.00",
        "exempt": false,
        "id": "txim_c63o27oiEhLuA",
        "tax_items": [
          {
            "rule_id": "0000",
            "rate": "0.060000000",
            "amount": "6.00",
            "name": "PA State Sales Tax",
            "type": "IMPORTED",
            "jurisdiction_type": "STATE",
            "jurisdiction_name": "PA"
          }
        ],
        "total_discount": "0.00",
        "subtotal": "100.00"
      },
      {
        "external_id": "LI_SERVICE_EXEMPT_002",
        "organization_id": "orgn_YOURORGID",
        "date": "2025-01-24T11:00:00",
        "external_product_id": "PROD_DIGITAL_SERVICE_EX",
        "product": "Digital Marketing Service (Non-Taxable in PA)",
        "product_id": "prod_zz2RshS8uweRe",
        "quantity": "1",
        "amount": "100.00",
        "tax_amount_imported": "0.00",
        "tax_rate_imported": "0E-9",
        "tax_amount_calculated": "0.00",
        "tax_rate_calculated": "0E-9",
        "taxable_amount": "100.00",
        "tax_exemption": "PRODUCT",
        "exempt": false,
        "id": "txim_eqwAKmiDpgf2m",
        "tax_items": [],
        "total_discount": "0.00",
        "subtotal": "100.00"
      }
    ],
    "customer": {
      "name": "John Doe",
      "external_id": "Cust456",
      "status": "ACTIVE",
      "email": "buyer@example.com",
      "address_status": "UNVERIFIED",
      "id": "cust_afXm2qPEycF83",
      "organization_id": "orgn_YOURORGID"
    },
    "type": "SALE",
    "total_discount": "0.00",
    "subtotal": "200.00"
  }
]

​Creating Transactions

​Overview

​When to Create Transactions

​Workflow

​Step 1: Create a Transaction

​Required Fields

​Example Request

​Step 2: Retrieve Transactions

​Authentication

​Try It Out

​Common Use Cases

​Basic Transaction

​Transaction with Customer

​Response Fields

​Next Steps

​Related Resources

Authorizations

Body

Response

Creating Transactions

Overview

When to Create Transactions

Workflow

Step 1: Create a Transaction

Required Fields

Example Request

Step 2: Retrieve Transactions

Authentication

Try It Out

Common Use Cases

Basic Transaction

Transaction with Customer

Response Fields

Next Steps

Related Resources