Guides
Postman collections ↗Bud Console ↗

Savings Goals

Suggest Edits

What are Savings Goals?

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

Create a Savings Goal

The POST goals/v1/savings endpoint allows a savings goal to be created against a given account_id. The provided account_id must be present in the Bud platform.

The target_amount, target_date, and recurrent_amount are also validated to ensure the savings goal is achievable within these constraints. At least two of these parameters must be supplied, the third is calculated if not present. When only two parameters are supplied, it is assumed that no payment will be made towards the goal within the month of creation.

This endpoint will return the created savings goal with its id and created_at time. An example of a 201 response can be seen below.

{
  "operation_id": "goals_v1_savings_post",
  "data": {
    "id": "f46d76c4-56d3-11ee-ac69-d6df71eb5902",
    "account_id": "RxsYshVGded4JeilkXgWKdXA",
    "name": "Car Savings",
    "target_amount": {
      "currency": "USD",
      "value": "3000.00"
    },
    "recurrent_amount": {
      "currency": "USD",
      "value": "750.00"
    },
    "target_date": "2023-12-30",
    "saved_amount": {
      "currency": "USD",
      "value": "0.00"
    },
    "created_at": "2023-09-19T10:04:43Z"
  }
}

curl --request POST \
     --url https://api-sandbox.thisisbud.com/goals/v1/savings \
     --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"
  },
  "recurrent_amount": {
    "value": "750",
    "currency": "USD"
  },
  "name": "Car Savings",
  "account_id": "RxsYshVGded4JeilkXgWKdXA",
  "target_date": "2023-12-30"
}
'

In the case that the provided account_id does not exist within the Bud platform, 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.

Retrieve Savings Goals

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

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

The response includes the saved_amount field which is a running total of the Savings Goal Actions against the goal.

{
  "operation_id": "goals_v1_savings_get",
  "data": [
    {
      "id": "f46d76c4-56d3-11ee-ac69-d6df71eb5902",
      "account_id": "RxsYshVGded4JeilkXgWKdXA",
      "name": "Car Savings",
      "target_amount": {
        "currency": "USD",
        "value": "3000.00"
      },
      "recurrent_amount": {
        "currency": "USD",
        "value": "750.00"
      },
      "target_date": "2023-12-30",
      "saved_amount": {
        "currency": "USD",
        "value": "0.00"
      },
      "created_at": "2023-09-19T10:04:43Z"
    },
    {
      "id": "265a4aed-348d-4ff1-802e-2d08d7cace77",
      "account_id": "RxsYshVGded4JeilkXgWKdXA",
      "name": "Holiday Savings",
      "target_amount": {
        "currency": "USD",
        "value": "1000.00"
      },
      "recurrent_amount": {
        "currency": "USD",
        "value": "100.00"
      },
      "target_date": "2023-07-30",
      "saved_amount": {
        "currency": "USD",
        "value": "0.00"
      },
      "created_at": "2023-09-19T10:04:43Z"
    }
  ],
  "metadata": {
    "results": 2,
    "account_id": "RxsYshVGded4JeilkXgWKdXA"
  }
}

curl --request GET \
     --url https://api-sandbox.thisisbud.com/goals/v1/savings \
     --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_v1_savings_get",
  "data": [],
  "metadata": {
    "results": 0,
    "account_id": null
  }
}

curl --request GET \
     --url https://api-sandbox.thisisbud.com/goals/v1/savings \
     --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.

Update a Savings Goal

The PATCH goals/v1/savings/{goal_id} endpoint is used to update a savings goal.

The goal's name, target_amount, target_date, and recurrent_amount can be updated.

If target_amount, target_date, and/or recurrent_amount is updated, then another of the fields must be supplied as is the case with the POST goals/v1/savings endpoint. Validation upon these fields is re-run when the goal is updated as it is on the POST goals/v1/savings endpoint.

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

{
  "operation_id": "goals_v1_savings_post",
  "data": {
    "id": "f46d76c4-56d3-11ee-ac69-d6df71eb5902",
    "account_id": "RxsYshVGded4JeilkXgWKdXA",
    "name": "Holiday",
    "target_amount": {
      "currency": "USD",
      "value": "3000.00"
    },
    "recurrent_amount": {
      "currency": "USD",
      "value": "750.00"
    },
    "target_date": "2024-01-30",
    "saved_amount": {
      "currency": "USD",
      "value": "0.00"
    },
    "created_at": "2023-09-19T10:04:43Z"
  }
}

curl --request PATCH \
     --url https://api-sandbox.thisisbud.com/goals/v1/savings/goal_id \
     --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"}'

In the case that the provided goal_id does not exist, 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/v1/savings endpoint removes all savings goals for a given customer.

If you would like to delete a specific goal you can do so by specifying an id in the URL of the endpoint such as

curl --request DELETE \
     --url https://api-sandbox.thisisbud.com/goals/v1/savings/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 id provided in the request, a 404 is returned.

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

Saving Goal Actions

Create a Savings Goal Action

