> For the complete documentation index, see [llms.txt](https://docs.tradevest.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tradevest.ai/api-reference/asset-management/savings-plans.md).

# Savings Plans

## Create Savings Plan

> Create a savings plan for a customer.

```json
{"openapi":"3.0.1","info":{"title":"Savings Plans","version":"1.0"},"tags":[{"name":"Savings Plans","description":"Savings Plans"}],"servers":[{"url":"https://tvda-api.platform-test.tradevest.ai","description":"Test"},{"url":"https://tvda-api.platform-pretest.tradevest.ai","description":"Pretest"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"","refreshUrl":"","scopes":{}}}}},"schemas":{"SavingsPlanResult":{"title":"SavingsPlanResult","type":"object","description":"The result of creating a savings plan.","required":["savingsPlanId"],"properties":{"savingsPlanId":{"type":"string","format":"uuid","description":"The UUID of the newly created savings plan."}}},"ErrorMessage":{"title":"ErrorMessage","type":"object","properties":{"message":{"type":"string"},"responseType":{"type":"string"},"validationString":{"minLength":1,"type":"string"},"requestId":{"type":"string"},"errorCode":{"type":"string","maxLength":255},"errorDetails":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetails"}}},"required":["message","responseType","requestId"]},"ErrorDetails":{"title":"ErrorDetails","type":"object","properties":{"field":{"type":"string","maxLength":255},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetailsExplanation"}}},"required":["field"]},"ErrorDetailsExplanation":{"title":"ErrorDetailsExplanation","type":"object","properties":{"code":{"type":"string","maxLength":255},"parameter":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"SavingsPlanData":{"title":"SavingsPlanData","type":"object","description":"Savings plan creation model.","required":["instrumentType","instrumentIdentifier","savingsAmount","currency","intervalPeriod","intervalDay","liquidityCustomerProductId","savingsCustomerProductId","startDate"],"properties":{"startDate":{"type":"string","format":"date","description":"The date from which the savings plan should start executing. Must be today or a future date."},"endDate":{"type":"string","format":"date","description":"Optional date after which the savings plan should stop executing. Must be strictly after startDate. Once this date passes the plan is transitioned to DELETED by the nightly expiry job."},"instrumentType":{"$ref":"#/components/schemas/InstrumentTypeEnum"},"instrumentIdentifier":{"type":"string","description":"Instrument identifier. For DIGITAL_ASSET this is the crypto symbol (e.g. BTC). For TRADITIONAL_ASSET this is the ISIN (e.g. US38259P5089)."},"savingsAmount":{"type":"number","multipleOf":0.01,"description":"The amount to invest on each savings plan execution. Must be a multiple of 0.01 (2 decimal places)."},"currency":{"$ref":"#/components/schemas/CurrencyEnum"},"intervalPeriod":{"$ref":"#/components/schemas/SavingsPlanIntervalPeriodEnum"},"intervalDay":{"$ref":"#/components/schemas/SavingsPlanIntervalDayEnum"},"liquidityCustomerProductId":{"type":"string","format":"uuid","description":"The customer product ID of the liquidity account (product_id = 8) used to fund the savings plan."},"savingsCustomerProductId":{"type":"string","format":"uuid","description":"The customer product ID of the savings account. Must be product_id = 2 for DIGITAL_ASSET or product_id = 15 for TRADITIONAL_ASSET."},"externalId":{"type":"string","maxLength":100,"description":"Optional external identifier set by the partner for their own reference."}}},"InstrumentTypeEnum":{"title":"InstrumentTypeEnum","type":"string","enum":["DIGITAL_ASSET","TRADITIONAL_ASSET"],"description":"The type of instrument for the savings plan."},"CurrencyEnum":{"title":"CurrencyEnum","type":"string","description":"Currency of the product's balance. Currency code in ISO 4217","enum":["EUR"]},"SavingsPlanIntervalPeriodEnum":{"title":"SavingsPlanIntervalPeriodEnum","type":"string","enum":["MONTH"],"description":"The interval period for savings plan execution."},"SavingsPlanIntervalDayEnum":{"title":"SavingsPlanIntervalDayEnum","type":"integer","enum":[1,16],"description":"The day of the interval period on which the savings plan executes."}}},"paths":{"/savings-plans":{"post":{"summary":"Create Savings Plan","operationId":"create-savings-plan","tags":["Savings Plans"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavingsPlanResult"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"description":"Create a savings plan for a customer.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavingsPlanData"}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"name":"Requestor-ID","in":"header","required":true,"description":"Unique requestor identification in UUID format"}]}}}}
```

## Get Savings Plan

> Get a savings plan by its ID. Returns 404 if the plan has been deleted or does not exist within the calling partner's scope.

```json
{"openapi":"3.0.1","info":{"title":"Savings Plans","version":"1.0"},"tags":[{"name":"Savings Plans","description":"Savings Plans"}],"servers":[{"url":"https://tvda-api.platform-test.tradevest.ai","description":"Test"},{"url":"https://tvda-api.platform-pretest.tradevest.ai","description":"Pretest"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"","refreshUrl":"","scopes":{}}}}},"schemas":{"SavingsPlan":{"type":"object","properties":{"savingsPlanId":{"type":"string","format":"uuid","description":"Unique identifier of the savings plan."},"customerId":{"type":"string","format":"uuid","description":"Unique identifier of the customer who owns this savings plan."},"status":{"$ref":"#/components/schemas/SavingsPlanStatusEnum"},"createdOn":{"type":"string","format":"date-time","description":"When this savings plan was created."},"modifiedOn":{"type":"string","format":"date-time","description":"When this savings plan was last updated."},"externalId":{"type":"string","description":"Optional external identifier set by the partner for their own reference.","maxLength":100},"message":{"type":"string","description":"Reason why the savings plan is invalid. Only present when status=INVALID. Matches the validationError.description delivered in the VALIDATION_ERROR webhook."},"startDate":{"type":"string","format":"date","description":"The date from which the savings plan should start executing. Must be today or a future date."},"endDate":{"type":"string","format":"date","description":"Optional date after which the savings plan should stop executing. Must be strictly after startDate. Once this date passes the plan is transitioned to DELETED by the nightly expiry job."},"instrumentType":{"$ref":"#/components/schemas/InstrumentTypeEnum"},"instrumentIdentifier":{"type":"string","description":"Instrument identifier. For DIGITAL_ASSET this is the crypto symbol (e.g. BTC). For TRADITIONAL_ASSET this is the ISIN (e.g. US38259P5089)."},"savingsAmount":{"type":"number","multipleOf":0.01,"description":"The amount to invest on each savings plan execution. Must be a multiple of 0.01 (2 decimal places)."},"currency":{"$ref":"#/components/schemas/CurrencyEnum"},"intervalPeriod":{"$ref":"#/components/schemas/SavingsPlanIntervalPeriodEnum"},"intervalDay":{"$ref":"#/components/schemas/SavingsPlanIntervalDayEnum"},"liquidityCustomerProductId":{"type":"string","format":"uuid","description":"The customer product ID of the liquidity account (product_id = 8) used to fund the savings plan."},"savingsCustomerProductId":{"type":"string","format":"uuid","description":"The customer product ID of the savings account. Must be product_id = 2 for DIGITAL_ASSET or product_id = 15 for TRADITIONAL_ASSET."}},"required":["createdOn","currency","customerId","instrumentIdentifier","instrumentType","intervalDay","intervalPeriod","liquidityCustomerProductId","modifiedOn","savingsAmount","savingsCustomerProductId","savingsPlanId","startDate","status"],"title":"SavingsPlan","description":"Single savings plan model."},"SavingsPlanStatusEnum":{"title":"SavingsPlanStatusEnum","enum":["ACTIVE","INACTIVE","RECEIVED","INVALID"],"description":"The current status of the savings plan."},"InstrumentTypeEnum":{"title":"InstrumentTypeEnum","type":"string","enum":["DIGITAL_ASSET","TRADITIONAL_ASSET"],"description":"The type of instrument for the savings plan."},"CurrencyEnum":{"title":"CurrencyEnum","type":"string","description":"Currency of the product's balance. Currency code in ISO 4217","enum":["EUR"]},"SavingsPlanIntervalPeriodEnum":{"title":"SavingsPlanIntervalPeriodEnum","type":"string","enum":["MONTH"],"description":"The interval period for savings plan execution."},"SavingsPlanIntervalDayEnum":{"title":"SavingsPlanIntervalDayEnum","type":"integer","enum":[1,16],"description":"The day of the interval period on which the savings plan executes."},"ErrorMessage":{"title":"ErrorMessage","type":"object","properties":{"message":{"type":"string"},"responseType":{"type":"string"},"validationString":{"minLength":1,"type":"string"},"requestId":{"type":"string"},"errorCode":{"type":"string","maxLength":255},"errorDetails":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetails"}}},"required":["message","responseType","requestId"]},"ErrorDetails":{"title":"ErrorDetails","type":"object","properties":{"field":{"type":"string","maxLength":255},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetailsExplanation"}}},"required":["field"]},"ErrorDetailsExplanation":{"title":"ErrorDetailsExplanation","type":"object","properties":{"code":{"type":"string","maxLength":255},"parameter":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"paths":{"/savings-plans/{savingsPlanId}":{"get":{"summary":"Get Savings Plan","operationId":"get-savings-plan","tags":["Savings Plans"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavingsPlan"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"description":"Get a savings plan by its ID. Returns 404 if the plan has been deleted or does not exist within the calling partner's scope."}}}}
```

## Delete Savings Plan

> Soft delete a savings plan by its ID. Sets deletedAt timestamp. Deleted plans are excluded from GET responses.

```json
{"openapi":"3.0.1","info":{"title":"Savings Plans","version":"1.0"},"tags":[{"name":"Savings Plans","description":"Savings Plans"}],"servers":[{"url":"https://tvda-api.platform-test.tradevest.ai","description":"Test"},{"url":"https://tvda-api.platform-pretest.tradevest.ai","description":"Pretest"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"","refreshUrl":"","scopes":{}}}}},"schemas":{"ErrorMessage":{"title":"ErrorMessage","type":"object","properties":{"message":{"type":"string"},"responseType":{"type":"string"},"validationString":{"minLength":1,"type":"string"},"requestId":{"type":"string"},"errorCode":{"type":"string","maxLength":255},"errorDetails":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetails"}}},"required":["message","responseType","requestId"]},"ErrorDetails":{"title":"ErrorDetails","type":"object","properties":{"field":{"type":"string","maxLength":255},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetailsExplanation"}}},"required":["field"]},"ErrorDetailsExplanation":{"title":"ErrorDetailsExplanation","type":"object","properties":{"code":{"type":"string","maxLength":255},"parameter":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"paths":{"/savings-plans/{savingsPlanId}":{"delete":{"summary":"Delete Savings Plan","operationId":"delete-savings-plan","tags":["Savings Plans"],"responses":{"202":{"description":"Accepted"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"description":"Soft delete a savings plan by its ID. Sets deletedAt timestamp. Deleted plans are excluded from GET responses.","parameters":[{"schema":{"type":"string","format":"uuid"},"name":"Requestor-ID","in":"header","required":true,"description":"Unique requestor identification in UUID format"}]}}}}
```

## Update Savings Plan

> Update a savings plan by its ID. Cannot update a deleted savings plan.

```json
{"openapi":"3.0.1","info":{"title":"Savings Plans","version":"1.0"},"tags":[{"name":"Savings Plans","description":"Savings Plans"}],"servers":[{"url":"https://tvda-api.platform-test.tradevest.ai","description":"Test"},{"url":"https://tvda-api.platform-pretest.tradevest.ai","description":"Pretest"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"","refreshUrl":"","scopes":{}}}}},"schemas":{"ErrorMessage":{"title":"ErrorMessage","type":"object","properties":{"message":{"type":"string"},"responseType":{"type":"string"},"validationString":{"minLength":1,"type":"string"},"requestId":{"type":"string"},"errorCode":{"type":"string","maxLength":255},"errorDetails":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetails"}}},"required":["message","responseType","requestId"]},"ErrorDetails":{"title":"ErrorDetails","type":"object","properties":{"field":{"type":"string","maxLength":255},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetailsExplanation"}}},"required":["field"]},"ErrorDetailsExplanation":{"title":"ErrorDetailsExplanation","type":"object","properties":{"code":{"type":"string","maxLength":255},"parameter":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"SavingsPlanUpdate":{"title":"SavingsPlanUpdate","type":"object","description":"Savings plan update model. Used to toggle between ACTIVE and INACTIVE status.","properties":{"status":{"$ref":"#/components/schemas/SavingsPlanToggleStatusEnum"}}},"SavingsPlanToggleStatusEnum":{"title":"SavingsPlanToggleStatusEnum","enum":["ACTIVE","INACTIVE"],"description":"The target status when toggling a savings plan."}}},"paths":{"/savings-plans/{savingsPlanId}":{"patch":{"summary":"Update Savings Plan","operationId":"patch-savings-plan","tags":["Savings Plans"],"responses":{"202":{"description":"Accepted"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"description":"Update a savings plan by its ID. Cannot update a deleted savings plan.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavingsPlanUpdate"}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"name":"Requestor-ID","in":"header","required":true,"description":"Unique requestor identification in UUID format"}]}}}}
```

## Sell Savings Plan

> Trigger exit of a savings plan position. Evaluates the accumulated fractional position,\
> selects the execution path, and returns a sell order ID. The outcome is delivered\
> asynchronously via a savings plan notification: on success the plan transitions to DELETED,\
> on rejection a VALIDATION\_ERROR is sent with the plan's status unchanged.

```json
{"openapi":"3.0.1","info":{"title":"Savings Plans","version":"1.0"},"tags":[{"name":"Savings Plans","description":"Savings Plans"}],"servers":[{"url":"https://tvda-api.platform-test.tradevest.ai","description":"Test"},{"url":"https://tvda-api.platform-pretest.tradevest.ai","description":"Pretest"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"","refreshUrl":"","scopes":{}}}}},"schemas":{"SavingsPlanSellResult":{"title":"SavingsPlanSellResult","type":"object","description":"Result of initiating a savings plan sell.","required":["sellOrderId"],"properties":{"sellOrderId":{"type":"string","format":"uuid","description":"UUID of the created sell order."}}},"ErrorMessage":{"title":"ErrorMessage","type":"object","properties":{"message":{"type":"string"},"responseType":{"type":"string"},"validationString":{"minLength":1,"type":"string"},"requestId":{"type":"string"},"errorCode":{"type":"string","maxLength":255},"errorDetails":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetails"}}},"required":["message","responseType","requestId"]},"ErrorDetails":{"title":"ErrorDetails","type":"object","properties":{"field":{"type":"string","maxLength":255},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetailsExplanation"}}},"required":["field"]},"ErrorDetailsExplanation":{"title":"ErrorDetailsExplanation","type":"object","properties":{"code":{"type":"string","maxLength":255},"parameter":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"SavingsPlanSellData":{"title":"SavingsPlanSellData","type":"object","description":"Request body for triggering a savings plan exit.","required":["savingsCustomerProductId","liquidityCustomerProductId"],"properties":{"savingsCustomerProductId":{"type":"string","format":"uuid","description":"UUID of the depository customer product holding the accumulated position."},"liquidityCustomerProductId":{"type":"string","format":"uuid","description":"UUID of the cash customer product to receive sale proceeds."}}}}},"paths":{"/savings-plans/{savingsPlanId}/sell":{"post":{"summary":"Sell Savings Plan","operationId":"sell-savings-plan","tags":["Savings Plans"],"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavingsPlanSellResult"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"description":"Trigger exit of a savings plan position. Evaluates the accumulated fractional position,\nselects the execution path, and returns a sell order ID. The outcome is delivered\nasynchronously via a savings plan notification: on success the plan transitions to DELETED,\non rejection a VALIDATION_ERROR is sent with the plan's status unchanged.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavingsPlanSellData"}}}},"parameters":[{"schema":{"type":"string","format":"uuid"},"name":"Requestor-ID","in":"header","required":true,"description":"Unique requestor identification in UUID format"}]}}}}
```

## Get Savings Plan Executions

> List the orders of a savings plan in an order-like shape. Covers both the periodic\
> BUY executions and the SELL exit, distinguished by tradeSide. Returns a paginated list.

```json
{"openapi":"3.0.1","info":{"title":"Savings Plans","version":"1.0"},"tags":[{"name":"Savings Plans","description":"Savings Plans"}],"servers":[{"url":"https://tvda-api.platform-test.tradevest.ai","description":"Test"},{"url":"https://tvda-api.platform-pretest.tradevest.ai","description":"Pretest"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"","refreshUrl":"","scopes":{}}}}},"schemas":{"SavingsPlansExecutions":{"title":"SavingsPlansExecutions","type":"object","description":"Paginated list of savings plan orders.","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SavingsPlansExecution"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"SavingsPlansExecution":{"title":"SavingsPlansExecution","type":"object","description":"A single savings plan order in an order-like shape. Represents either a periodic BUY execution or the SELL exit, distinguished by tradeSide.","properties":{"executionId":{"type":"string","format":"uuid","description":"Unique identifier of the order (execution or exit)."},"savingsPlanId":{"type":"string","format":"uuid"},"exAnteId":{"type":"string","format":"uuid","nullable":true,"description":"Reserved for ex-ante cost disclosure. Always null for savings plan orders."},"createdOn":{"type":"string","format":"date-time"},"modifiedOn":{"type":"string","format":"date-time"},"status":{"$ref":"#/components/schemas/SavingsPlansOrderStatusEnum"},"failureReason":{"type":"string","nullable":true,"description":"Populated for failed orders (e.g. REJECTED); null otherwise."},"executionDatePlanned":{"type":"string","format":"date","description":"The date on which this order was planned to execute. Present for BUY executions."},"isin":{"type":"string"},"savingsAmount":{"type":"number","multipleOf":0.01,"description":"The savings amount for this BUY execution. Absent for SELL exits."},"currency":{"$ref":"#/components/schemas/CurrencyEnum"},"exchangeCode":{"$ref":"#/components/schemas/SavingsPlansExchangeCodeEnum"},"tradeSide":{"$ref":"#/components/schemas/TradeSideEnum"},"execution":{"$ref":"#/components/schemas/SavingsPlansExecutionData"}},"required":["executionId","savingsPlanId","createdOn","modifiedOn","status","isin","tradeSide"]},"SavingsPlansOrderStatusEnum":{"title":"SavingsPlansOrderStatusEnum","type":"string","enum":["PENDING","PLACED","FILLED","REJECTED","EXPIRED","CANCELLED"],"description":"Status of a savings plan order (execution or exit), aligned with the traditional trading vocabulary. For BUY executions the internal lifecycle maps as PLANNED/READY -> PENDING, PLACED, FILLED, REJECTED, CANCELLED. For SELL exits the status maps directly."},"CurrencyEnum":{"title":"CurrencyEnum","type":"string","description":"Currency of the product's balance. Currency code in ISO 4217","enum":["EUR"]},"SavingsPlansExchangeCodeEnum":{"title":"SavingsPlansExchangeCodeEnum","type":"string","enum":["TGAT","XOFF"],"description":"Venue of a savings plan order. TGAT when the batch touched the exchange (ordered_quantity > 0 for BUY, exchange execution path for SELL); XOFF for pure FIFO / internal TVM allocation."},"TradeSideEnum":{"title":"TradeSideEnum","type":"string","enum":["BUY","SELL"]},"SavingsPlansExecutionData":{"title":"SavingsPlansExecutionData","type":"object","description":"Execution detail of a filled savings plan order. Present once status is FILLED.","properties":{"executionPrice":{"type":"number","description":"The unified fill price used for the allocation."},"executionQuantity":{"type":"number","description":"The fractional quantity allocated (BUY) or sold (SELL)."},"transactionTime":{"type":"string","format":"date-time","description":"The fill time (value date) of the underlying order."},"amount":{"type":"number","multipleOf":0.01,"description":"executionQuantity x executionPrice, rounded to 2 decimal places."},"amountCurrency":{"$ref":"#/components/schemas/CurrencyEnum"},"feeAmount":{"type":"number","multipleOf":0.01},"germanCit":{"type":"number","format":"decimal","description":"German capital income tax. 0 for BUY executions; populated for SELL exits."},"solidaritySurcharge":{"type":"number","format":"decimal","description":"German solidarity surcharge. 0 for BUY executions; populated for SELL exits."},"churchTax":{"type":"number","format":"decimal","description":"German church tax. 0 for BUY executions; populated for SELL exits."}},"required":["executionPrice","executionQuantity","transactionTime","amount","amountCurrency","germanCit","solidaritySurcharge","churchTax"]},"Pagination":{"title":"Pagination","type":"object","properties":{"cursor":{"type":"string","description":"String value used for pagination, which should be set in next page request."},"limit":{"type":"integer","description":"Maximum number of returned items"}},"required":["cursor","limit"]},"ErrorMessage":{"title":"ErrorMessage","type":"object","properties":{"message":{"type":"string"},"responseType":{"type":"string"},"validationString":{"minLength":1,"type":"string"},"requestId":{"type":"string"},"errorCode":{"type":"string","maxLength":255},"errorDetails":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetails"}}},"required":["message","responseType","requestId"]},"ErrorDetails":{"title":"ErrorDetails","type":"object","properties":{"field":{"type":"string","maxLength":255},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetailsExplanation"}}},"required":["field"]},"ErrorDetailsExplanation":{"title":"ErrorDetailsExplanation","type":"object","properties":{"code":{"type":"string","maxLength":255},"parameter":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"paths":{"/savings-plans/{savingsPlanId}/executions":{"get":{"summary":"Get Savings Plan Executions","operationId":"get-savings-plan-executions","tags":["Savings Plans"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavingsPlansExecutions"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"description":"List the orders of a savings plan in an order-like shape. Covers both the periodic\nBUY executions and the SELL exit, distinguished by tradeSide. Returns a paginated list.","parameters":[{"schema":{"$ref":"#/components/schemas/SavingsPlansOrderStatusEnum"},"in":"query","name":"status","description":"Filter by order status"},{"schema":{"type":"string","format":"date"},"in":"query","name":"executionDateFrom","description":"Return orders with a planned execution date on or after this date (inclusive)"},{"schema":{"type":"string","format":"date"},"in":"query","name":"executionDateTo","description":"Return orders with a planned execution date on or before this date (inclusive)"},{"schema":{"type":"integer","default":20,"minimum":1},"in":"query","name":"limit","description":"Maximum number of results to return per page"},{"schema":{"type":"string"},"in":"query","name":"cursor","description":"Pagination cursor returned from a previous response"}]}}}}
```

## Get Savings Plan Execution

> Get a single savings plan order (execution or exit) by its ID, within the calling\
> partner's scope.

```json
{"openapi":"3.0.1","info":{"title":"Savings Plans","version":"1.0"},"tags":[{"name":"Savings Plans","description":"Savings Plans"}],"servers":[{"url":"https://tvda-api.platform-test.tradevest.ai","description":"Test"},{"url":"https://tvda-api.platform-pretest.tradevest.ai","description":"Pretest"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"","refreshUrl":"","scopes":{}}}}},"schemas":{"SavingsPlansExecution":{"title":"SavingsPlansExecution","type":"object","description":"A single savings plan order in an order-like shape. Represents either a periodic BUY execution or the SELL exit, distinguished by tradeSide.","properties":{"executionId":{"type":"string","format":"uuid","description":"Unique identifier of the order (execution or exit)."},"savingsPlanId":{"type":"string","format":"uuid"},"exAnteId":{"type":"string","format":"uuid","nullable":true,"description":"Reserved for ex-ante cost disclosure. Always null for savings plan orders."},"createdOn":{"type":"string","format":"date-time"},"modifiedOn":{"type":"string","format":"date-time"},"status":{"$ref":"#/components/schemas/SavingsPlansOrderStatusEnum"},"failureReason":{"type":"string","nullable":true,"description":"Populated for failed orders (e.g. REJECTED); null otherwise."},"executionDatePlanned":{"type":"string","format":"date","description":"The date on which this order was planned to execute. Present for BUY executions."},"isin":{"type":"string"},"savingsAmount":{"type":"number","multipleOf":0.01,"description":"The savings amount for this BUY execution. Absent for SELL exits."},"currency":{"$ref":"#/components/schemas/CurrencyEnum"},"exchangeCode":{"$ref":"#/components/schemas/SavingsPlansExchangeCodeEnum"},"tradeSide":{"$ref":"#/components/schemas/TradeSideEnum"},"execution":{"$ref":"#/components/schemas/SavingsPlansExecutionData"}},"required":["executionId","savingsPlanId","createdOn","modifiedOn","status","isin","tradeSide"]},"SavingsPlansOrderStatusEnum":{"title":"SavingsPlansOrderStatusEnum","type":"string","enum":["PENDING","PLACED","FILLED","REJECTED","EXPIRED","CANCELLED"],"description":"Status of a savings plan order (execution or exit), aligned with the traditional trading vocabulary. For BUY executions the internal lifecycle maps as PLANNED/READY -> PENDING, PLACED, FILLED, REJECTED, CANCELLED. For SELL exits the status maps directly."},"CurrencyEnum":{"title":"CurrencyEnum","type":"string","description":"Currency of the product's balance. Currency code in ISO 4217","enum":["EUR"]},"SavingsPlansExchangeCodeEnum":{"title":"SavingsPlansExchangeCodeEnum","type":"string","enum":["TGAT","XOFF"],"description":"Venue of a savings plan order. TGAT when the batch touched the exchange (ordered_quantity > 0 for BUY, exchange execution path for SELL); XOFF for pure FIFO / internal TVM allocation."},"TradeSideEnum":{"title":"TradeSideEnum","type":"string","enum":["BUY","SELL"]},"SavingsPlansExecutionData":{"title":"SavingsPlansExecutionData","type":"object","description":"Execution detail of a filled savings plan order. Present once status is FILLED.","properties":{"executionPrice":{"type":"number","description":"The unified fill price used for the allocation."},"executionQuantity":{"type":"number","description":"The fractional quantity allocated (BUY) or sold (SELL)."},"transactionTime":{"type":"string","format":"date-time","description":"The fill time (value date) of the underlying order."},"amount":{"type":"number","multipleOf":0.01,"description":"executionQuantity x executionPrice, rounded to 2 decimal places."},"amountCurrency":{"$ref":"#/components/schemas/CurrencyEnum"},"feeAmount":{"type":"number","multipleOf":0.01},"germanCit":{"type":"number","format":"decimal","description":"German capital income tax. 0 for BUY executions; populated for SELL exits."},"solidaritySurcharge":{"type":"number","format":"decimal","description":"German solidarity surcharge. 0 for BUY executions; populated for SELL exits."},"churchTax":{"type":"number","format":"decimal","description":"German church tax. 0 for BUY executions; populated for SELL exits."}},"required":["executionPrice","executionQuantity","transactionTime","amount","amountCurrency","germanCit","solidaritySurcharge","churchTax"]},"ErrorMessage":{"title":"ErrorMessage","type":"object","properties":{"message":{"type":"string"},"responseType":{"type":"string"},"validationString":{"minLength":1,"type":"string"},"requestId":{"type":"string"},"errorCode":{"type":"string","maxLength":255},"errorDetails":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetails"}}},"required":["message","responseType","requestId"]},"ErrorDetails":{"title":"ErrorDetails","type":"object","properties":{"field":{"type":"string","maxLength":255},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetailsExplanation"}}},"required":["field"]},"ErrorDetailsExplanation":{"title":"ErrorDetailsExplanation","type":"object","properties":{"code":{"type":"string","maxLength":255},"parameter":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"paths":{"/savings-plans/{savingsPlanId}/executions/{executionId}":{"get":{"summary":"Get Savings Plan Execution","operationId":"get-savings-plan-execution","tags":["Savings Plans"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavingsPlansExecution"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"description":"Get a single savings plan order (execution or exit) by its ID, within the calling\npartner's scope."}}}}
```

## Get Customer Savings Plans

> Get all savings plans for a customer. Deleted plans are excluded.

```json
{"openapi":"3.0.1","info":{"title":"Savings Plans","version":"1.0"},"tags":[{"name":"Savings Plans","description":"Savings Plans"}],"servers":[{"url":"https://tvda-api.platform-test.tradevest.ai","description":"Test"},{"url":"https://tvda-api.platform-pretest.tradevest.ai","description":"Pretest"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"","refreshUrl":"","scopes":{}}}}},"schemas":{"SavingsPlans":{"title":"SavingsPlans","type":"object","description":"List of savings plans returned.","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SavingsPlan"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"SavingsPlan":{"type":"object","properties":{"savingsPlanId":{"type":"string","format":"uuid","description":"Unique identifier of the savings plan."},"customerId":{"type":"string","format":"uuid","description":"Unique identifier of the customer who owns this savings plan."},"status":{"$ref":"#/components/schemas/SavingsPlanStatusEnum"},"createdOn":{"type":"string","format":"date-time","description":"When this savings plan was created."},"modifiedOn":{"type":"string","format":"date-time","description":"When this savings plan was last updated."},"externalId":{"type":"string","description":"Optional external identifier set by the partner for their own reference.","maxLength":100},"message":{"type":"string","description":"Reason why the savings plan is invalid. Only present when status=INVALID. Matches the validationError.description delivered in the VALIDATION_ERROR webhook."},"startDate":{"type":"string","format":"date","description":"The date from which the savings plan should start executing. Must be today or a future date."},"endDate":{"type":"string","format":"date","description":"Optional date after which the savings plan should stop executing. Must be strictly after startDate. Once this date passes the plan is transitioned to DELETED by the nightly expiry job."},"instrumentType":{"$ref":"#/components/schemas/InstrumentTypeEnum"},"instrumentIdentifier":{"type":"string","description":"Instrument identifier. For DIGITAL_ASSET this is the crypto symbol (e.g. BTC). For TRADITIONAL_ASSET this is the ISIN (e.g. US38259P5089)."},"savingsAmount":{"type":"number","multipleOf":0.01,"description":"The amount to invest on each savings plan execution. Must be a multiple of 0.01 (2 decimal places)."},"currency":{"$ref":"#/components/schemas/CurrencyEnum"},"intervalPeriod":{"$ref":"#/components/schemas/SavingsPlanIntervalPeriodEnum"},"intervalDay":{"$ref":"#/components/schemas/SavingsPlanIntervalDayEnum"},"liquidityCustomerProductId":{"type":"string","format":"uuid","description":"The customer product ID of the liquidity account (product_id = 8) used to fund the savings plan."},"savingsCustomerProductId":{"type":"string","format":"uuid","description":"The customer product ID of the savings account. Must be product_id = 2 for DIGITAL_ASSET or product_id = 15 for TRADITIONAL_ASSET."}},"required":["createdOn","currency","customerId","instrumentIdentifier","instrumentType","intervalDay","intervalPeriod","liquidityCustomerProductId","modifiedOn","savingsAmount","savingsCustomerProductId","savingsPlanId","startDate","status"],"title":"SavingsPlan","description":"Single savings plan model."},"SavingsPlanStatusEnum":{"title":"SavingsPlanStatusEnum","enum":["ACTIVE","INACTIVE","RECEIVED","INVALID"],"description":"The current status of the savings plan."},"InstrumentTypeEnum":{"title":"InstrumentTypeEnum","type":"string","enum":["DIGITAL_ASSET","TRADITIONAL_ASSET"],"description":"The type of instrument for the savings plan."},"CurrencyEnum":{"title":"CurrencyEnum","type":"string","description":"Currency of the product's balance. Currency code in ISO 4217","enum":["EUR"]},"SavingsPlanIntervalPeriodEnum":{"title":"SavingsPlanIntervalPeriodEnum","type":"string","enum":["MONTH"],"description":"The interval period for savings plan execution."},"SavingsPlanIntervalDayEnum":{"title":"SavingsPlanIntervalDayEnum","type":"integer","enum":[1,16],"description":"The day of the interval period on which the savings plan executes."},"Pagination":{"title":"Pagination","type":"object","properties":{"cursor":{"type":"string","description":"String value used for pagination, which should be set in next page request."},"limit":{"type":"integer","description":"Maximum number of returned items"}},"required":["cursor","limit"]},"ErrorMessage":{"title":"ErrorMessage","type":"object","properties":{"message":{"type":"string"},"responseType":{"type":"string"},"validationString":{"minLength":1,"type":"string"},"requestId":{"type":"string"},"errorCode":{"type":"string","maxLength":255},"errorDetails":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetails"}}},"required":["message","responseType","requestId"]},"ErrorDetails":{"title":"ErrorDetails","type":"object","properties":{"field":{"type":"string","maxLength":255},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetailsExplanation"}}},"required":["field"]},"ErrorDetailsExplanation":{"title":"ErrorDetailsExplanation","type":"object","properties":{"code":{"type":"string","maxLength":255},"parameter":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"paths":{"/customers/{customerId}/savings-plans":{"get":{"summary":"Get Customer Savings Plans","operationId":"get-customer-savings-plans","tags":["Savings Plans"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavingsPlans"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"description":"Get all savings plans for a customer. Deleted plans are excluded.","parameters":[{"schema":{"$ref":"#/components/schemas/SavingsPlanStatusEnum"},"in":"query","name":"status","description":"Filter by savings plan status"},{"schema":{"$ref":"#/components/schemas/InstrumentTypeEnum"},"in":"query","name":"instrumentType","description":"Filter by instrument type"},{"schema":{"type":"string"},"in":"query","name":"instrumentIdentifier","description":"Filter by instrument identifier (ISIN or crypto symbol)"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"liquidityCustomerProductId","description":"Filter by liquidity customer product ID"},{"schema":{"type":"string","format":"uuid"},"in":"query","name":"savingsCustomerProductId","description":"Filter by savings customer product ID"},{"schema":{"type":"string"},"in":"query","name":"externalId","description":"Filter by external identifier set by the partner"},{"schema":{"type":"integer","default":20,"minimum":1},"in":"query","name":"limit","description":"Maximum number of results to return per page"},{"schema":{"type":"string"},"in":"query","name":"cursor","description":"Pagination cursor returned from a previous response"}]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tradevest.ai/api-reference/asset-management/savings-plans.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.