# Creating Transactions (2026-07-21)

> Interactive walkthrough for creating transactions and retrieving transaction records

Source: https://docs.trykintsugi.com/docs/2026-07-21/recipes/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 API Lab below with POST /transactions.

Example Request

{
"externalId": "order-2001",
"date": "2026-01-15T14:30:00Z",
"type": "SALE",
"currency": "USD",
"totalAmount": "100.00",
"source": "API",
"description": "Order 2001",
"addresses": [
{
"type": "SHIP_TO",
"street1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"postalCode": "94107",
"country": "US"
}
],
"items": [
{
"externalProductId": "SKU-ABC",
"date": "2026-01-15T14:30:00Z",
"product": "Widget",
"quantity": "2",
"amount": "100.00"
}
]
}

The API answers 202 Accepted. The transaction is recorded immediately and tax is calculated afterwards, so the response shows processingStatus QUEUED with tax totals of "0.00". totalTaxAmountCalculated and each line's taxItems populate once processing completes.

The returned id is not fetchable straight away: GET /transactions/{transaction_id} answers 404 until processing completes. Poll it rather than treating the first 404 as a failure.

externalId is your stable identifier for the transaction. Sending the same one again updates the existing transaction rather than creating a second.

## Step 2: Retrieve Transactions

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

Search with the search parameter, which covers the transaction id, externalId, externalFriendlyId, description and customer name

Filter by date range using startDate and endDate ( YYYY-MM-DD)

Filter by status, state, country, and more

Page through results with limit and the cursor from a prior response's nextCursor or previousCursor

The list is sorted by date, newest first, unless you set sort and order.

## Authentication

These endpoints take one credential header:

Api-Key: Your API key

Api-Version: 2026-07-21 is optional. A request without it runs against 2026-07-21. When your key can reach more than one organization, add an Organization-Id, Connection-Id or Entity-Id header to choose which one the request targets.

## Try It Out

API Lab Simulated

Run all Reset Share Copy cURL Postman

Runs in a simulated sandbox. Responses are generated from the API schema so you can explore each call safely; they never reach the live API, so the values are illustrative.

1 Create a transaction

POST /transactions

Record a completed sale. The API answers 202 Accepted and calculates tax afterwards, so processingStatus starts at QUEUED.

{

"externalId": "order-2001",

"date": "2026-01-15T14:30:00Z",

"type": "SALE",

"currency": "USD",

"totalAmount": "100.00",

"source": "API",

"description": "Order 2001",

"addresses": [

{

"type": "SHIP_TO",

"street1": "123 Main St",

"city": "San Francisco",

"state": "CA",

"postalCode": "94107",

"country": "US"

}

],

"items": [

{

"externalProductId": "SKU-ABC",

"date": "2026-01-15T14:30:00Z",

"product": "Widget",

"quantity": "2",

"amount": "100.00"

}

]

}

{
"externalId": "order-2001",
"date": "2026-01-15T14:30:00Z",
"type": "SALE",
"currency": "USD",
"totalAmount": "100.00",
"source": "API",
"description": "Order 2001",
"addresses": [
{
"type": "SHIP_TO",
"street1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"postalCode": "94107",
"country": "US"
}
],
"items": [
{
"externalProductId": "SKU-ABC",
"date": "2026-01-15T14:30:00Z",
"product": "Widget",
"quantity": "2",
"amount": "100.00"
}
]
}

Run

2 Get a transaction by id

GET /transactions/{transaction_id}

Read the transaction back. On the live API this returns 404 until processing has finished.

Run Run the previous step to fill the path.

## Required Fields

externalId: Your stable identifier for the transaction

date: When the transaction occurred. This drives which filing period it lands in, so send the real transaction time, not the time of the call

currency: ISO 4217 currency of every amount sent (for example, USD)

Within the optional arrays, each address needs a type, and each line in items needs an externalProductId and a date. type defaults to SALE. Tax jurisdiction is resolved from addresses, so an incomplete address means tax cannot be calculated accurately.

## Common Use Cases

Basic Transaction

Create a simple transaction with one address and one line:

{
"externalId": "order-2001",
"date": "2026-01-15T14:30:00Z",
"type": "SALE",
"currency": "USD",
"totalAmount": "100.00",
"source": "API",
"addresses": [
{
"type": "SHIP_TO",
"street1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"postalCode": "94107",
"country": "US"
}
],
"items": [
{
"externalProductId": "SKU-ABC",
"date": "2026-01-15T14:30:00Z",
"product": "Widget",
"quantity": "2",
"amount": "100.00"
}
]
}

Transaction with Customer

Include customer information. Omit customer for a sale with no customer identity, such as a marketplace or point-of-sale transaction; the transaction is then attributed to your organization's shared unattributed-sales customer.

{
"externalId": "order-2001",
"date": "2026-01-15T14:30:00Z",
"type": "SALE",
"currency": "USD",
"totalAmount": "100.00",
"source": "API",
"customer": {
"externalId": "cust-1001",
"name": "Acme Corp",
"email": "jane.doe@example.com"
},
"addresses": [
{
"type": "SHIP_TO",
"street1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"postalCode": "94107",
"country": "US"
}
],
"items": [
{
"externalProductId": "SKU-ABC",
"date": "2026-01-15T14:30:00Z",
"product": "Widget",
"quantity": "2",
"amount": "100.00"
}
]
}

## Response Fields

id: Kintsugi's unique identifier for the transaction

externalId: Your stable identifier for the transaction

date: When the transaction occurred; this drives filing-period assignment

totalAmount: Total transaction amount

totalTaxAmountCalculated: Total tax Kintsugi calculated

status: Settlement state of the transaction

processingStatus: How far the transaction has progressed through processing; PROCESSED means tax calculation has completed

## Next Steps

List transactions - List and search transactions

Get a transaction by id - Retrieve a specific transaction

Update a transaction - Modify transaction details

Syncing Transaction Records - Learn more about transaction management

## Related Resources

Transactions API Reference

Getting Started

Support

---

Index of every page: https://docs.trykintsugi.com/llms.txt