API product catalogExecution & Order Management (OMS)

Modify (replace) a resting order

Execution & Order Management (OMS)

PATCH

/orders/{orderId}

Sandbox unsupportedpatchOrder

Replaces a resting LIMIT/STOP/STOP_LIMIT order on the master account in place, keeping the same orderId. Only WORKING orders can be modified — a MARKET order is already PENDING at the dealing desk and can only be cancelled. Check replaceable on the order. Supply any combination of limitPrice, stopPrice, and quantity. The replace is repriced on the same FX basis and fee rates captured when the order was placed. A BUY re-escrows the difference (400 INSUFFICIENT_FUNDS if the wallet cannot cover an increase); a SELL adjusts reserved units. An Idempotency-Key is required because this moves money. The sub-account equivalent is PATCH /users/{userId}/orders/{orderId}.

Parameters

orderIdstringpathRequired

Example: ord_abc123xyz

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Idempotency-KeystringheaderRequired

Unique string that makes write calls safe to retry on network failure. Required for money movement, trading, KYC, subscriptions, and webhook creation. Deduplicated for 24 hours -- duplicate keys return the cached response. HTTP 409 if a concurrent request with the same key is still in progress.

Example: dep_user42_1743152580

Request body

limitPricenumber

New limit price, in the instrument's local trading currency.

Example: 18.5

stopPricenumber

New stop price, in the instrument's local trading currency.

Example: 17.25

quantitynumber

New quantity. Converts a cashValue-sized order into a quantity-sized one.

Example: 200

Response fields

orderIdstring

Unique order ID. Use to poll status or cancel.

Example: "ord_abc123xyz"

symbolstring

Example: "SCOM.KE"

namestring

Example: "Safaricom PLC"

exchangestring

Example: "NSE"

orderTypeMARKET | LIMIT | STOP | STOP_LIMIT

Order type. MARKET orders are quote-gated; LIMIT/STOP/STOP_LIMIT rest as WORKING until triggered.

Example: "LIMIT"

limitPricenumber | null

Limit price in the stock's local currency (LIMIT / STOP_LIMIT only).

stopPricenumber | null

Stop price in the stock's local currency (STOP / STOP_LIMIT only).

cancelableboolean

Whether the order can be cancelled now (DELETE). True while PENDING or WORKING.

replaceableboolean

Whether the order can be modified now (PATCH). True only for a WORKING resting order.

typeBUY | SELL

PENDING after submission. WORKING = resting LIMIT/STOP/STOP_LIMIT order waiting for its trigger price (becomes PENDING on trigger). PARTIALLY_FILLED and FILLED are the canonical execution states. REJECTED, CANCELLED, and EXPIRED are terminal outcomes. PROCESSING is a legacy transition alias and COMPLETED is a v1 compatibility alias of FILLED; neither represents custody settlement. Settlement is tracked separately as PENDING, SETTLED, or FAILED.

quoteIdstring | null

Pre-trade quote ID consumed by this order.

quoteExpiresAtstring | null

quoteUsdPricenumber | null

clientOrderIdstring | null

Partner-supplied order reference.

omsStatusstring | null

Canonical OMS lifecycle status.

timeInForcestring | null

filledQuantitynumber

remainingQuantitynumber

averageFillPricenumber | null

executionVenuestring | null

lastExecutionReportIdstring | null

executionSlaunion

Live execution SLA clock for orders that have entered the PENDING dealing-desk queue. Null while a resting order is still WORKING.

quantityinteger

priceAtOrdernumber

Stock price in local currency at submission.

usdPriceAtOrdernumber

USD equivalent of priceAtOrder.

fxRateAtOrdernumber | null

Managed FX rate used for local-to-USD conversion at order submission.

fxSourcestring | null

fxRateAsOfstring | null

fxConversionunion

feenumber

Total fee in USD (base + partner markup).

baseFeenumber

MyStocks base broker fee (0.75% of gross).

partnerMarkupFeenumber

Your markup fee component. Zero if markupBps = 0.

totalAmountnumber

BUY: gross + fee. SELL: gross - fee.

