KintsugiKintsugi
API Lab

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

  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 /v1/transactions.

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

API LabSimulated
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.
1Create transaction
POST/v1/transactions

Record a completed sale. The response returns the stored transaction.

2Get transaction by id
GET/v1/transactions/{transaction_id}
Run the previous step to fill the path.

Required Fields

  • external_id: Your unique order identifier
  • date: Transaction date in ISO 8601 format
  • type: Transaction type (for example, SALE)
  • currency: Three-letter currency code (for example, USD)
  • customer: The customer associated with the sale
  • addresses: Transaction addresses; the ship-to address determines the tax jurisdiction
  • transaction_items: The line items sold, each with an amount

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

  • 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

Next Steps

Related Resources