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.

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

1. Create a Transaction - Record a completed sale
2. 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.

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

Try It Out

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

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