Savings plan execution

Once a savings plan has been created with the desired configuration, our system automatically executes the savings plan.

You must provide a start date, which is the first day on which our system will executes a savings plan. This start date forms the basis for calculating when the next execution should take place.

If a savings plan execution falls on a non-trading day (e.g. weekend or public holiday), we execute the order on the next possible trading day. If the start date is the last day of a month and the cadence is monthly, the next execution will always take place on the last day of the following month.

Savings plan execution flow

You may inspect the current state of the savings plan execution at any time (see: "Retrieving saving plan executions").

The following table shows the different statuses of a savings plan execution, which will be reflected in the data returned for a savings plan execution:

Status	Description
`NEW`	In this state, the savings plan execution is created and you’ll receive a webhook notification informing you about an upcoming savings plan order for your user. The timing of the webhook notification can be flexibly configured (i.e. two days in advance of the actual execution day).
`PROCESSING`	The respective savings plan order (either individual order or portfolio order) are being executed.
`FILLED`	A savings plan execution is `FILLED` once the underlying order(s) have been fully executed.
`CANCELLED`	Savings plan execution is cancelled by you or your user. NOTE: A savings plan execution can only be cancelled if it is in the `NEW` state.

Example savings plan execution object

{
  "id": "4b9732bd-7496-491-8a5f-6360479d7fed",
  "savings_plan_id": "00ef0be8-d564-43af-b3c7-11b7a2188030",
 "type" : "INSTRUMENT"  
 "order_id": "6885ddc1-3e23-4f87-9a7d-71ec4ca73286"
  "cash_amount": "100.00",
  "currency": "EUR",
  "execution_date" : "2023-07-24",
  "state": "FILLED",
 "created_at": "2023-07-21T14:10:00.00Z",
 "updated_at": "2023-07-21T14:10:00.00Z" 
}

Monitoring savings plan executions with webhooks

A webhook is sent for each state transition that the savings plan goes through in its lifecycle.

Example webhook object

{
  "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": "INSTRUMENT",
    "instrument_id": "DE0007664005",
    "instrument_id_type": "ISIN",
    "execution_date": "2023-07-23"
  },
  "webhook_id": "cd2e4183-4e62-4e0f-981b-44b594d14610"
}

Webhooks notify you of events in business processes, not the success or failure of the initialisation of those processes.

Please be sure to check the HTTP status of the response to your requests and handle failure cases appropriately.

States of a savings plan execution in webhooks

This section describes the statuses you'll receive in webhooks as the savings plan passes, step-by-step, through each phase of its execution.

SAVINGS_PLAN_EXECUTION.NEW You receive this webhook when a new savings plan execution is started.
SAVINGS_PLAN_EXECUTION.PROCESSING You receive this webhook when the underlying order is being processed.
- For instrument savings plans, you will receive a series of order events from NEW to PROCESSING to FILLED for the respective individual order.
- For portfolio savings plans, you will receive the same series of events for both the portfolio order and the resulting individual orders.
SAVINGS_PLAN_EXECUTION.FILLED Once a savings plan execution is FILLED, the process repeats from step 1. You will receive a webhook for the next scheduled execution for that savings plan, providing you with all the information you need for a smooth execution.