> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wealthyhood.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Savings order flow

> How to create savings top ups and withdrawals using the Savings Orders API

## Overview

This guide covers how to submit savings top ups and withdrawals (sell orders) using the Savings Orders endpoint `POST /savings/orders`.

<Info>
  Savings orders always operate on the savings product implied by the provided currency. No ISIN is required.
</Info>

### Prerequisites

* Access to the Savings Orders endpoints
* M2M bearer token with required scopes
* `x-user-id` header to scope the user (MongoDB ObjectId format)

***

## Savings top up flow

Use this flow to move cash into a user's savings plan.

<Steps>
  <Step title="Verify the user has sufficient cash">
    Retrieve the user's available cash in the target currency before submitting a top up.

    <CodeGroup>
      ```javascript Node.js theme={null}
      const BASE = 'https://api.wealthyhood.com';

      async function getCashBalance({ token, userId }) {
        const res = await fetch(`${BASE}/cash`, {
          method: 'GET',
          headers: {
            'Authorization': `Bearer ${token}`,
            'x-user-id': userId,
            'Accept': 'application/json'
          }
        });
        if (!res.ok) throw new Error(`Failed to get cash: ${res.status}`);
        return res.json();
      }
      ```

      ```bash cURL theme={null}
      curl -X GET 'https://api.wealthyhood.com/cash' \
        -H 'Accept: application/json' \
        -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
        -H 'x-user-id: 64f0c51e7fb3fc001234abcd'
      ```
    </CodeGroup>
  </Step>

  <Step title="Build the savings top up request">
    Create the order payload with the side set to `Buy`, the savings currency, and the amount to top up.

    ```json theme={null}
    {
      "side": "Buy",
      "currency": "EUR",
      "amount": 200
    }
    ```
  </Step>

  <Step title="Submit the savings top up order">
    Call `POST /savings/orders` with the request body and required headers.

    <CodeGroup>
      ```javascript Node.js theme={null}
      const BASE = 'https://api.wealthyhood.com';

      async function submitSavingsTopUp({ token, userId, currency, amount }) {
        const res = await fetch(`${BASE}/savings/orders`, {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${token}`,
            'x-user-id': userId,
            'Accept': 'application/json',
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            side: 'Buy',
            currency,
            amount
          })
        });
        if (!res.ok) throw new Error(`Savings order failed: ${res.status}`);
        return res.json();
      }
      ```

      ```bash cURL theme={null}
      curl -X POST 'https://api.wealthyhood.com/savings/orders' \
        -H 'Accept: application/json' \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
        -H 'x-user-id: 64f0c51e7fb3fc001234abcd' \
        -d '{
          "side": "Buy",
          "currency": "EUR",
          "amount": 200
        }'
      ```
    </CodeGroup>
  </Step>

  <Step title="Retrieve order status">
    Use `GET /transactions/savings-activity` to retrieve the order status. Filter the results by the transaction `id` returned from the order submission.
  </Step>
</Steps>

***

## Savings withdrawal flow

Withdrawals correspond to savings sell orders. Use this flow to return funds from the savings plan to the user's cash balance.

<Steps>
  <Step title="Retrieve the user's savings vault balance">
    Before submitting a withdrawal, retrieve the user's savings vault balance to ensure they have sufficient savings in the target currency.

    <CodeGroup>
      ```javascript Node.js theme={null}
      const BASE = 'https://api.wealthyhood.com';

      async function getSavingsVault({ token, userId }) {
        const res = await fetch(`${BASE}/savings-vault`, {
          method: 'GET',
          headers: {
            'Authorization': `Bearer ${token}`,
            'x-user-id': userId,
            'Accept': 'application/json'
          }
        });
        if (!res.ok) throw new Error(`Failed to get savings vault: ${res.status}`);
        return res.json();
      }
      ```

      ```bash cURL theme={null}
      curl -X GET 'https://api.wealthyhood.com/savings-vault' \
        -H 'Accept: application/json' \
        -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
        -H 'x-user-id: 64f0c51e7fb3fc001234abcd'
      ```
    </CodeGroup>

    <Info>
      The response returns a map of savings products by currency, each containing the `amount` (in cents) and `currency`. For example:

      ```json theme={null}
      {
        "EUR": {
          "amount": 150000,
          "currency": "EUR"
        }
      }
      ```
    </Info>
  </Step>

  <Step title="Verify sufficient savings balance">
    Check that the user has enough savings in the target currency to cover the withdrawal amount. Remember that the savings vault amounts are in cents, so convert accordingly.

    ```javascript theme={null}
    const savingsVault = await getSavingsVault({ token, userId });
    const eurSavings = savingsVault.EUR;

    if (!eurSavings || eurSavings.amount < withdrawalAmountInCents) {
      throw new Error('Insufficient savings balance');
    }
    ```
  </Step>

  <Step title="Build the withdrawal request">
    Configure the request payload with `side` set to `Sell`.

    ```json theme={null}
    {
      "side": "Sell",
      "currency": "EUR",
      "amount": 150
    }
    ```
  </Step>

  <Step title="Submit the withdrawal order">
    Call `POST /savings/orders` with the withdrawal payload.

    <CodeGroup>
      ```javascript Node.js theme={null}
      const BASE = 'https://api.wealthyhood.com';

      async function submitSavingsWithdrawal({ token, userId, currency, amount }) {
        const res = await fetch(`${BASE}/savings/orders`, {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${token}`,
            'x-user-id': userId,
            'Accept': 'application/json',
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            side: 'Sell',
            currency,
            amount
          })
        });
        if (!res.ok) throw new Error(`Savings withdrawal failed: ${res.status}`);
        return res.json();
      }
      ```

      ```bash cURL theme={null}
      curl -X POST 'https://api.wealthyhood.com/savings/orders' \
        -H 'Accept: application/json' \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
        -H 'x-user-id: 64f0c51e7fb3fc001234abcd' \
        -d '{
          "side": "Sell",
          "currency": "EUR",
          "amount": 150
        }'
      ```
    </CodeGroup>
  </Step>

  <Step title="Retrieve withdrawal status">
    Use `GET /transactions/savings-activity` to retrieve the withdrawal status. Filter the results by the transaction `id` returned from the withdrawal submission.
  </Step>
</Steps>

***

### Related APIs

* API Reference → Savings Vault → `GET /savings-vault`
* API Reference → Savings Orders → `POST /savings/orders`
* API Reference → Transactions → `GET /transactions/savings-activity`
* API Reference → Cash → `GET /cash`