API product catalogExecution & Order Management (OMS)

Get order

Execution & Order Management (OMS)

GET

/orders/{orderId}

Get order

Sandbox unsupportedgetOrder

Returns a single order by ID.

Parameters

orderIdstringpathRequired

Example: ord_abc123xyz

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

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 detail.

404Order not found.

Request reference

Sandbox unsupported

orderId Required · path

Use the API Reference for this production-only or streaming operation.

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 GET 'https://mystocks.africa/api/v1/partner/orders/%7BorderId%7D' \
  -H "Authorization: Bearer $MYSTOCKS_API_KEY"

DELETE /orders/{orderId}

PATCH /orders/{orderId}