# Transaction items A transaction is the primary object in Trustap, representing an agreement between a buyer and seller to pay for goods or services. While a transaction can cover a single lump sum, adding transaction items enables you to break down the total cost into distinct elements. Itemizing a transaction is helpful for the following. * Order Management: Tracking distinct physical or digital items within a combined order. * Inventory & Stock Tracking: Keeping line-item records for stock allocation. * Tax & Reporting: Allocating precise tax amounts (`amount_tax`) and extra charges per item for accounting purposes. Transaction items can be added to a transaction before or after a transaction has been paid for. ## Workflow overview Adding items to a transaction follows a three-step sequence. ### Create the transaction Calculate applicable fees and create the core transaction object representing the total order value. ### Attach items Send a `POST` request to the transaction's `/items` endpoint with line-item details. ### Process payment Redirect the buyer to the generated `payment_link` to complete payment. ### Important breakdown rules When attaching items to a transaction, the sum of all individual item fields must strictly match the parent transaction values. * **Base Amount + Tax**: The sum of `item.amount` + `item.amount_tax` across all items must equal `transaction.amount`. * **Extra Charges**: The sum of `item.amount_extra` across all items must equal `transaction.amount_extra`. * **Postage/Shipping**: The sum of `item.amount_postage` across all items must equal `transaction.amount_postage`. ## Add items to a transaction ### Step 1: Calculate fees and create transaction Query the fee endpoint for your currency and payment method, then create the base transaction. #### 1. Calculate fees ```curl curl -i -X GET \ -u ':' \ 'https://api.test.trustap.com/v2/fees?currency=eur&amount=20000&amount_extra=100&amount_postage=0&payment_method=card' ``` #### 2. Create transaction Create a transaction ```curl curl -i -X POST \ https://api.test.trustap.com/v2/transactions \ -u ':' \ -H 'Content-Type: application/json' \ -d '{ "amount": 20000, "amount_extra": 100, "amount_postage": 0, "currency": "eur", "description": "Trustap socks", "fees_buyer": 1055, "payment_method": "card", "role": "buyer", "seller_id": "1-a91647f1-0cda-4d6c-b95f-b08de714dcd9", "buyer_id": "1-a5034d6a-1110-4d33-b6dd-c6ff1b3b2e28" }' ``` Response ```json { "id": "tx_01m3m96hmmed4rhyph7q555w1n", "status": "joined", "description": "Trustap socks", "payment_link": "[https://actions.stage.trustap.com/transactions/tx_01m3m96hmmed4rhyph7q555w1n/pay](https://actions.stage.trustap.com/transactions/tx_01m3m96hmmed4rhyph7q555w1n/pay)", "pricing": { "amount": 20000, "amount_extra": 100, "amount_postage": 0, "currency": "eur", "fees": { "buyer": 1055, "buyer_client": 0, "seller": 0, "seller_client": 0 }, "postage_bearer": "buyer" } } ``` ### Step 2: Add items to transaction Before payment, post the breakdown array to the transaction's `items` endpoint. Ensure the values for `amount`, `amount_tax`, `amount_extra`, and `amount_postage` follow the [breakdown rules](#important-breakdown-rules). Base + Tax Total: €(4800 + 200) + (10000 + 0) + (4800 + 200) = 20000 (Matches transaction amount) Extra Total: €50 + 40 + 10 = 100€ (Matches transaction amount_extra) Use `billing_type` to set the billing occurrence. Use `"billing_type": "one_time"` for one time payment and `"billing_type": "recurring"` for subscription billing. ```curl curl -i -X POST \ 'https://api.test.trustap.com/v2/transactions/tx_01m3m96hmmed4rhyph7q555w1n/items' \ -u ':' \ -H 'Content-Type: application/json' \ -H 'Trustap-User: 1-a91647f1-0cda-4d6c-b95f-b08de714dcd9' \ -d '{ "items": [ { "description": "red sock", "quantity": 1, "amount": 4800, "amount_tax": 200, "amount_extra": 50, "amount_postage": 0, "billing_type": "one_time" }, { "description": "blue sock", "quantity": 1, "amount": 10000, "amount_tax": 0, "amount_extra": 40, "amount_postage": 0, "billing_type": "one_time" }, { "description": "green sock", "quantity": 1, "amount": 4800, "amount_tax": 200, "amount_extra": 10, "amount_postage": 0, "billing_type": "one_time" } ] }' ``` When the items endpoint returns, the transaction object includes an items array with assigned item IDs (item_id) and timestamps. ```json { "id": "tx_01m3m96hmmed4rhyph7q555w1n", "status": "paid", "description": "Trustap socks", "items": [ { "item_id": "it_01m3m9pf9yed4ta6yb8dwdq89t", "description": "red sock", "quantity": 1, "amount": 4800, "amount_tax": 200, "amount_extra": 50, "amount_postage": 0, "billing_type": "one_time", "created": "2026-09-28T15:21:23.030670445Z" }, { "item_id": "it_01m3m9pfa4ed4r12mpvzz9zt3f", "description": "blue sock", "quantity": 1, "amount": 10000, "amount_tax": 0, "amount_extra": 40, "amount_postage": 0, "billing_type": "one_time", "created": "2026-09-28T15:21:23.030670445Z" }, { "item_id": "it_01m3m9pfa9ed4stzk0mck71na8", "description": "green sock", "quantity": 1, "amount": 4800, "amount_tax": 200, "amount_extra": 10, "amount_postage": 0, "billing_type": "one_time", "created": "2026-09-28T15:21:23.030670445Z" } ], "pricing": { "amount": 20000, "amount_extra": 100, "amount_postage": 0, "currency": "eur", "fees": { "buyer": 1055, "buyer_client": 0, "international_payment": 316, "seller": 0, "seller_client": 0 }, "postage_bearer": "buyer" } } ``` ### Step 3: Complete payment Redirect the buyer to the payment_link returned in the creation payload: ``` https://actions.stage.trustap.com/transactions/tx_01m3m96hmmed4rhyph7q555w1n/pay?redirect_uri= ``` Once the user completes checkout, the transaction state updates to `"status": "paid"`.