---
title: "Create withdrawal order"
method: POST
path: "/v0/withdrawal-orders/"
tags: ["Withdrawal orders"]
---

# Create withdrawal order

`POST /v0/withdrawal-orders/`

## Request

- Base URL: `https://distributor-api.spiko.io`
- URL: `https://distributor-api.spiko.io/v0/withdrawal-orders/`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/spiko/apis/spiko-distributor-api/docs/v0/withdrawal-orders/post.ts> (a function with typed inputs; its response is checked against the schema)

**Create a new withdrawal order for an investor with the specified parameters.**

- The `destination` field supports three modes:
  - `{"type":"bank-transfer","bankAccountId":"..."}` - pay out by bank transfer to one of the investor's bank accounts
  - `{"type":"instant-bank-transfer","bankAccountId":"..."}` - **instant withdrawal**: pay out the same day by instant bank transfer to one of the investor's bank accounts, without waiting for the standard settlement cycle
  - `{"type":"stablecoin-transfer","walletId":"..."}` - pay out in stablecoin to one of the investor's external wallets (organizations or individuals with a tax identification number, on supported share classes)
- The top-level `bankAccountId` field is a deprecated shorthand for the bank-transfer destination; provide exactly one of `destination` or `bankAccountId`.
- The `quantity` field supports three modes:
  - `{"mode":"amount","amount":{"value":"1000","currency":"USD"}}` - withdraw a specific fiat amount
  - `{"mode":"shares","shares":"10.5"}` - withdraw a specific number of shares
  - `{"mode":"total"}` - withdraw all shares (full withdrawal)
- If the order is expressed in shares or if it is total, the currency used will be the bank account currency.
- Returns complete order details, including its UUID identifier.
- **Instant withdrawals** carry extra conditions: your distributor must be enabled for them, the share class must be `EUTBL` or `eurSAFO`, the amount must be in `EUR` and within the investor's remaining daily instant limit, the destination bank account must be validated, and its bank must accept instant transfers. They are executed straight away and cannot be canceled.

> **Distribute-with-Spiko's-license distributors** cannot place this order from their backend. The investor must place it directly from the browser with a short-lived [Investor JWT](/developers/distributor_api/technical_guides/investor_jwt), targeting the investor-scoped path **`POST /v0/investor/withdrawal-orders/`** (identical payload and response, but authenticated with the investor JWT as bearer token instead of your API credentials).

## Request body

- object
  - `investorId` string, uuid, required: a Universally Unique Identifier
  - `accountId` string, uuid: a Universally Unique Identifier
  - `shareClassId` string, uuid, required: a Universally Unique Identifier
  - `bankAccountId` string, uuid, nullable: Deprecated. Use `destination` instead.
  - `destination` union
    - object
      - `type` 'bank-transfer', required
      - `bankAccountId` string, uuid, required: a Universally Unique Identifier
    - object
      - `type` 'instant-bank-transfer', required
      - `bankAccountId` string, uuid, required: a Universally Unique Identifier
    - object
      - `type` 'stablecoin-transfer', required
      - `walletId` string, uuid, required: a Universally Unique Identifier
  - `quantity` union, required
    - object
      - `mode` 'amount', required
      - `amount` NonNegativeAmount, required
        - `value` string, required: a string representation of a non-negative decimal number e.g. "10000", "0.00" or "3420.92"
        - `currency` 'EUR' | 'USD' | 'GBP' | 'CHF' | 'JPY' | 'SGD' | 'SEK' | 'NOK' | 'DKK' | 'PLN' | 'HUF' | 'CZK', required: a currency code among "EUR", "USD", "GBP", "CHF", "JPY", "SGD", "SEK", "NOK", "DKK", "PLN", "HUF", "CZK"
    - object
      - `mode` 'shares', required
      - `shares` string, required
    - object
      - `mode` 'total', required

## Response `200`

Success

