# Creating Transactions > Interactive walkthrough for creating transactions and retrieving transaction records Source: https://docs.trykintsugi.com/docs/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 /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 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 transaction POST /v1/transactions Record a completed sale. The response returns the stored transaction. { "organization_id": "orgn_YourOrgIdHere", "external_id": "YourUniqueOrder123", "date": "2024-01-15T14:30:00Z", "type": "SALE", "currency": "USD", "marketplace": true, "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 } ], "source": "API" } { "organization_id": "orgn_YourOrgIdHere", "external_id": "YourUniqueOrder123", "date": "2024-01-15T14:30:00Z", "type": "SALE", "currency": "USD", "marketplace": true, "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 } ], "source": "API" } Run 2 Get transaction by id GET /v1/transactions/{transaction_id} Run 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 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 ## Related Resources Transactions API Reference Getting Started Support --- Index of every page: https://docs.trykintsugi.com/llms.txt