currencystring

Example: "USD"

localCurrencystring

Example: "KES"

rejectionCodestring | null

Structured rejection code. Populated when status = REJECTED.

rejectionReasonstring | null

Free-text rejection detail provided by the MyStocks internal-book execution service. Populated when status = REJECTED.

cancelledAtstring | null

settledAtstring | null

Set when custody settlement completes; independent of the canonical FILLED execution state. Legacy completed records that pre-date this field return their immutable completion/creation timestamp as compatibility evidence.

createdAtstring

Response codes

200Order modified. Escrow / unit reservation adjusted atomically.

400Invalid body, or insufficient funds to increase a BUY escrow.

409Order is not WORKING, or is not a resting order type, so it cannot be modified.

Request reference

Sandbox unsupported

orderId Required · path

Use the API Tester for write requests, including request bodies and idempotency keys.

https://mystocks.africa/api/v1/partner/orders/%7BorderId%7D

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "orderId": {
      "type": "string",
      "example": "ord_abc123xyz",
      "description": "Unique order ID. Use to poll status or cancel."
    },
    "symbol": {
      "type": "string",
      "example": "SCOM.KE"
    },
    "name": {
      "type": "string",
      "example": "Safaricom PLC"
    },
    "exchange": {
      "type": "string",
      "example": "NSE"
    },
    "orderType": {
      "type": "string",
      "enum": [
        "MARKET",
        "LIMIT",
        "STOP",
        "STOP_LIMIT"
      ],
      "description": "Order type. MARKET orders are quote-gated; LIMIT/STOP/STOP_LIMIT rest as WORKING until triggered.",
      "example": "LIMIT"
    },
    "limitPrice": {
      "type": [
        "number",
        "null"
      ],
      "description": "Limit price in the stock's local currency (LIMIT / STOP_LIMIT only)."
    },
    "stopPrice": {
      "type": [
        "number",
        "null"
      ],
      "description": "Stop price in the stock's local currency (STOP / STOP_LIMIT only)."
    },
    "cancelable": {
      "type": "boolean",
      "description": "Whether the order can be cancelled now (DELETE). True while PENDING or WORKING."
    },
    "replaceable": {
      "type": "boolean",
      "description": "Whether the order can be modified now (PATCH). True only for a WORKING resting order."
    },
    "type": {
      "type": "string",
      "enum": [
        "BUY",
        "SELL"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "PENDING",
        "WORKING",
        "PARTIALLY_FILLED",
        "PROCESSING",
        "COMPLETED",
        "FILLED",
        "REJECTED",
        "CANCELLED",
        "EXPIRED"
      ],
      "description": "PENDING after submission. WORKING = resting LIMIT/STOP/STOP_LIMIT order waiting for its trigger price (becomes PENDING on trigger). PARTIALLY_FILLED and FILLED are the canonical execution states. REJECTED, CANCELLED, and EXPIRED are terminal outcomes. PROCESSING is a legacy transition alias and COMPLETED is a v1 compatibility alias of FILLED; neither represents custody settlement. Settlement is tracked separately as PENDING, SETTLED, or FAILED."
    },
    "quoteId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pre-trade quote ID consumed by this order."
    },
    "quoteExpiresAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "quoteUsdPrice": {
      "type": [
        "number",
        "null"
      ]
    },
    "clientOrderId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Partner-supplied order reference."
    },
    "omsStatus": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "RECEIVED",
        "FILLED",
        "REJECTED",
        "CANCELLED",
        "null"
      ],
      "description": "Canonical OMS lifecycle status."
    },
    "timeInForce": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "DAY",
        "GTC",
        "GTD",
        "null"
      ]
    },
    "filledQuantity": {
      "type": "number"
    },
    "remainingQuantity": {
      "type": "number"
    },
    "averageFillPrice": {
      "type": [
        "number",
        "null"
      ]
    },
    "executionVenue": {
      "type": [
        "string",
        "null"
      ]
    },
    "lastExecutionReportId": {
      "type": [
        "string",
        "null"
      ]
    },
    "executionSla": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "model": {
              "type": "string",
              "enum": [
                "LIVE_DEALING_DESK"
              ],
              "description": "Execution path covered by this SLA."
            },
            "minMinutes": {
              "type": "integer",
              "example": 1,
              "description": "Earliest expected live execution window, in minutes."
            },
            "maxMinutes": {
              "type": "integer",
              "example": 5,
              "description": "Maximum live execution window, in minutes."
            },
            "targetMinutes": {
              "type": "integer",
              "example": 5,
              "description": "Deadline used by monitoring for breach detection."
            },
            "clockStartedAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time",
              "description": "When the order entered the live execution queue."
            },
            "targetFillBy": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time",
              "description": "Latest expected fill or rejection timestamp."
            },
            "status": {
              "type": "string",
              "enum": [
                "WITHIN_SLA",
                "BREACHED",
                "MET",
                "CANCELLED"
              ]
            },
            "breachedAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "lastCheckedAt": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            }
          }
        },
        {
          "type": "null"
        }
      ],
      "description": "Live execution SLA clock for orders that have entered the PENDING dealing-desk queue. Null while a resting order is still WORKING."
    },
    "quantity": {
      "type": "integer"
    },
    "priceAtOrder": {
      "type": "number",
      "description": "Stock price in local currency at submission."
    },
    "usdPriceAtOrder": {
      "type": "number",
      "description": "USD equivalent of priceAtOrder."
    },
    "fxRateAtOrder": {
      "type": [
        "number",
        "null"
      ],
      "description": "Managed FX rate used for local-to-USD conversion at order submission."
    },
    "fxSource": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "MYSTOCKS_MANAGED_FX",
        "PARTNER_PROVIDED_LEGACY",
        "null"
      ]
    },
    "fxRateAsOf": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "fxConversion": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "sourceCurrency": {
              "type": "string",
              "example": "KES"
            },
            "sourceAmount": {
              "type": "number",
              "example": 65000
            },
            "targetCurrency": {
              "type": "string",
              "example": "USD"
            },
            "targetAmount": {
              "type": "number",
              "example": 500
            },
            "rate": {
              "type": "number",
              "example": 130
            },
            "rateConvention": {
              "type": "string",
              "example": "KES per USD"
            },
            "source": {
              "type": "string",
              "enum": [
                "MYSTOCKS_MANAGED_FX",
                "PARTNER_PROVIDED_LEGACY"
              ]
            },
            "asOf": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "fee": {
      "type": "number",
      "description": "Total fee in USD (base + partner markup)."
    },
    "baseFee": {
      "type": "number",
      "description": "MyStocks base broker fee (0.75% of gross)."
    },
    "partnerMarkupFee": {
      "type": "number",
      "description": "Your markup fee component. Zero if markupBps = 0."
    },
    "totalAmount": {
      "type": "number",
      "description": "BUY: gross + fee. SELL: gross - fee."
    },
    "currency": {
      "type": "string",
      "example": "USD"
    },
    "localCurrency": {
      "type": "string",
      "example": "KES"
    },
    "rejectionCode": {
      "type": [
        "string",
        "null"
      ],
      "description": "Structured rejection code. Populated when status = REJECTED.",
      "enum": [
        "INSUFFICIENT_FUNDS",
        "KYC_REQUIRED",
        "MARKET_CLOSED",
        "COMPLIANCE_HOLD",
        "TECHNICAL_ISSUE",
        "OTHER",
        "null"
      ]
    },
    "rejectionReason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Free-text rejection detail provided by the MyStocks internal-book execution service. Populated when status = REJECTED."
    },
    "cancelledAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "settledAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Set when custody settlement completes; independent of the canonical FILLED execution state. Legacy completed records that pre-date this field return their immutable completion/creation timestamp as compatibility evidence."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    }
  }
}

curl -X PATCH 'https://mystocks.africa/api/v1/partner/orders/%7BorderId%7D' \
  -H "Authorization: Bearer $MYSTOCKS_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "limitPrice": 18.5,
  "quantity": 200
}'

GET /orders/{orderId}

GET /orders/{orderId}/executions