The POST goals/v1/savings{goal_id}/actions endpoint allows an action to be created against a given savings goal. An action is an indication from the customer that they have paid a contribution into the given account towards their savings goal.

The amount can be a debit or a credit, denoted by the credit_debit_indicator, should a customer withdraw or add money from or to the associated account.

The amount is validated against the balance of the account to ensure it is possible that this contribution has been paid into the account.

This endpoint will return the created action with its id and created_at time. An example of a 201 response can be seen below.

{
  "operation_id": "goals_v1_savings_actions_post",
  "data": {
    "id": "23267253-5860-11ee-99e5-9ed0600d2630",
    "amount": {
      "currency": "USD",
      "value": "10.00"
    },
    "credit_debit_indicator": "credit",
    "created_at": "2023-09-21T09:20:42Z"
  },
  "metadata": {
    "goal_id": "19d1def3-5860-11ee-9342-3e1d60bc76f9"
  }
}

curl --request POST \
     --url https://api-sandbox.thisisbud.com/goals/v1/savings/goal_id/actions \
     --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 '
{
  "amount": {
    "value": "10",
    "currency": "GBP"
  },
  "credit_debit_indicator": "credit"
}
'

In the case that the action cannot have been made as it is not valid against the account's balance, then 400 is returned.

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

Retrieve Savings Goal Actions

The GET goals/v1/savings/{goal_id}/actions endpoint retrieves all actions for a customer's savings goal.

This endpoint is paginated with a maximum page size of 200 and a default of 100, this can be set via the page_size query parameter. If more pages are available, then a page_token field will be present in the metadata of the response. The value of this field should be put in the page_token query parameter to fetch the next page if results.

Below is an example response with a page_token indicating there is a further page of actions available.

{
  "operation_id": "goals_v1_savings_actions_get",
  "data": [
    {
      "id": "23267253-5860-11ee-99e5-9ed0600d2630",
      "amount": {
        "currency": "USD",
        "value": "10.00"
      },
      "credit_debit_indicator": "credit",
      "created_at": "2023-09-21T09:20:42Z"
    },
    {
      "id": "23267253-5860-11ee-99e5-9ed0600d2630",
      "amount": {
        "currency": "USD",
        "value": "10.00"
      },
      "credit_debit_indicator": "credit",
      "created_at": "2023-09-21T09:20:42Z"
    }
  ],
  "metadata": {
    "results": 2,
    "page_token": "b21055a9a9f46fc794a2e6855c65abd7e317181039fc6930daabac5822911d14a84895ecd947e2b5abdcb22e4fcc2c594e1f661dc63e34b9ba88760724047990896f7581a0786c2605dce19c6a9d80d1044f963b74fea0a929c0a4465a6e67378a74dce38ec5e26ae4cc804b62fd666d5df4cf2e7f524bd99e5523bc5d471768065c036dc0c73122705b280817fbbd7d9aa31f271d72cd3877d999dcb9a5b1c0be0c05",
    "page_size": 100,
    "goal_id": "19d1def3-5860-11ee-9342-3e1d60bc76f9"
  }
}

curl --request GET \
     --url https://api-sandbox.thisisbud.com/goals/v1/savings/goal_id/actions \
     --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 there are no further pages of results, the page_token in the metadata will be empty.

{
  "operation_id": "goals_v1_savings_actions_get",
  "data": [..],
  "metadata": {
    "results": 2,
    "page_token": "",
    "page_size": 100,
    "goal_id": "19d1def3-5860-11ee-9342-3e1d60bc76f9"
  }
}

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

Update Savings Goal Actions

The PATCH goals/v1/savings/{goal_id}/actions/{goal_action_id} endpoint is used to update a goal's action.

When a goal action is updated, the amount is once again validated against the associated account's balance as it is upon creation.

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

{
  "operation_id": "goals_v1_savings_actions_patch",
  "data": {
    "id": "23267253-5860-11ee-99e5-9ed0600d2630",
    "amount": {
      "currency": "USD",
      "value": "10.00"
    },
    "credit_debit_indicator": "credit",
    "created_at": "2023-09-21T09:20:42Z"
  },
  "metadata": {
    "goal_id": "19d1def3-5860-11ee-9342-3e1d60bc76f9"
  }
}

curl --request PATCH \
     --url https://api-sandbox.thisisbud.com/goals/v1/savings/goal_id/actions/goal_action_id \
     --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 '
{
  "amount": {
    "value": "15",
    "currency": "USD"
  }
}
'

In the case that the provided goal_id or goal_action_id does not exist, 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 Action

The DELETE goals/v1/savings/{goal_id}/actions/{goal_action_id} endpoint removes a given action. The response from this endpoint will be 204 if the deletion is successful.

curl --request DELETE \
     --url https://api-sandbox.thisisbud.com/goals/v1/savings/goal_id/actions/goal_action_id \
     --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 action with a goal_id and goal_action_id that matches the goal_id and goal_action_id provided, a 404 is returned.

If you receive a 400 response, please check the headers 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.

Updated 8 months ago