{"templateId":"markdown","versions":[{"version":"v1.0","label":"v1.0","link":"/docs/v1.0/guides/transactions/transaction-items","default":false,"active":false,"folderId":"a2557b8d"},{"version":"v2.0","label":"v2.0 (latest version)","link":"/docs/guides/transactions/transaction-items","default":true,"active":true,"folderId":"a2557b8d"}],"sharedDataIds":{"sidebar":"sidebar-docs/@v1.0/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["DSteps","DStep","tabs","tab"]},"type":"markdown"},"seo":{"title":"Add Items to a Transaction | Trustap Documentation","description":"Learn how to break down a Trustap transaction into individual itemized elements to track stock, taxes, and multi-item orders.","llmstxt":{"hide":false,"title":"Trustap API","description":"Trustap is an API for end-to-end transaction solution that seamlessly integrates payments, fulfillment, and support into your marketplace. Trustap is an escrow like API service facilitating secure transactions.","sections":[{"title":"Intro","description":"Trustap API introduction.","includeFiles":["**/docs/@v2.0/intro/*.md"],"excludeFiles":[]},{"title":"Concepts","description":"Trustap Concepts","includeFiles":["**/docs/@v2.0/concepts/*.md"],"excludeFiles":[]},{"title":"Guides","description":"Trustap integration guides","includeFiles":["**/docs/@v2.0/guides/**/*.md"],"excludeFiles":["**/docs/@v2.0/guides/listing/"]},{"title":"API Reference","description":"Trustap API reference guide","includeFiles":["**/apis/@v2.0/openapi.yaml"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"transaction-items","__idx":0},"children":["Transaction items"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Itemizing a transaction is helpful for the following."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Order Management: Tracking distinct physical or digital items within a combined order."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Inventory & Stock Tracking: Keeping line-item records for stock allocation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Tax & Reporting: Allocating precise tax amounts (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount_tax"]},") and extra charges per item for accounting purposes."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Transaction items can be added to a transaction before or after a transaction has been paid for."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"workflow-overview","__idx":1},"children":["Workflow overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Adding items to a transaction follows a three-step sequence."]},{"$$mdtype":"Tag","name":"DSteps","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-the-transaction","__idx":2},"children":["Create the transaction"]},{"$$mdtype":"Tag","name":"DStep","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Calculate applicable fees and create the core transaction object representing the total order value."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"attach-items","__idx":3},"children":["Attach items"]},{"$$mdtype":"Tag","name":"DStep","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," request to the transaction's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/items"]}," endpoint with line-item details."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"process-payment","__idx":4},"children":["Process payment"]},{"$$mdtype":"Tag","name":"DStep","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redirect the buyer to the generated ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_link"]}," to complete payment."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"important-breakdown-rules","__idx":5},"children":["Important breakdown rules"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When attaching items to a transaction, the sum of all individual item fields must strictly match the parent transaction values."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Base Amount + Tax"]},": The sum of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["item.amount"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["item.amount_tax"]}," across all items must equal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.amount"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Extra Charges"]},": The sum of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["item.amount_extra"]}," across all items must equal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.amount_extra"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Postage/Shipping"]},": The sum of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["item.amount_postage"]}," across all items must equal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.amount_postage"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"add-items-to-a-transaction","__idx":6},"children":["Add items to a transaction"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-1-calculate-fees-and-create-transaction","__idx":7},"children":["Step 1: Calculate fees and create transaction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Query the fee endpoint for your currency and payment method, then create the base transaction."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"1-calculate-fees","__idx":8},"children":["1. Calculate fees"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"curl","header":{"controls":{"copy":{}}},"source":"curl -i -X GET \\\n  -u '<API_KEY>:' \\\n  'https://api.test.trustap.com/v2/fees?currency=eur&amount=20000&amount_extra=100&amount_postage=0&payment_method=card'\n","lang":"curl"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"2-create-transaction","__idx":9},"children":["2. Create transaction"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Create a transaction","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"curl","header":{"controls":{"copy":{}}},"source":"curl -i -X POST \\\n  https://api.test.trustap.com/v2/transactions \\\n  -u '<API_KEY>:' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"amount\": 20000,\n    \"amount_extra\": 100,\n    \"amount_postage\": 0,\n    \"currency\": \"eur\",\n    \"description\": \"Trustap socks\",\n    \"fees_buyer\": 1055,\n    \"payment_method\": \"card\",\n    \"role\": \"buyer\",\n    \"seller_id\": \"1-a91647f1-0cda-4d6c-b95f-b08de714dcd9\",\n    \"buyer_id\": \"1-a5034d6a-1110-4d33-b6dd-c6ff1b3b2e28\"\n  }'\n","lang":"curl"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Response","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"tx_01m3m96hmmed4rhyph7q555w1n\",\n  \"status\": \"joined\",\n  \"description\": \"Trustap socks\",\n  \"payment_link\": \"[https://actions.stage.trustap.com/transactions/tx_01m3m96hmmed4rhyph7q555w1n/pay](https://actions.stage.trustap.com/transactions/tx_01m3m96hmmed4rhyph7q555w1n/pay)\",\n  \"pricing\": {\n    \"amount\": 20000,\n    \"amount_extra\": 100,\n    \"amount_postage\": 0,\n    \"currency\": \"eur\",\n    \"fees\": {\n      \"buyer\": 1055,\n      \"buyer_client\": 0,\n      \"seller\": 0,\n      \"seller_client\": 0\n    },\n    \"postage_bearer\": \"buyer\"\n  }\n}\n","lang":"json"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-2-add-items-to-transaction","__idx":10},"children":["Step 2: Add items to transaction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before payment, post the breakdown array to the transaction's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["items"]}," endpoint."," ","Ensure the values for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount_tax"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount_extra"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount_postage"]}," follow the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#important-breakdown-rules"},"children":["breakdown rules"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Base + Tax Total:"," ","€(4800 + 200) + (10000 + 0) + (4800 + 200) = 20000 (Matches transaction amount)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Extra Total:"," ","€50 + 40 + 10 = 100€ (Matches transaction amount_extra)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["billing_type"]}," to set the billing occurrence. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"billing_type\": \"one_time\""]}," for one time payment and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"billing_type\": \"recurring\""]}," for subscription billing."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"curl","header":{"controls":{"copy":{}}},"source":"curl -i -X POST \\\n  'https://api.test.trustap.com/v2/transactions/tx_01m3m96hmmed4rhyph7q555w1n/items' \\\n  -u '<API_KEY>:' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Trustap-User: 1-a91647f1-0cda-4d6c-b95f-b08de714dcd9' \\\n  -d '{\n    \"items\": [\n      {\n        \"description\": \"red sock\",\n        \"quantity\": 1,\n        \"amount\": 4800,\n        \"amount_tax\": 200,\n        \"amount_extra\": 50,\n        \"amount_postage\": 0,\n        \"billing_type\": \"one_time\"\n      },\n      {\n        \"description\": \"blue sock\",\n        \"quantity\": 1,\n        \"amount\": 10000,\n        \"amount_tax\": 0,\n        \"amount_extra\": 40,\n        \"amount_postage\": 0,\n        \"billing_type\": \"one_time\"\n      },\n      {\n        \"description\": \"green sock\",\n        \"quantity\": 1,\n        \"amount\": 4800,\n        \"amount_tax\": 200,\n        \"amount_extra\": 10,\n        \"amount_postage\": 0,\n        \"billing_type\": \"one_time\"\n      }\n    ]\n  }'\n","lang":"curl"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the items endpoint returns, the transaction object includes an items array with assigned item IDs (item_id) and timestamps."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"tx_01m3m96hmmed4rhyph7q555w1n\",\n  \"status\": \"paid\",\n  \"description\": \"Trustap socks\",\n  \"items\": [\n    {\n      \"item_id\": \"it_01m3m9pf9yed4ta6yb8dwdq89t\",\n      \"description\": \"red sock\",\n      \"quantity\": 1,\n      \"amount\": 4800,\n      \"amount_tax\": 200,\n      \"amount_extra\": 50,\n      \"amount_postage\": 0,\n      \"billing_type\": \"one_time\",\n      \"created\": \"2026-09-28T15:21:23.030670445Z\"\n    },\n    {\n      \"item_id\": \"it_01m3m9pfa4ed4r12mpvzz9zt3f\",\n      \"description\": \"blue sock\",\n      \"quantity\": 1,\n      \"amount\": 10000,\n      \"amount_tax\": 0,\n      \"amount_extra\": 40,\n      \"amount_postage\": 0,\n      \"billing_type\": \"one_time\",\n      \"created\": \"2026-09-28T15:21:23.030670445Z\"\n    },\n    {\n      \"item_id\": \"it_01m3m9pfa9ed4stzk0mck71na8\",\n      \"description\": \"green sock\",\n      \"quantity\": 1,\n      \"amount\": 4800,\n      \"amount_tax\": 200,\n      \"amount_extra\": 10,\n      \"amount_postage\": 0,\n      \"billing_type\": \"one_time\",\n      \"created\": \"2026-09-28T15:21:23.030670445Z\"\n    }\n  ],\n  \"pricing\": {\n    \"amount\": 20000,\n    \"amount_extra\": 100,\n    \"amount_postage\": 0,\n    \"currency\": \"eur\",\n    \"fees\": {\n      \"buyer\": 1055,\n      \"buyer_client\": 0,\n      \"international_payment\": 316,\n      \"seller\": 0,\n      \"seller_client\": 0\n    },\n    \"postage_bearer\": \"buyer\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-3-complete-payment","__idx":11},"children":["Step 3: Complete payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redirect the buyer to the payment_link returned in the creation payload:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://actions.stage.trustap.com/transactions/tx_01m3m96hmmed4rhyph7q555w1n/pay?redirect_uri=<YOUR-REDIRECT-URI>\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once the user completes checkout, the transaction state updates to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"status\": \"paid\""]},"."]}]},"headings":[{"value":"Transaction items","id":"transaction-items","depth":1},{"value":"Workflow overview","id":"workflow-overview","depth":2},{"value":"Create the transaction","id":"create-the-transaction","depth":3},{"value":"Attach items","id":"attach-items","depth":3},{"value":"Process payment","id":"process-payment","depth":3},{"value":"Important breakdown rules","id":"important-breakdown-rules","depth":3},{"value":"Add items to a transaction","id":"add-items-to-a-transaction","depth":2},{"value":"Step 1: Calculate fees and create transaction","id":"step-1-calculate-fees-and-create-transaction","depth":3},{"value":"1. Calculate fees","id":"1-calculate-fees","depth":4},{"value":"2. Create transaction","id":"2-create-transaction","depth":4},{"value":"Step 2: Add items to transaction","id":"step-2-add-items-to-transaction","depth":3},{"value":"Step 3: Complete payment","id":"step-3-complete-payment","depth":3}],"frontmatter":{"title":"Transaction Items","seo":{"title":"Add Items to a Transaction | Trustap Documentation","description":"Learn how to break down a Trustap transaction into individual itemized elements to track stock, taxes, and multi-item orders."}},"lastModified":"2026-10-20T13:57:16.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/guides/transactions/transaction-items","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}