---
title: "Add items to a transaction"
method: POST
path: "/v2/transactions/{transaction_id}/items"
tags: ["Transactions"]
---

# Add items to a transaction

`POST /v2/transactions/{transaction_id}/items`

Adds one or more items to a transaction. Items with a
`recurring_period` are billed automatically on that interval.

## Path parameters

- `transaction_id` string, required

## Headers

- `Trustap-User` string

## Request body

- object
  - `items` V2TransactionsTransactionItemBody[], required
    - `amount` integer, required — The base price of a single unit of the item, in the transaction's currency's smallest unit.
    - `amount_extra` integer — This field adds an additional cost to the item. Use it to charge a buyer for things like fulfillment costs. The `amount_extra` field is separate from the `amount` field. It applies once per item and isn't multiplied by `quantity`. This separation displays the additional cost apart from the base price on the Trustap payment page. It also helps clients track the breakdown of charges.
    - `amount_postage` integer — This field adds an additional cost to the item. Use it to charge a buyer for things like shipping costs. The `amount_postage` field is separate from the `amount` field. It applies once per item and isn't multiplied by `quantity`. This separation displays the additional cost apart from the base price on the Trustap payment page. It also helps clients track the breakdown of charges.
    - `amount_tax` integer — Unlike `amount_extra` and `amount_postage`, this field doesn't add an additional cost to the item. It's the portion of a single unit's `amount` that is tax, so use `amount` and `amount_tax` together to break the per-unit amount down into its base amount and the tax portion. The combined `quantity * (amount + amount_tax)` of all items must still equal the transaction's amount.
    - `billing_type` 'one_time' | 'recurring', required
    - `description` string, required
    - `image_url` string, absolute_url — URL of an image representing the item, shown to the buyer. Supports jpg, png, gif, bmp, webp and svg files.
    - `quantity` integer — The number of units of this item. `amount` and `amount_tax` are per-unit values: the combined `quantity * (amount + amount_tax)` across all items must equal the transaction's amount. Defaults to `1`.
    - `recurring_period` 'day' | 'week' | 'month' | 'year'
    - `ref_id` string — An optional ID that can be provided to tie the item to a resource in the client's own system.
    - `tax_code` string — A code identifying the type of goods or service being sold, used to determine the applicable tax treatment.

## Response `200`

OK

