Skip to content
MyStocks Developers
API v1

API v1

Current stable contract

Versioning policyRelease changelog
Sandbox console
API product catalogSub-Accounts & White-Label Retail KYC

Close sub-account

Sub-Accounts & White-Label Retail KYC

DELETE

/users/{userId}

Close sub-account

Sandbox availablecloseUsers

Soft-closes/offboards a sub-account. This is a terminal state: closed sub-accounts cannot trade, receive deposits, or withdraw. The record is retained for audit, regulatory, and support purposes. Closure is blocked while the sub-account has open orders, positive holdings, or unsettled proceeds. If the USD wallet has residual cash, either withdraw it first or pass residualCashHandling: "transfer_to_partner" to atomically move the cash back to the partner master wallet during closure. Emits account.closed to registered webhooks. Requires Idempotency-Key.

Parameters

userIdstringpathRequired

Example: usr_abc123

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

residualCashHandlingrequire_zero | transfer_to_partner

How to handle a remaining USD wallet balance. require_zero blocks closure if cash remains. transfer_to_partner atomically moves residual cash to the partner master wallet before closing.

reasonstring

Partner-supplied closure reason stored for audit and support.

Example: "User requested account deletion in partner app."

Response fields

messagestring

Example: "Sub-account closed. Residual cash transferred to partner master wallet."

subAccountIdstring

Example: "usr_abc123"

externalIdstring

Example: "user_42"

statusclosed
residualTransferUsdnumber

USD cash moved back to the partner master wallet during closure.

Example: 42.5

currencyUSD
newMasterBalancenumber

Present when residual cash was transferred.

Example: 10042.5

alreadyClosedboolean

true when the sub-account was already closed.

Response codes

200Sub-account closed, or was already closed.
409Closure blocked by open orders, positions, unsettled proceeds, or residual cash.

Previous

POST /users

Next

GET /users/{userId}