Savings Goals

What are Savings Goals?

Savings goals are a way for customers to track and reach their savings goals within the Bud platform.

Each goal is linked to an account and given an allocation_ratio, which is the proportion of that account's balance attributed to the goal. Bud monitors the account's balance and keeps the goal's progress up to date automatically, so there is no need to log individual contributions or withdrawals against a goal.

The goal_balance returned for a goal is calculated as the current account balance multiplied by the goal's allocation_ratio. For example, an account with a balance of $5,000.00 and a goal with an allocation_ratio of 0.2 has a goal_balance of $1,000.00.

Savings goals do not move money between accounts. They record how much of an account's balance a customer has attributed to each goal. Multiple goals can be linked to the same account, and the allocation_ratio of the goals on an account should not total more than 1 (100%).

Create a Savings Goal

The POST goals/v2/savings/goal endpoint allows a savings goal to be created against a given account_id.

The following fields are supplied in the request body:

Field	Required	Description
`account_id`	Yes	The account the goal is linked to.
`name`	Yes	The name of the goal.
`target_amount`	Yes	The amount the customer wants to save.
`allocation_ratio`	Yes	The proportion of the account balance attributed to the goal. Must be greater than `0` and no more than `1`, for example `0.2` for 20%.
`target_datetime`	No	The date the customer wants to reach the goal by, in RFC-3339 format. Must be a future date, for example `2027-12-31T00:00:00Z`.

This endpoint will return the created savings goal, including its goal_balance. An example of a 200 response can be seen below.

{
  "operation_id": "goals_v2_savings_goal_post",
  "data": {
    "id": "f46d76c4-56d3-11ee-ac69-d6df71eb5902",
    "account_id": "RxsYshVGded4JeilkXgWKdXA",
    "name": "Car Savings",
    "target_amount": {
      "currency": "USD",
      "value": "3000.00"
    },
    "target_datetime": "2025-12-30T00:00:00Z",
    "allocation_ratio": 0.2,
    "goal_balance": {
      "currency": "USD",
      "value": "500.00"
    },
    "created_at": "2024-01-15T10:04:43Z"
  }
}

curl --request POST \
     --url https://api-sandbox.thisisbud.com/goals/v2/savings/goal \
     --header 'X-Client-Id: ecfa9b53-963b-4f8a-9811-e09a79ff7019' \
     --header 'X-Customer-Id: 2a7a1f1c-18b9-4af1-8424-91c5848e8037' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer dddd' \
     --header 'content-type: application/json' \
     --data '
{
  "target_amount": {
    "value": "3000",
    "currency": "USD"
  },
  "name": "Car Savings",
  "account_id": "RxsYshVGded4JeilkXgWKdXA",
  "target_datetime": "2027-12-31T00:00:00Z",
  "allocation_ratio": 0.2
}
'

If you receive a 400 response, please check the headers and body you're sending in the request before trying again. This includes checking that the allocation_ratio is greater than 0 and no more than 1, and that target_datetime is a future date.

Retrieve Savings Goals

The GET goals/v2/savings/goals endpoint retrieves all savings goals for a customer.

This endpoint can be filtered by account_id using the query parameter filter. An example of a 200 response can be seen below.

The response includes the goal_balance field for each goal, which is calculated using the current balance of the linked account multiplied by the goal's allocation_ratio.

{
  "operation_id": "goals_v2_savings_goals_get",
  "data": [
    {
      "id": "f46d76c4-56d3-11ee-ac69-d6df71eb5902",
      "account_id": "RxsYshVGded4JeilkXgWKdXA",
      "name": "Car Savings",
      "target_amount": {
        "currency": "USD",
        "value": "3000.00"
      },
      "target_datetime": "2025-12-30T00:00:00Z",
      "allocation_ratio": 0.2,
      "goal_balance": {
        "currency": "USD",
        "value": "500.00"
      },
      "created_at": "2024-01-15T10:04:43Z"
    },
    {
      "id": "265a4aed-348d-4ff1-802e-2d08d7cace77",
      "account_id": "RxsYshVGded4JeilkXgWKdXA",
      "name": "Holiday Savings",
      "target_amount": {
        "currency": "USD",
        "value": "1000.00"
      },
      "allocation_ratio": 0.1,
      "goal_balance": {
        "currency": "USD",
        "value": "250.00"
      },
      "created_at": "2024-01-15T10:04:43Z"
    }
  ]
}

curl --request GET \
     --url 'https://api-sandbox.thisisbud.com/goals/v2/savings/goals?account_id=RxsYshVGded4JeilkXgWKdXA' \
     --header 'X-Client-Id: ecfa9b53-963b-4f8a-9811-e09a79ff7019' \
     --header 'X-Customer-Id: 2a7a1f1c-18b9-4af1-8424-91c5848e8037' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer dddd'

In the case that the customer has no savings goals, a 200 is still returned with a response as below.

{
  "operation_id": "goals_v2_savings_goals_get",
  "data": []
}