- V2TransactionsTransaction
  - `buyer` V2TransactionsUser
    - `id` string, required
    - `is_guest` boolean, required
  - `cancellation` object
    - `description` string, required
  - `client_id` string, required
  - `complaint` object
    - `accepted` string, date-time
    - `category` 'item_not_received' | 'item_not_as_described' | 'other', required
    - `description` string, required
  - `contains_shipping` boolean
  - `deadlines` object, required — This property contains all possible actions that have associated deadlines for completion. Actions with `null` do not have deadlines currently pending.
    - `complaints` string, date-time, nullable
  - `description` string, required
  - `events` V2TransactionsEvents, required
    - `by_key` object, required — These fields indicate the time that the first instance of the given event occurred. Where events can repeat (such as `refunded`), duplicate instances can be retrieved from the `by_time` sibling property.
      - `buyer_handover_confirmed` string, date-time
      - `cancelled` string, date-time
      - `claimed_by_buyer` string, date-time
      - `claimed_by_seller` string, date-time
      - `complaint_period_ended` string, date-time
      - `complaint_submitted` string, date-time
      - `created` string, date-time, required
      - `delivered` string, date-time
      - `funds_released` string, date-time
      - `joined` string, date-time
      - `order_issue_submitted` string, date-time
      - `paid` string, date-time
      - `payment_accepted` string, date-time
      - `refunded` string, date-time
      - `rejected` string, date-time
      - `review_flagged` string, date-time
      - `seller_handover_confirmed` string, date-time
      - `tracked` string, date-time
    - `by_time` object[], required
      - `at` string, date-time, required
      - `by` string — This contains the ID of the user that triggered this event. It is not present for events that are triggered by the platform, such as by automated systems.
      - `code` string, required
  - `funds_release` object
    - `payout_id` string
    - `refunds` object[], required
      - `amount` integer, required
      - `id` string, required
    - `released_to_seller` boolean, required
  - `id` string, type_id, required
  - `items` V2TransactionsTransactionItem[] — The items added to the transaction.
    - `amount` integer, required
    - `amount_extra` integer
    - `amount_postage` integer
    - `amount_tax` integer
    - `billing_type` 'one_time' | 'recurring', required
    - `created` string, date-time, required
    - `description` string, required
    - `image_url` string, absolute_url — URL of an image representing the item, shown to the buyer. Supports jpg, png, gif, bmp, webp and svg files.
    - `item_id` string, required
    - `quantity` integer
    - `recurring_period` 'day' | 'week' | 'month' | 'year'
    - `ref_id` string
    - `tax_code` string
  - `join_code` string
  - `metadata` object — Arbitrary key-value string pairs for adding extra information to transactions.
  - `order_issue` object
    - `category` 'item_not_received' | 'other', required
    - `description` string, required
  - `payment_link` string — URL to the actions page where the buyer can pay the deposit.
  - `pricing` V2TransactionsPricing, required
    - `amount` integer, required
    - `amount_extra` integer, required — Represents an additional charge to be paid by the buyer added to the transaction total. Use this field to include costs like processing fees or local taxes. Must be an integer provided in the smallest unit of the currency (for example, 500 for $5.00 USD). Defaults to 0 if not provided.
    - `amount_postage` integer — Represents an additional charge to be paid by the buyer, seller or client. Use this field to include costs like shipping surcharges. Must be an integer provided in the smallest unit of the currency (for example, 500 for $5.00 USD).
    - `currency` string, currency, required — The currency of the transaction. Note that, at present, the buyer must pay using the transaction's currency and the seller will be paid in the transaction's currency. Conversion to this currency will happen automatically during payment if the buyer pays with a different currency.
    - `fees` object, required
      - `buyer` integer, required
      - `buyer_client` integer, required
      - `international_payment` integer
      - `seller` integer, required
      - `seller_client` integer, required
    - `postage_bearer` 'buyer' | 'seller' | 'client' — Indicates who is responsible for paying the postage amount. Only present if `amount_postage` is provided.
  - `review` object
    - `approved` boolean, required
    - `outcome_reason` string, required
  - `seller` V2TransactionsUser
    - `id` string, required
    - `is_guest` boolean, required
  - `status` 'created' | 'joined' | 'rejected' | 'cancelled' | 'paid' | 'review_flagged' | 'payment_accepted' | 'complaint_submitted' | 'complaint_period_ended' | 'refunded' | 'tracked' | 'delivered' | 'funds_released' | 'claimed_by_buyer' | 'claimed_by_seller', required
  - `tracking` V2TransactionsTracking
    - `carrier` string, required
    - `tracking_code` string, required

## Other responses

- `400` — Bad Request `code` can be one of the following: * `duplicate_ref_id`: More than one item in the request has the same `ref_id`. * `items_already_added`: Items have already been added to this transaction. * `payment_not_made`: Items can only be added to a transaction once it's been paid. * `invalid_amount`: The combined `amount` + `amount_tax` of all items doesn't match the transaction's amount. * `invalid_amount_extra`: The combined `amount_extra` of all items doesn't match the transaction's `amount_extra`. * `invalid_amount_postage`: The combined `amount_postage` of all items doesn't match the transaction's `amount_postage`. * `negative_amount`: An item's `amount` cannot be negative. * `negative_amount_extra`: An item's `amount_extra` cannot be negative. * `negative_amount_postage`: An item's `amount_postage` cannot be negative. * `negative_amount_tax`: An item's `amount_tax` cannot be negative. * `amount_too_large`: An item's `amount` + `amount_extra` is too large. * `amount_too_low`: An item's `amount` is below the minimum for its currency. * `invalid_quantity`: An item's `quantity` must be greater than zero. * `invalid_billing_type`: An item's `billing_type` isn't `one_time` or `recurring`. * `invalid_recurring_period` * `recurring_period_required`: An item's `billing_type` is `recurring`, but it doesn't have a `recurring_period`. * `unexpected_recurring_period`: An item's `billing_type` is `one_time`, but it has a `recurring_period`. * `unsupported_recurring_payment_method`: An item is recurring, but the transaction's payment method doesn't support recurring items. * `unsupported_currency`
- `404` — Not Found
- `409` — Conflict `code` can be one of the following: * `item_description_mismatch`: An item with `ref_id` already exists with a different description. * `item_tax_code_mismatch`: An item with `ref_id` already exists with a different tax_code. * `item_image_url_mismatch`: An item with `ref_id` already exists with a different image_url.

## Changes

- **2026-09-25** `ee7f9f13c513` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/trustap/apis/trustap-api/changes/v2/transactions/:transaction_id/items/post.md)

---

[API](https://skmtc.dev/trustap/apis/trustap-api.md) · [All operations](https://skmtc.dev/trustap/apis/trustap-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trustap/apis/trustap-api/revisions/ee7f9f13c513?raw)