--- title: "Create a transaction fee model" method: POST path: "/transaction_fees/models" tags: ["Transaction Fees Models"] --- # Create a transaction fee model `POST /transaction_fees/models` Creates a transaction fee model that defines how per-order transaction fees are calculated — either as fixed cash amounts (`ABSOLUTE`) or in basis points of the order value (`RELATIVE`), with one or more tiers based on the order's cash amount. Fee models are immutable once created; to change a fee structure, create a new model. Apply a model to an order by referencing its ID in the `fee_configuration` object of the order request. See the Building transaction fees guide ([TOL](https://docs.upvest.co/products/tol/guides/fees/fees_transaction_fees_building) / [BYOL](https://docs.upvest.co/products/byol/guides/fees/fees_transaction_fees_building)) for implementation details. ## Request body - object — Request to create a transaction fee model. Defines the currency, charge method, value type, application type, base amount scope, and the fee tiers. Transaction fee models are immutable once created. - `label` string, required — A human-readable label for the transaction fee model. - `currency` 'EUR' | 'GBP', required — Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. * EUR — Euro. * GBP — Pound Sterling. - `charge_method` 'CHARGED_BY_CLIENT' | 'COLLECTED_BY_UPVEST', required — Indicates how the transaction fee is charged. * `CHARGED_BY_CLIENT` — The fee is charged by the client as part of post-trade settlement; the fee movement occurs outside Upvest cash balances. * `COLLECTED_BY_UPVEST` — The fee is charged by the client and collected by Upvest; the fee amount is debited from the user's Upvest cash balance. - `value_type` 'ABSOLUTE' | 'RELATIVE', required — The value type of the transaction fee model. * `ABSOLUTE` — Tier fees are fixed cash amounts. * `RELATIVE` — Tier fees are percentages of the order value, expressed in basis points. - `application_type` 'VOLUME', required — The application type of the transaction fee model. * `VOLUME` — The full order value is assessed against the tier thresholds, and the matching tier's fee applies to the total order volume. - `base_amount_scope` 'GROSS_AMOUNT' | 'ORDER', required — The scope of the base amount that fee tiers are evaluated against. * `GROSS_AMOUNT` — Tiers are evaluated against the gross cash amount of the transaction the fee model is applied to (e.g. the total cash value of an order, a contribution or a transfer). * `ORDER` — Tiers are evaluated against the total cash value of each order. DEPRECATED: Use `GROSS_AMOUNT` instead. Existing fee models using `ORDER` continue to work unchanged. - `tiers` union[], required — The tiers of the transaction fee model. - union — A single tier of a transaction fee model — either an absolute tier with a fixed cash amount or a relative tier defined in basis points. - object — A single tier of a transaction fee model with a fixed, absolute cash amount. - `tier_id` string, required — Unique identifier of the fee tier within the transaction fee model. A numeric string of up to 63 digits. - `base_amount_from` string, required — A positive decimal amount, as a string. - `fee_amount` string, required — A positive decimal amount, as a string. - object — A single tier of a transaction fee model based on a percentage (defined in basis points). - `tier_id` string, required — Unique identifier of the fee tier within the transaction fee model. A numeric string of up to 63 digits. - `base_amount_from` string, required — A positive decimal amount, as a string. - `fee_bps` string, required — A positive decimal amount, as a string. - `min_fee_amount` string — A positive decimal amount, as a string. - `max_fee_amount` string — A positive decimal amount, as a string. ## Response `200` OK - object — A transaction fee model. Defines how per-order transaction fees are calculated, as a set of tiers with either absolute cash amounts or relative basis-point values. Assign a model to an order via the `fee_configuration` array when placing the order. - `id` string, uuid, required — Universally Unique Identifier (UUID) of the transaction fee model. - `created_at` string, date-time, required — Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html) - `updated_at` string, date-time, required — Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html) - `label` string, required — A human-readable label for the transaction fee model. - `currency` 'EUR' | 'GBP', required — Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. * EUR — Euro. * GBP — Pound Sterling. - `charge_method` 'CHARGED_BY_CLIENT' | 'COLLECTED_BY_UPVEST', required — Indicates how the transaction fee is charged. * `CHARGED_BY_CLIENT` — The fee is charged by the client as part of post-trade settlement; the fee movement occurs outside Upvest cash balances. * `COLLECTED_BY_UPVEST` — The fee is charged by the client and collected by Upvest; the fee amount is debited from the user's Upvest cash balance. - `value_type` 'ABSOLUTE' | 'RELATIVE', required — The value type of the transaction fee model. * `ABSOLUTE` — Tier fees are fixed cash amounts. * `RELATIVE` — Tier fees are percentages of the order value, expressed in basis points. - `application_type` 'VOLUME', required — The application type of the transaction fee model. * `VOLUME` — The full order value is assessed against the tier thresholds, and the matching tier's fee applies to the total order volume. - `base_amount_scope` 'GROSS_AMOUNT' | 'ORDER', required — The scope of the base amount that fee tiers are evaluated against. * `GROSS_AMOUNT` — Tiers are evaluated against the gross cash amount of the transaction the fee model is applied to (e.g. the total cash value of an order, a contribution or a transfer). * `ORDER` — Tiers are evaluated against the total cash value of each order. DEPRECATED: Use `GROSS_AMOUNT` instead. Existing fee models using `ORDER` continue to work unchanged. - `tiers` union[], required — The tiers of the transaction fee model. - union — A single tier of a transaction fee model — either an absolute tier with a fixed cash amount or a relative tier defined in basis points. - object — A single tier of a transaction fee model with a fixed, absolute cash amount. - `tier_id` string, required — Unique identifier of the fee tier within the transaction fee model. A numeric string of up to 63 digits. - `base_amount_from` string, required — A positive decimal amount, as a string. - `fee_amount` string, required — A positive decimal amount, as a string. - object — A single tier of a transaction fee model based on a percentage (defined in basis points). - `tier_id` string, required — Unique identifier of the fee tier within the transaction fee model. A numeric string of up to 63 digits. - `base_amount_from` string, required — A positive decimal amount, as a string. - `fee_bps` string, required — A positive decimal amount, as a string. - `min_fee_amount` string — A positive decimal amount, as a string. - `max_fee_amount` string — A positive decimal amount, as a string. ## Other responses - `400` — Bad Request. The incoming request had a malformed parameter/object. - `401` — Unauthorized. The caller has not been authenticated. - `403` — Forbidden. The caller has been authenticated but is not allowed to take the requested action. - `404` — Not Found. The requested resource could not be found. - `406` — Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. "Accept" header defined unsupported value. - `409` — Conflict. An operation is not available for the current state of the resource. - `429` — Too Many Requests. The caller has exceeded their quota for the time period and has been throttled. - `500` — Internal Server Error. The service encountered an unexpected error. - `503` — Service Unavailable. The service handling for this request cannot be reached at this time. - `504` — Gateway Timeout. The service gateway has reached its internal timeout. ## Changes - **2026-09-23** `25a6cd1e39de` — 2 warning, 2 info - added the new `COLLECTED_BY_UPVEST` enum value to the `charge_method` response property for the response status `200` - added the new `GROSS_AMOUNT` enum value to the `base_amount_scope` response property for the response status `200` - added the new `COLLECTED_BY_UPVEST` enum value to the request property `charge_method` - added the new `GROSS_AMOUNT` enum value to the request property `base_amount_scope` [Change history](https://skmtc.dev/upvest/apis/upvest-investment-api/changes/transaction_fees/models/post.md) --- [API](https://skmtc.dev/upvest/apis/upvest-investment-api.md) · [All operations](https://skmtc.dev/upvest/apis/upvest-investment-api/llms.txt) · [OpenAPI document](https://skmtc.dev/upvest/apis/upvest-investment-api/revisions/34243fe649c4?raw)