- object
  - `id` string, uuid, required: a Universally Unique Identifier
  - `investorId` string, uuid, required: a Universally Unique Identifier
  - `accountId` string, uuid, required: a Universally Unique Identifier
  - `shareClassId` string, uuid, required: a Universally Unique Identifier
  - `destination` union, required
    - object
      - `type` 'bank-transfer', required
      - `bankAccountId` string, uuid, required: a Universally Unique Identifier
    - object
      - `type` 'instant-bank-transfer', required
      - `bankAccountId` string, uuid, required: a Universally Unique Identifier
    - object
      - `type` 'stablecoin-transfer', required
      - `walletId` string, uuid, required: a Universally Unique Identifier
  - `quantity` union, required
    - object
      - `mode` 'amount', required
      - `amount` NonNegativeAmount, required
        - `value` string, required: a string representation of a non-negative decimal number e.g. "10000", "0.00" or "3420.92"
        - `currency` 'EUR' | 'USD' | 'GBP' | 'CHF' | 'JPY' | 'SGD' | 'SEK' | 'NOK' | 'DKK' | 'PLN' | 'HUF' | 'CZK', required: a currency code among "EUR", "USD", "GBP", "CHF", "JPY", "SGD", "SEK", "NOK", "DKK", "PLN", "HUF", "CZK"
    - object
      - `mode` 'shares', required
      - `shares` string, required
    - object
      - `mode` 'total', required
  - `status` 'pending' | 'executed' | 'canceled', required
  - `createdAt` string, required
  - `executedAt` string, nullable, required
  - `canceledAt` string, nullable, required
  - `settlement` object, nullable, required
    - `amount` NonNegativeAmount, required
      - `value` string, required: a string representation of a non-negative decimal number e.g. "10000", "0.00" or "3420.92"
      - `currency` 'EUR' | 'USD' | 'GBP' | 'CHF' | 'JPY' | 'SGD' | 'SEK' | 'NOK' | 'DKK' | 'PLN' | 'HUF' | 'CZK', required: a currency code among "EUR", "USD", "GBP", "CHF", "JPY", "SGD", "SEK", "NOK", "DKK", "PLN", "HUF", "CZK"
    - `shares` string, required
    - `appliedNAV` object, required
      - `day` string, required: a day in ISO format "YYYY-MM-DD"
      - `amount` NonNegativeAmount, required
        - `value` string, required: a string representation of a non-negative decimal number e.g. "10000", "0.00" or "3420.92"
        - `currency` 'EUR' | 'USD' | 'GBP' | 'CHF' | 'JPY' | 'SGD' | 'SEK' | 'NOK' | 'DKK' | 'PLN' | 'HUF' | 'CZK', required: a currency code among "EUR", "USD", "GBP", "CHF", "JPY", "SGD", "SEK", "NOK", "DKK", "PLN", "HUF", "CZK"

## Other responses

- `400`: Bad Request | Application Error | Insufficient balance in account to process requested operation | The request did not match the expected schema
- `401`: Authentication failed. Two bodies are possible: the schema below when the API rejects the credentials, and `{ "error": { "code", "status", "request", "message" } }` when the API gateway rejects them first. Only the former carries a `_tag`.
- `403`: Forbidden
- `404`: NotFound
- `409`: Investor token has already been used
- `422`: Investor is not ready for order creation yet | Unprocessable Content | Requested instant withdrawal amount exceeds daily limit for this investor
- `503`: Service Unavailable | Instant withdrawals are disabled for this distributor | The bank is experiencing a temporary outage | The investor is undergoing a scheduled upgrade, access is temporarily paused to ensure data safety.

---

[API](https://skmtc.dev/spiko/apis/spiko-distributor-api.md) - [All operations](https://skmtc.dev/spiko/apis/spiko-distributor-api/llms.txt) - [OpenAPI document](https://skmtc.dev/spiko/apis/spiko-distributor-api/revisions/ad85137fd00b?raw)