Skip to main content

​
Overview

This guide covers how to submit savings top ups and withdrawals (sell orders) using the Savings Orders endpoint POST /savings/orders.
Savings orders always operate on the savings product implied by the provided currency. No ISIN is required.

​
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.
1

Verify the user has sufficient cash

Retrieve the user’s available cash in the target currency before submitting a top up.
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();
}
2

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.
{
  "side": "buy",
  "currency": "EUR",
  "amount": 200
}
3

Submit the savings top up order

Call POST /savings/orders with the request body and required headers.
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();
}
4

Track the order until settlement

Use the returned id to poll GET /savings/orders/{id} and update the UI once the status becomes Settled.

​
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.
1

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.
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();
}
The response returns a map of savings products by currency, each containing the amount (in cents) and currency. For example:
{
  "EUR": {
    "amount": 150000,
    "currency": "EUR"
  },
  "GBP": {
    "amount": 250000,
    "currency": "GBP"
  }
}
2

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.
const savingsVault = await getSavingsVault({ token, userId });
const eurSavings = savingsVault.EUR;

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

Build the withdrawal request

Configure the request payload with side set to sell.
{
  "side": "sell",
  "currency": "EUR",
  "amount": 150
}
4

Submit the withdrawal order

Call POST /savings/orders with the withdrawal payload.
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();
}
5

Monitor the withdrawal status

Poll GET /savings/orders/{id} or list orders with GET /savings/orders until the withdrawal is Settled, then reconcile the user’s balances.
  • API Reference → Savings Vault → GET /savings-vault
  • API Reference → Savings Orders → POST /savings/orders
  • API Reference → Savings Orders → GET /savings/orders
  • API Reference → Savings Orders → GET /savings/orders/{id}
  • API Reference → Cash → GET /cash