Implementing savings plans

In this chapter, you will learn how to implement savings plans with the Investment API.

Prerequisites

Please note the following preconditions in order to successfully implement savings plans:

Creating a savings plan for one of your users requires an active account.
The user's portfolio account must already have been configured for a portfolio savings plan.

1. Creating savings plans

The savings plan endpoint allows you to flexibly configure savings plan intervals - for example, your users can choose monthly automatic investments or individual intervals that best suit their needs.

You can create a savings plan for individual instruments as well as for a portfolio.

WARNING

Please note that you cannot create a savings plan for a single instrument for a portfolio account.

To create a portfolio savings plan, proceed as follows:

POST /savings_plans

Portfolio savings plan

In this example, a portfolio savings plan is created that executes recurring buy orders of € 100 once a week from July 24.

Example request portfolio savings plan

Expand example

{
  "user_id": "4b9732bd-7496-491-8a5f-6360479d7fed",
  "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030",
  "type": "PORTFOLIO",
  "cash_amount": "100.00",
  "currency": "EUR",
  "start_date" : "2023-07-24",
  "period": "WEEK", 
  "interval" : "1" 
}

Single instruments savings plan

Instrument savings plans are executed as individual orders.

In this example, a savings plan is created that executes recurring weekly buy orders of €100 for a specific ETF starting on July 24.

Example request instruments savings plan

Expand example

{
  "user_id": "4b9732bd-7496-491-8a5f-6360479d7fed",
  "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030",
  "type": "INSTRUMENT",
  "instrument_id": "IE00BOM62058",
  "instrument_id_type": "ISIN",
  "cash_amount": "100.00",
  "currency": "EUR",
  "start_date" : "2023-07-24",
  "period": "WEEK", 
  "interval" : "1" 
}

Parameter	Description
`user_id`	Required: The ID of the user.
`account_id`	Required: The ID of the account.
`type`	Required The savings plan type. Possible values: * `PORTFOLIO` * `INSTRUMENT`
`instrument_id`	If `type` is `INSTRUMENT`, the ID of the instrument.
`instrument_id_type`	If `type` is `INSTRUMENT`, The type of the ID used in the request. Possible values: - `ISIN` - `WKN`
`cash_amount`	Required: The savings plan amount.
`currency`	Required: The currency, currently only `EUR` is allowed.
`start_date`	Required: First date of the savings plan execution in the YYYY-MM-DD format.
`period`	Required: The time unit. Possible values: * `WEEK` * `MONTH` * `YEAR`
`interval`	Required: The number of periods between executions. Default: 1.

Configuring the cadence

This table will help you to define the cadence.

Example configurations:

Cadence	Example configuration
Every day	`start_date: "01.08.2023",` `period: "DAY",` `interval: "1"`
Bi-weekly	`start_date: "31.07.2023",` `period: "WEEK",` `interval: "2"`
Every week	`start_date: "31.07.2023",` `period: "WEEK",` `interval: "1"`
Beginning of the month/ Once a month	`start_date: "01.08.2023",` `period: "MONTH",` `interval: "1"`
Middle of the month	`start_date: "15.08.2023",` `period: "MONTH",` `interval: "1"`

2. Listing a savings plans

To list all savings plans, submit

GET /savings_plans/

You can retrieve individual savings plan via

GET /savings_plans/{savings_plan_id}

3. Get savings plans execution

You can list the executions for a savings plan with the following request:

GET /savings_plans/{savings_plan_id}/executions

Path parameter	Description
`savings_plan_id`	Required: Specify the ID of the savings plan that you want to retrieve.

To retrieve a single savings plan execution, submit the following request:

GET /savings_plans/{savings_plan_id}/executions/{savings_plan_execution_id}

Path parameter	Description
`savings_plan_id`	Required: Specify the ID of the savings plan that you want to retrieve.
`savings_plan_execution_id`	Required: Specify the ID of the savings plan execution that you want to retrieve.

Example response portfolio savings plan

{
  "id": "54b8d84f-5bd0-4e43-bf0f-164388cb4c23",
  "created_at": "2023-07-21T10:00:00.00Z",
  "type": "SAVINGS_PLAN_EXECUTION.NEW",
  "object": {
    "id": "fc34d28e-38f5-49d2-92f6-82acb79098f4",
    "created_at": "2023-07-21T14:10:00.00Z",
    "updated_at": "2023-07-21T15:10:00.00Z",
    "user_id": "4b9732bd-7496-4913-8a5f-6360479d7fed",
    "account_id": "00ef0be8-d564-43af-b3c7-11b7a2188030",
    "savings_plan_id": "c31083c1-1cd3-405f-95d1-f49a37f0e032",
    "order_id": null,
    "cash_amount": "100",
    "currency": "EUR",
    "status": "NEW",
    "type": "PORTFOLIO",
    "execution_date": "2023-07-23"
  },
  "webhook_id": "cd2e4183-4e62-4e0f-981b-44b594d14610"
}

4. Delete a savings plan execution

If you delete a savings plan execution, all outstanding executions will be cancelled and no new executions will be created.

DELETE /savings_plans/{savings_plan_id}/executions/{savings_plan_execution_id}