API product catalogSub-Accounts & White-Label Retail KYC

Replace (modify) a resting order

Sub-Accounts & White-Label Retail KYC

PATCH

/users/{userId}/orders/{orderId}

Sandbox unsupportedreplaceUserOrder

Modifies a WORKING resting order (LIMIT / STOP / STOP_LIMIT) in place, keeping the same orderId. Supply any of limitPrice, stopPrice, quantity — the BUY escrow or SELL unit reservation is adjusted by the delta atomically. Prices are in the stock's LOCAL trading currency. Only WORKING resting orders can be modified — market orders (PENDING for automatic internal-book execution) and terminal orders return 409. Increasing a BUY escrow beyond the available wallet balance returns 400 INSUFFICIENT_FUNDS; increasing a SELL quantity beyond available units returns 409. Fires the order.replaced webhook and writes a REPLACE execution report. A unique Idempotency-Key header is required (this moves escrow).

Parameters

userIdstringpathRequired

Example: usr_abc123

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 stock's local currency (LIMIT / STOP_LIMIT).

Example: 21.5

stopPricenumber

New stop price in the stock's local currency (STOP / STOP_LIMIT).

Example: 20

quantitynumber

New order quantity. Converts a cashValue-sized order to quantity-sized.

Example: 150

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

settlementStatusPENDING | SETTLED | FAILED

orderLifecyclestring | null

EXPIRED for expiry; expiry is not a rejection.

cancelReasonstring | null

executionReportIdstring

escrowAdjustmentnumber

USD escrow delta for BUY orders (>0 debited, <0 refunded).

messagestring

Response codes

200Order modified. Escrow / reservation adjusted by the delta.

400Validation error, or insufficient funds to increase a BUY escrow.

409Order is not a WORKING resting order, or a concurrent change won the race.

Request reference

Sandbox unsupported

userId Required · pathorderId Required · path

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

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

Open in API Tester API Reference

Response schema

{
  "allOf": [
    {
      "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"
        },
        "canonicalStatus": {
          "type": "string",
          "enum": [
            "PENDING",
            "WORKING",
            "PARTIALLY_FILLED",
            "FILLED",
            "REJECTED",
            "CANCELLED",
            "EXPIRED"
          ]
        },
        "settlementStatus": {
          "type": "string",
          "enum": [
            "PENDING",
            "SETTLED",
            "FAILED"
          ]
        },
        "orderLifecycle": {
          "type": [
            "string",
            "null"
          ],
          "description": "EXPIRED for expiry; expiry is not a rejection."
        },
        "cancelReason": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    {
      "type": "object",
      "properties": {
        "executionReportId": {
          "type": "string"
        },
        "escrowAdjustment": {
          "type": "number",
          "description": "USD escrow delta for BUY orders (>0 debited, <0 refunded)."
        },
        "message": {
          "type": "string"
        }
      }
    }
  ]
}

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

GET /users/{userId}/orders/{orderId}

GET /users/{userId}/orders/{orderId}/executions