--- title: "Create portfolios order" method: POST path: "/portfolios/orders" tags: ["Portfolios"] --- # Create portfolios order `POST /portfolios/orders` ## Request - Base URL: `https://sandbox.upvest.co` - URL: `https://sandbox.upvest.co/portfolios/orders` - Auth: OAuth 2 (client credentials, token URL `https://sandbox.upvest.co/auth/token`, scopes: `portfolios:admin`) Places a buy or sell portfolio order for the specified account, distributing the cash amount across instruments according to the account's allocation weights. One underlying instrument order is generated per instrument in the allocation. See the Portfolios guide ([TOL](https://docs.upvest.co/products/tol/guides/portfolios) / [BYOL](https://docs.upvest.co/products/byol/guides/portfolios)) for implementation details. ## Headers - `idempotency-key` string, uuid, required ## Request body - object: Request body for placing a portfolio order. Specifies the account, cash amount, currency, and order side (`BUY` or `SELL`). - `user_id` string, uuid, required: Unique identifier of the user, as a UUID. - `account_id` string, uuid, required: Universally Unique Identifier (UUID) of the account. - `cash_amount` string, required: A positive decimal amount, as a string. - `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. - `side` 'BUY' | 'SELL', required: Side of the portfolio order. * BUY - * SELL - - `post_tax` boolean: Cash amount is post-tax value ## Response `200` Portfolios order - object: Represents a portfolio order — a BUY or SELL instruction that invests or withdraws a cash amount distributed across all instruments in the account's current allocation. - `id` string, uuid, required: Universally Unique Identifier (UUID) of a portfolio order. - `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) - `user_id` string, uuid: Unique identifier of the user, as a UUID. - `account_id` string, uuid, required: Universally Unique Identifier (UUID) of the account. - `allocation_id` string, uuid: Universally Unique Identifier (UUID) of a portfolio allocation. - `cash_amount` string, required: A positive decimal amount, as a string. - `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. - `status` 'NEW' | 'PROCESSING' | 'FILLED' | 'SETTLED' | 'CANCELLED', required: Execution status of the Portfolio Order. * NEW - * PROCESSING - * FILLED - * SETTLED - * CANCELLED - - `type` 'BUY' | 'SELL' | 'REBALANCING': Type of the Portfolio Order. * BUY - * SELL - * REBALANCING - - `post_tax` boolean, required: Cash amount is post-tax value - `orders` object[], required: Orders associated with this portfolio order - `id` string, uuid, required: Unique identifier for an order. Universally Unique Identifier (UUID). - `side` 'BUY' | 'SELL', required: Side of the portfolio order. * BUY - * SELL - - `status` 'NEW' | 'PROCESSING' | 'FILLED' | 'CANCELLED', required: The execution status of the order. * NEW — the order has been received and validated, awaiting routing. * PROCESSING — the order is being routed for execution. * FILLED — the order has been fully executed. * CANCELLED — the order was cancelled before being fully executed. - `client_reference` string, required: A reference string provided by the client to correlate the portfolio order with a record in the client's own system. - `initiation_flow` 'API' | 'SAVINGS_PLAN' | 'AUTO_INVESTMENT', required: Identifies what triggered the portfolio order. * API — initiated directly via the client API. * SAVINGS_PLAN — initiated by a savings plan execution. * AUTO_INVESTMENT — initiated automatically by auto-investment to invest incoming cash. - `cancellation_reason` 'ACCOUNT_IS_EMPTY' | 'CANCELLED_BY_CLIENT' | 'CANCELLED_BY_UPVEST' | 'PORTFOLIO_IS_BALANCED' | 'SELL_LIMIT_EXCEEDED': Explains the reason why the order was cancelled . * ACCOUNT_IS_EMPTY - * CANCELLED_BY_CLIENT - * CANCELLED_BY_UPVEST - * PORTFOLIO_IS_BALANCED - * SELL_LIMIT_EXCEEDED - - `cancellation_details` 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. - `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-10-03** `34243fe649c4`: 1 warning - added the new `AUTO_INVESTMENT` enum value to the `initiation_flow` response property for the response status `200` [Operation history](https://skmtc.dev/upvest/apis/upvest-investment-api/changes/portfolios/orders/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/ca69534b631d?raw)