# 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"](/products/tol/guides/saving_plans/saving_plans_inspect#retrieving-savings-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` | The savings plan execution is created in this state. | | `PROCESSING` | The respective savings plan order (either individual order or portfolio order) are being executed. | | `FILLED` | The savings plan execution is `FILLED` once the underlying order(s) have been fully executed. | | `CANCELLED` | The 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** ```json { "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** ```json { "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](/api_errors) of the response to your requests and handle failure cases appropriately. ## Savings plan execution states 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.REMINDER You will receive this webhook to notify you about an upcoming savings plan execution. You can configure how many days in advance the webhook notification is sent, for example, three days before the scheduled execution date. 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. ## Automatically cancelled savings plan executions When a savings plan execution cannot be fulfilled due to insufficient funds, Upvest automatically cancels the execution and its associated order once a defined time threshold has passed. This prevents a single savings plan execution from blocking all future scheduled investments. ### Automatic cancellation workflow A new savings plan execution cannot be created until the previous one completes. Under normal conditions, this happens automatically. However, if an order cannot be executed due to missing funds, the current savings plan execution can become stuck in the `PROCESSING` state. This blocks all subsequent executions. To resolve this, Upvest automatically cancels any savings plan execution when the associated order remains unfilled after **more than 50%** of the interval period has elapsed since the execution date. When a savings plan execution is automatically cancelled, you will receive the existing `SAVINGS_PLAN_EXECUTION.CANCELLED` webhook event. You can use this event to update the status of the execution in your system. ### Example - automatic savings plan execution cancellation In this example, an end user sets up a monthly savings plan. The following shows the behavior when a savings plan execution cannot complete: 1. A savings plan execution is created with an `execution_date` of **1 February**. 2. The account has insufficient funds, and the related order remains in a `NEW` state. 3. By **15 February** (50% of the monthly interval), Upvest automatically cancels both the savings plan execution and the linked order. 4. The next savings plan execution is created with an `execution_date` of **1 March** and proceeds as normal. The missed execution is treated as an isolated event. This means only the single execution for February is affected.