# Cambiar el precio de activación de la orden
`PATCH /orders/{orderId}`
Edita una orden pendiente: precio de activación, `amount` reservado, tolerancia al deslizamiento, o tamaño base. El motor hace esto reemplazando la orden, por lo que la
respuesta contiene una **nueva orden con un nuevo identificador**, mientras que la anterior termina como `canceled_by_update`.
Verificado más allá del esquema:
- La orden debe existir y seguir estando `active`, y su cuenta debe pertenecer al solicitante y estar en un estado de trading.
- Las órdenes `market` y `liquidation` no se pueden editar en absoluto, ni tampoco una orden `stop` / `take` que se creó sin un precio de activación (`order_not_updatable`); un precio de activación que está establecido no se puede restablecer a `0` (`trigger_price_reset_forbidden`).
- Aumentar la reserva de una orden de incremento requiere la diferencia como saldo libre, y se rechaza mientras la cuenta esté bloqueada por el límite de capital gestionado.
- Una orden creada con `sizeMode: base` necesita un `amount` nuevo siempre que `baseSize` cambie (`base_size_requires_amount`).
- El mercado debe estar abierto, y la orden resultante se vuelve a comprobar exactamente como en la creación — la misma forma de campos, precio de activación y códigos de nocional listados en `POST /orders` se aplican aquí, excepto `invalid_leverage`: el apalancamiento no se puede editar.
Una solicitud que no establece ninguno de los campos no cambia nada y devuelve la orden tal como está.
## Autorización
bearer: http · bearer (obligatorio). Clave de API personal, con el prefijo `usk_`.
## Parámetros
- path: orderId (string · uuid; obligatorio). Identificador de la orden que se va a editar.
Tipo: string · uuid
format: uuid
## Cuerpo de la solicitud · OrderUpdateRequest
application/json · obligatorio
Esquema: OrderUpdateRequest
Tipo: object
Campos obligatorios: ninguno
- triggerPrice (string · int32; opcional)
triggerPrice ejemplo: 65000000000000
triggerPrice.Tipo: string · int32
triggerPrice.Nuevo precio de activación, fp9 en bruto. Los límites se vuelven a comprobar contra el precio de mercado actual (y, para `stop` / `take`, contra el precio de liquidación de la posición). Un precio de activación que ya está establecido no se puede restablecer a `0`.
triggerPrice.format: int32
triggerPrice.pattern: ^(?:-?[1-9][0-9]*|0)$
- amount (string · int32; opcional)
amount ejemplo: 100000000000
amount.Tipo: string · int32
amount.Nuevo `amount`, fp9 en bruto, en la unidad que usa su clase de orden — consulte el mismo campo en la creación de la orden. En una orden de aumento, es la reserva de cotización: aumentarla requiere que la diferencia esté disponible como saldo libre, y se requiere junto con `baseSize` en una orden de tamaño `base`. En una orden de cierre, es el tamaño del activo base de la posición que se va a cerrar.
amount.format: int32
amount.pattern: ^(?:-?[1-9][0-9]*|0)$
- expectedAmount (string · int32; opcional)
expectedAmount ejemplo: 1000000000
expectedAmount.Tipo: string · int32
expectedAmount.Nueva tolerancia de deslizamiento, fp9 en bruto. Consulte el mismo campo en la creación de la orden.
expectedAmount.format: int32
expectedAmount.pattern: ^(?:-?[1-9][0-9]*|0)$
- baseSize (string · int32; opcional)
baseSize ejemplo: 1000000000
baseSize.Tipo: string · int32
baseSize.Nuevo tamaño en unidades del activo base, fp9 en bruto. Solo para órdenes creadas con `sizeMode: base`.
baseSize.format: int32
baseSize.pattern: ^(?:-?[1-9][0-9]*|0)$
Ejemplo
```json
{}
```
## Ejemplo · cURL
```bash
curl --request PATCH 'https://api.upscale.trade/orders/{orderId}' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{}'
```
## Ejemplo · JavaScript
```javascript
const response = await fetch("https://api.upscale.trade/orders/{orderId}", {
method: "PATCH",
headers: {
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
body: "{}",
});
console.log(response.status, await response.text());
```
## Ejemplo · Python
```python
import requests
response = requests.request(
"PATCH",
"https://api.upscale.trade/orders/{orderId}",
headers={"Accept":"application/json","Authorization":"Bearer YOUR_API_KEY","Content-Type":"application/json"},
data="{}",
timeout=30,
)
print(response.status_code, response.text)
```
## Respuesta 401
**401** — No autorizado
## Respuesta 403
**403** — La orden ya no está activa. La cuenta pertenece a otro usuario (`account_access_denied`), o la solicitud está autenticada con una clave de API mientras `api_trading` está deshabilitado en la cuenta (`api_trading_not_enabled`). El trading en la cuenta ha terminado en su estado actual (`challenge_closed`), o la cuenta está bloqueada por el límite de capital gestionado (`funded_limit_trading_locked`). El mercado está en pausa (`market_paused`) o solo acepta órdenes de cierre (`market_close_only`).
## Respuesta 404
**404** — No hay ninguna orden con este identificador.
## Respuesta 429
**429** — Se superó el límite de velocidad de la clave de API (`api_key_rate_limit_exceeded`). `Retry-After` indica cuándo volver; el cuerpo incluye el bucket (`read` / `write`), la ventana que se activó, su límite y `retryAt`.
## Respuesta default · OrderResponse
**default** application/json — Respuesta
Esquema: OrderResponse
Tipo: object
Campos obligatorios: id, txId, trader, market, status, type, direction, triggerPrice, requestedTriggerPrice, stopPrice, limitPrice, stopTriggerPrice, takeTriggerPrice, trailingStopActivationPrice, trailingStopOffset, trailingStopOffsetPercent, leverage, index, positionId, parentOrderId, expiration, amount, indexPrice, settlementOraclePrice, createdAt, error, realizedPnl, rawRealizedPnl, profitAdjustmentApplied, executedAfterPause, sizeMode, baseSize, reservedAmount, errorCode, reason
Tipos de campos obligatorios: id (string · uuid; obligatorio), txId (string; obligatorio), trader (string · uuid; obligatorio), market (string · uuid; obligatorio), status (string · enum; obligatorio), type (string · enum; obligatorio), direction (string · enum; obligatorio), triggerPrice (string · int32; obligatorio), requestedTriggerPrice (string · int32 · nullable; obligatorio), stopPrice (string · int32; obligatorio), limitPrice (string · int32; obligatorio), stopTriggerPrice (string · int32; obligatorio), takeTriggerPrice (string · int32; obligatorio), trailingStopActivationPrice (string · int32; obligatorio), trailingStopOffset (string · int32; obligatorio), trailingStopOffsetPercent (string · int32; obligatorio), leverage (string · int32 · nullable; obligatorio), index (string; obligatorio), positionId (string[]; obligatorio), parentOrderId (string[]; obligatorio), expiration (string · date-time · nullable; obligatorio), amount (string · int32; obligatorio), indexPrice (string · int32 · nullable; obligatorio), settlementOraclePrice (string · int32; obligatorio), createdAt (string · date-time; obligatorio), error (string[]; obligatorio), realizedPnl (string · int32 · nullable; obligatorio), rawRealizedPnl (string · int32 · nullable; obligatorio), profitAdjustmentApplied (boolean; obligatorio), executedAfterPause (boolean; obligatorio), sizeMode (string · enum; obligatorio), baseSize (string · int32 · nullable; obligatorio), reservedAmount (string · int32 · nullable; obligatorio), errorCode (string[]; obligatorio), reason (string · enum · nullable; obligatorio)
- id (string · uuid; obligatorio)
id ejemplo: 00000000-0000-4000-8000-000000000000
id.Tipo: string · uuid
id.Identificador de la orden.
id.format: uuid
id.pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
- txId (string; obligatorio)
txId ejemplo: string
txId.Tipo: string
txId.Identificador de la orden. Se conserva por compatibilidad con versiones anteriores, siempre igual a `id`.
- trader (string · uuid; obligatorio)
trader ejemplo: 00000000-0000-4000-8000-000000000000
trader.Tipo: string · uuid
trader.Cuenta del trader a la que pertenece la orden.
trader.format: uuid
trader.pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
- market (string · uuid; obligatorio)
market ejemplo: 00000000-0000-4000-8000-000000000000
market.Tipo: string · uuid
market.Mercado en el que se coloca la orden.
market.format: uuid
market.pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
- status (string · enum; obligatorio)
status ejemplo: active
status.Tipo: string · enum
status.Estado del ciclo de vida: `active` mientras espera, `executed` una vez ejecutada, `canceled` cuando es cancelada por el trader o la plataforma, `canceled_by_update` cuando es reemplazada por una edición, `canceled_by_position` cuando la posición a la que estaba vinculada desapareció, `canceled_by_error` cuando falló la ejecución — consulta `errorCode`.
status.Valores permitidos: ["active","canceled","canceled_by_update","canceled_by_error","canceled_by_position","executed"]
- type (string · enum; obligatorio)
type ejemplo: market
type.Tipo: string · enum
type.Tipo de orden. `liquidation` marca una orden que el propio motor generó.
type.Valores permitidos: ["market","limit","stop","trailing_stop","take","stop_limit","stop_market","liquidation"]
- direction (string · enum; obligatorio)
direction ejemplo: long
direction.Tipo: string · enum
direction.Dirección de la orden.
direction.Valores permitidos: ["long","short"]
- triggerPrice (string · int32; obligatorio)
triggerPrice ejemplo: 1000000000
triggerPrice.Tipo: string · int32
triggerPrice.Precio al que se dispara la orden, fp9 en bruto. `0` cuando la orden no lleva disparador.
triggerPrice.format: int32
triggerPrice.pattern: ^(?:-?[1-9][0-9]*|0)$
- requestedTriggerPrice (string · int32 · nullable; obligatorio)
requestedTriggerPrice ejemplo: 1000000000
requestedTriggerPrice.Tipo: string · int32 · nullable
requestedTriggerPrice.Precio de activación tal como se solicitó, antes de que el motor lo desplazara hasta la distancia mínima de stop, fp9 en bruto. Nulo cuando el precio solicitado se mantuvo tal cual.
requestedTriggerPrice.format: int32
requestedTriggerPrice.pattern: ^(?:-?[1-9][0-9]*|0)$
- stopPrice (string · int32; obligatorio)
stopPrice ejemplo: 1000000000
stopPrice.Tipo: string · int32
stopPrice.Precio de activación de una orden `stop_market` / `stop_limit`, fp9 en bruto; `0` para cualquier otro tipo.
stopPrice.format: int32
stopPrice.pattern: ^(?:-?[1-9][0-9]*|0)$
- limitPrice (string · int32; obligatorio)
limitPrice ejemplo: 1000000000
limitPrice.Tipo: string · int32
limitPrice.Precio al que se coloca la orden una vez activada, fp9 en bruto: el precio stop-limit, recurriendo al precio de activación como alternativa.
limitPrice.format: int32
limitPrice.pattern: ^(?:-?[1-9][0-9]*|0)$
- stopTriggerPrice (string · int32; obligatorio)
stopTriggerPrice ejemplo: 1000000000
stopTriggerPrice.Tipo: string · int32
stopTriggerPrice.Stop-loss asociado a la orden, fp9 en bruto. `0` cuando no hay ninguno asociado.
stopTriggerPrice.format: int32
stopTriggerPrice.pattern: ^(?:-?[1-9][0-9]*|0)$
- takeTriggerPrice (string · int32; obligatorio)
takeTriggerPrice ejemplo: 1000000000
takeTriggerPrice.Tipo: string · int32
takeTriggerPrice.Take-profit asociado a la orden, fp9 en bruto. `0` cuando no hay ninguno asociado.
takeTriggerPrice.format: int32
takeTriggerPrice.pattern: ^(?:-?[1-9][0-9]*|0)$
- trailingStopActivationPrice (string · int32; obligatorio)
trailingStopActivationPrice ejemplo: 1000000000
trailingStopActivationPrice.Tipo: string · int32
trailingStopActivationPrice.Precio al que un stop móvil comienza a hacer seguimiento, fp9 sin procesar. `0` cuando hace seguimiento desde la creación.
trailingStopActivationPrice.format: int32
trailingStopActivationPrice.pattern: ^(?:-?[1-9][0-9]*|0)$
- trailingStopOffset (string · int32; obligatorio)
trailingStopOffset ejemplo: 1000000000
trailingStopOffset.Tipo: string · int32
trailingStopOffset.Distancia de seguimiento como un importe absoluto de cotización, fp9 sin procesar. `0` cuando la distancia se establece como porcentaje.
trailingStopOffset.format: int32
trailingStopOffset.pattern: ^(?:-?[1-9][0-9]*|0)$
- trailingStopOffsetPercent (string · int32; obligatorio)
trailingStopOffsetPercent ejemplo: 1000000000
trailingStopOffsetPercent.Tipo: string · int32
trailingStopOffsetPercent.Distancia de seguimiento como una fracción del precio, fp9 sin procesar. `0` cuando la distancia es absoluta.
trailingStopOffsetPercent.format: int32
trailingStopOffsetPercent.pattern: ^(?:-?[1-9][0-9]*|0)$
- leverage (string · int32 · nullable; obligatorio)
leverage ejemplo: 1000000000
leverage.Tipo: string · int32 · nullable
leverage.Apalancamiento de la orden, fp9 en bruto. Nulo en órdenes de cierre, que heredan el apalancamiento de la posición.
leverage.format: int32
leverage.pattern: ^(?:-?[1-9][0-9]*|0)$
- index (string; obligatorio)
index ejemplo: string
index.Tipo: string
index.Identificador de la orden. Se conserva por compatibilidad con versiones anteriores, siempre igual a `id`.
- positionId (string[]; obligatorio)
positionId ejemplo: [
"string"
]
positionId.Tipo: string[]
positionId.Posición a la que está asociada una orden de cierre. Nulo para órdenes que abren o aumentan una posición.
positionId.[]Tipo: string
- parentOrderId (string[]; obligatorio)
parentOrderId ejemplo: [
"string"
]
parentOrderId.Tipo: string[]
parentOrderId.Orden de la que se generó esta: un stop o un take creado a partir de `stopTriggerPrice` / `takeTriggerPrice`, o la orden limit en la que se convirtió un `stop_limit`. Nulo cuando la orden se envió directamente.
parentOrderId.[]Tipo: string
- expiration (string · date-time · nullable; obligatorio)
expiration ejemplo: 2026-05-01T12:30:00.000Z
expiration.Tipo: string · date-time · nullable
expiration.Siempre nulo. Se mantiene por compatibilidad con versiones anteriores: las órdenes no expiran por sí solas.
expiration.format: date-time
- amount (string · int32; obligatorio)
amount ejemplo: 1000000000
amount.Tipo: string · int32
amount.Tamaño de la orden, fp9 en bruto, en la unidad que usa su clase: en una orden de incremento, un importe de cotización — la reserva mientras espera, y lo que realmente gastó una vez ejecutada; en una orden de cierre (`stop`, `take`, `trailing_stop`), el tamaño del activo base que cierra, tal como se solicitó al crearla.
amount.format: int32
amount.pattern: ^(?:-?[1-9][0-9]*|0)$
- indexPrice (string · int32 · nullable; obligatorio)
indexPrice ejemplo: 1000000000
indexPrice.Tipo: string · int32 · nullable
indexPrice.Precio índice al que se ejecutó la orden, fp9 en bruto. Nulo mientras la orden no se haya ejecutado.
indexPrice.format: int32
indexPrice.pattern: ^(?:-?[1-9][0-9]*|0)$
- settlementOraclePrice (string · int32; obligatorio)
settlementOraclePrice ejemplo: 1000000000
settlementOraclePrice.Tipo: string · int32
settlementOraclePrice.Siempre `1000000000` (1.0). Se mantiene por compatibilidad con versiones anteriores.
settlementOraclePrice.format: int32
settlementOraclePrice.pattern: ^(?:-?[1-9][0-9]*|0)$
- createdAt (string · date-time; obligatorio)
createdAt ejemplo: 2026-05-01T12:30:00.000Z
createdAt.Tipo: string · date-time
createdAt.Cuándo se aceptó la orden.
createdAt.format: date-time
- error (string[]; obligatorio)
error ejemplo: [
"string"
]
error.Tipo: string[]
error.Siempre null. Se mantiene por compatibilidad hacia atrás — utilice `errorCode`.
error.[]Tipo: string
- realizedPnl (string · int32 · nullable; obligatorio)
realizedPnl ejemplo: 1000000000
realizedPnl.Tipo: string · int32 · nullable
realizedPnl.Pnl realizado por esta orden, fp9 en bruto. Se establece solo en una orden de cierre ejecutada; null mientras está pendiente y en órdenes que abren o aumentan una posición.
realizedPnl.format: int32
realizedPnl.pattern: ^(?:-?[1-9][0-9]*|0)$
- rawRealizedPnl (string · int32 · nullable; obligatorio)
rawRealizedPnl ejemplo: 1000000000
rawRealizedPnl.Tipo: string · int32 · nullable
rawRealizedPnl.Pnl realizado antes del ajuste de 60 segundos, fp9 en bruto. Difiere de `realizedPnl` solo cuando se activó el ajuste.
rawRealizedPnl.format: int32
rawRealizedPnl.pattern: ^(?:-?[1-9][0-9]*|0)$
- profitAdjustmentApplied (boolean; obligatorio)
profitAdjustmentApplied ejemplo: true
profitAdjustmentApplied.Tipo: boolean
profitAdjustmentApplied.Si el ajuste de 60 segundos limitó la ganancia de esta orden — dentro de un minuto de una apertura o un aumento, el pnl de la posición no puede crecer por encima de lo que era en ese momento.
- executedAfterPause (boolean; obligatorio)
executedAfterPause ejemplo: true
executedAfterPause.Tipo: boolean
executedAfterPause.Indica si la orden se ejecutó después de una pausa del mercado. No lo establece el motor actual — siempre `false`.
- sizeMode (string · enum; obligatorio)
sizeMode ejemplo: quote
sizeMode.Tipo: string · enum
sizeMode.Cómo se expresó el tamaño al crearse: `quote` dimensiona la orden por `amount`, `base` la dimensiona por `baseSize`.
sizeMode.Valores permitidos: ["quote","base"]
- baseSize (string · int32 · nullable; obligatorio)
baseSize ejemplo: 1000000000
baseSize.Tipo: string · int32 · nullable
baseSize.Tamaño de la orden en unidades del activo base, fp9 en bruto. Nulo para órdenes dimensionadas por `quote`.
baseSize.format: int32
baseSize.pattern: ^(?:-?[1-9][0-9]*|0)$
- reservedAmount (string · int32 · nullable; obligatorio)
reservedAmount ejemplo: 1000000000
reservedAmount.Tipo: string · int32 · nullable
reservedAmount.Importe de quote reservado cuando se creó la orden con sizeMode=base, fp9 en bruto. Se mantiene en la reserva original después de la ejecución, mientras que `amount` se reescribe a lo que se gastó. Nulo para órdenes dimensionadas por `quote`, donde `amount` es la reserva.
reservedAmount.format: int32
reservedAmount.pattern: ^(?:-?[1-9][0-9]*|0)$
- errorCode (string[]; obligatorio)
errorCode ejemplo: [
"string"
]
errorCode.Tipo: string[]
errorCode.Por qué falló la ejecución, establecido junto con el estado `canceled_by_error` — por ejemplo `insufficient_reserve_at_execution`, `order_below_min_notional`, `order_exceeds_market_depth` o `slippage_tolerance`. Nulo en caso contrario.
errorCode.[]Tipo: string
- reason (string · enum · nullable; obligatorio)
reason ejemplo: force_close
reason.Tipo: string · enum · nullable
reason.Por qué la plataforma canceló la orden por sí misma, por ejemplo `force_close` o `weekly_session_risk_close`. Nulo para cancelaciones impulsadas por el trader.
reason.Valores permitidos: ["force_close","stop_accounts_fail","stop_accounts_freeze","stop_accounts_promote","stop_accounts_manual","weekly_session_risk_close",null]
Ejemplo
```json
{
"id": "00000000-0000-4000-8000-000000000000",
"txId": "string",
"trader": "00000000-0000-4000-8000-000000000000",
"market": "00000000-0000-4000-8000-000000000000",
"status": "active",
"type": "market",
"direction": "long",
"triggerPrice": "1000000000",
"requestedTriggerPrice": "1000000000",
"stopPrice": "1000000000",
"limitPrice": "1000000000",
"stopTriggerPrice": "1000000000",
"takeTriggerPrice": "1000000000",
"trailingStopActivationPrice": "1000000000",
"trailingStopOffset": "1000000000",
"trailingStopOffsetPercent": "1000000000",
"leverage": "1000000000",
"index": "string",
"positionId": [
"string"
],
"parentOrderId": [
"string"
],
"expiration": "2026-05-01T12:30:00.000Z",
"amount": "1000000000",
"indexPrice": "1000000000",
"settlementOraclePrice": "1000000000",
"createdAt": "2026-05-01T12:30:00.000Z",
"error": [
"string"
],
"realizedPnl": "1000000000",
"rawRealizedPnl": "1000000000",
"profitAdjustmentApplied": true,
"executedAfterPause": true,
"sizeMode": "quote",
"baseSize": "1000000000",
"reservedAmount": "1000000000",
"errorCode": [
"string"
],
"reason": "force_close"
}
```