curl --request GET \
     --url https://api-sandbox.thisisbud.com/goals/v2/savings/goals \
     --header 'X-Client-Id: ecfa9b53-963b-4f8a-9811-e09a79ff7019' \
     --header 'X-Customer-Id: 2a7a1f1c-18b9-4af1-8424-91c5848e8037' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer dddd'

If you receive a 400 response, please check the headers you're sending in the request before trying again.

Retrieve a Savings Goal

The GET goals/v2/savings/goals/{savings_goal_id} endpoint retrieves a single savings goal using its savings_goal_id.

As with retrieving all goals, the goal_balance is calculated using the current balance of the linked account multiplied by the goal's allocation_ratio. An example of a 200 response can be seen below.

{
  "operation_id": "goals_v2_savings_goal_get",
  "data": {
    "id": "f46d76c4-56d3-11ee-ac69-d6df71eb5902",
    "account_id": "RxsYshVGded4JeilkXgWKdXA",
    "name": "Car Savings",
    "target_amount": {
      "currency": "USD",
      "value": "3000.00"
    },
    "target_datetime": "2025-12-30T00:00:00Z",
    "allocation_ratio": 0.2,
    "goal_balance": {
      "currency": "USD",
      "value": "500.00"
    },
    "created_at": "2024-01-15T10:04:43Z"
  }
}

curl --request GET \
     --url https://api-sandbox.thisisbud.com/goals/v2/savings/goals/81a68821-dca6-4771-80d4-002c7fce412e \
     --header 'X-Client-Id: ecfa9b53-963b-4f8a-9811-e09a79ff7019' \
     --header 'X-Customer-Id: 2a7a1f1c-18b9-4af1-8424-91c5848e8037' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer dddd'

In the case that the provided savings_goal_id does not exist, a 404 HTTP response will be given.

If you receive a 400 response, please check the headers and the savings_goal_id you're sending in the request before trying again.

Update a Savings Goal

The PATCH goals/v2/savings/goals/{savings_goal_id} endpoint is used to update a savings goal.

The goal's name, account_id, target_amount, target_datetime, and allocation_ratio can be updated. All fields are optional, so only the fields being changed need to be supplied.

The allocation_ratio must be greater than 0 and no more than 1.
The target_datetime must be a future date. Set target_datetime to null to remove the target date from the goal.

The goal_balance is recalculated when the goal is updated, using the current account balance multiplied by the updated allocation_ratio.

This endpoint will return the updated savings goal. An example of a 200 response can be seen below.

{
  "operation_id": "goals_v2_savings_goal_patch",
  "data": {
    "id": "f46d76c4-56d3-11ee-ac69-d6df71eb5902",
    "account_id": "RxsYshVGded4JeilkXgWKdXA",
    "name": "Mortgage Deposit Savings",
    "target_amount": {
      "currency": "USD",
      "value": "3000.00"
    },
    "target_datetime": "2026-06-30T00:00:00Z",
    "allocation_ratio": 0.25,
    "goal_balance": {
      "currency": "USD",
      "value": "625.00"
    },
    "created_at": "2024-01-15T10:04:43Z"
  }
}

curl --request PATCH \
     --url https://api-sandbox.thisisbud.com/goals/v2/savings/goals/81a68821-dca6-4771-80d4-002c7fce412e \
     --header 'X-Client-Id: ecfa9b53-963b-4f8a-9811-e09a79ff7019' \
     --header 'X-Customer-Id: 2a7a1f1c-18b9-4af1-8424-91c5848e8037' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer dddd' \
     --header 'content-type: application/json' \
     --data '
{
  "name": "Holiday",
  "allocation_ratio": 0.25
}
'

In the case that the provided savings_goal_id does not exist, a 404 HTTP response will be given.

If you receive a 400 response, please check the headers and body you're sending in the request before trying again.

Delete a Savings Goal

The DELETE goals/v2/savings/goals/{savings_goal_id} endpoint removes the savings goal with the given savings_goal_id.

curl --request DELETE \
     --url https://api-sandbox.thisisbud.com/goals/v2/savings/goals/81a68821-dca6-4771-80d4-002c7fce412e \
     --header 'X-Client-Id: ecfa9b53-963b-4f8a-9811-e09a79ff7019' \
     --header 'X-Customer-Id: 2a7a1f1c-18b9-4af1-8424-91c5848e8037' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer dddd'

This endpoint will return a 204 if the deletion has been successful.

In the case that the customer doesn't have a goal with an id that matches the savings_goal_id provided in the request, a 404 is returned.

If you receive a 400 response, please check the headers and the savings_goal_id you're sending in the request before trying again.

Dealing with `401` and `500` responses

If you receive a 401 response from any of these endpoints this would indicate that you are not authorized to make this request, if you believe this to be a mistake or are receiving persistent 500 responses please raise a support request.

If you have any questions, please contact us via the chatbot (bottom-right of screen 👉) or via a support request or check our FAQs.