--- title: "Update deposit account attachment overrides" method: PATCH path: "/v1/deposits/accounts/{accountId}/attachment" tags: ["Account attachment"] --- # Update deposit account attachment overrides `PATCH /v1/deposits/accounts/{accountId}/attachment` ## Request - Base URL: `https://sandbox.pismolabs.io/savings-products` - URL: `https://sandbox.pismolabs.io/savings-products/v1/deposits/accounts/{accountId}/attachment` - Auth: HTTP bearer Partially updates `deposit_configs.maturity_period`, `deposit_configs.overrides` and `deposit_configs.interest_capitalization_mode` on an active deposit account attachment. The `overrides` fields are processed using three‑state `PATCH` semantics, allowing values to be added, changed, or cleared as part of the update. * **Omitted**: Keeps the current value * `null`: Removes the override; falls back through the cascade (program → product) * **Value**: Replaces the current override with the supplied value **NOTES**: * At least one of `deposit_configs.maturity_period`, `deposit_configs.overrides` or `deposit_configs.interest_capitalization_mode` must be provided. A payload carrying only `maturity_period` is valid. * The `overrides` envelope, if provided, must contain at least one field. Sending an empty object returns `400 EIBACC0315`. * `renewal_term` still requires `ROLLOVER` configured in `maturity_instructions` somewhere in the fallback sequence (`400 EIBACC0310` otherwise). * `maturity_period` changes the term **in force** and takes effect immediately, recalculating the current cycle's maturity date from the attachment's `effective_date`. It's accepted in both documented forms (`unit`+`value` or `calendar_maturity_date`) and doesn't follow the three-state semantics above: `null` is a no-op, not a removal. * `maturity_period` and `overrides.renewal_term` are independent. `renewal_term` keeps applying at rollover only and never recalculates the current cycle's maturity date. * When `maturity_period` changes, the schedules driven by the maturity date (maturity instruction, maturity notices) are re-evaluated against the new date. * `product_id` and `payout_account` stay fixed after attach and are ignored if included in the request body. To change the payout account, use [Update payout account for deposit account](ref:interest-bearing-v1-deposit-update-payout-account). This endpoint generates an [Account attachment updated](https://developers.pismo.io/events/docs/deposit-product-account-attachment-updated-1) event that includes the active term in `data.maturity_period`. If the account has an external account ID, the event also includes it in `data.external_account_id`. The response returns `external_account_id` whenever the account has one; it is omitted for an account with no external identifier. ## Path parameters - `accountId` string, required ## Request body - UpdateAccountAttachmentRequest - `deposit_configs` object, required: At least one of `maturity_period`, `overrides` or `interest_capitalization_mode` must be provided. - `maturity_period` MaturityPeriod: Defines when the deposit matures. There are three usage modes: * **Relative period**: Sends `unit` + `value` (e.g. `MONTHS` + `6`). * **Explicit date**: Sends `calendar_maturity_date` (e.g. `2027-06-15`). * **Default**: Omits the field or sends `{}`. The product's configured default maturity term (`PRODUCT_DEFAULT_MATURITY_DATE_DAYS`, typically `10950` days ≈ 30 years) is applied. **NOTE**: `calendar_maturity_date` and `unit`/`value` are mutually exclusive, sending both in the same request returns a `400` validation error. In the **attach** endpoints, the response returns exactly what was sent in the request: * Send `unit` + `value` returns `unit` + `value` * Send `calendar_maturity_date` returns `calendar_maturity_date` * Send nothing (default fallback applied) returns `unit=DAYS` and `value` equal to the product's configured `PRODUCT_DEFAULT_MATURITY_DATE_DAYS` **NOTE**: this behavior applies only to attach. The `GET` attachment endpoints and `PATCH /v1/deposits/accounts/{accountId}/attachment` return the resolved term, with `unit`, `value`, and `calendar_maturity_date` populated together. A `PATCH` sent in explicit‑date form is returned normalized as `{unit: DAYS, value: , calendar_maturity_date: }`. - `unit` 'DAYS' | 'WEEKS' | 'MONTHS' | 'YEARS': Time unit for the relative maturity period. It's used together with `value` and cannot coincide with `calendar_maturity_date`. - `DAYS`: Uses `value` directly. Example: `value=90` → 90 days. - `WEEKS`: Multiplies `value` by 7. Example: `value=4` → 28 days. - `MONTHS`: Calculates calendar-month with end-of-month (EOM) clamping when the target day does not exist. The maturity date falls on the same day of the month as the start date. Example: `2026-09-22` + 3 months = `2026-12-22`; `2024-01-31` + 1 month = `2024-02-29` (leap year) or `2025-02-28` (non-leap year). - `YEARS`: Calculates calendar-year, for example: `2024-02-29` + 1 year = `2025-02-28`. Note that there is no Feb 29 in 2025. For `WEEKS`, `MONTHS`, and `YEARS`, the resulting calendar date is converted back to a day count to validate against the product's configured minimum or maximum term. - `value` integer: Number of time units until maturity. Must be greater than `0`. Mutually exclusive with `calendar_maturity_date`. - `calendar_maturity_date` string, date: Maturity date. Format is `YYYY-MM-DD`. The date must be a future date. This date cannot coincide with `unit`/`value`, sending both in the same request returns a `400` validation error. - `interest_capitalization_mode` 'PAYOUT' | 'REINVEST' | 'null', nullable: Updates how capitalized interest is treated on this attachment.
* `PAYOUT` (explicit): Switching to this mode requires the attachment to already have a valid `payout_account`. If none is configured, the request returns `400 EIBACC0379`—set the `payout_account` first via `PATCH /v1/deposits/accounts/{accountId}`, then switch to this mode. * `REINVEST`: The Pismo platform adds the capitalized amount to the principal. No `payout_account` is required. * `Omitted`: The current mode is left unchanged. * `null`: Clears the account‑level value and restores the inherited behavior from the program and then the product default. When the value is missing at all levels, the Pismo platform applies `REINVEST`. This field applies only to the capitalization flow. The maturity instruction flow always uses `payout_account` regardless of the setting. - `overrides` AttachmentOverridesPatchRequest: PATCH envelope for account‑level `deposit_configs.overrides`. Fields support three‑state semantics, omission preserves the current value, `null` removes the override and restores the inherited configuration, and a provided value replaces it. The envelope must define at least one field, an empty overrides object returns a `400` error: `EIBACC0315`. - `maturity_instructions` MaturityInstructionsOverrideRequest: Overrides the deposit’s behavior at maturity. If a field is omitted, the Pismo platform uses the value defined at the higher‑level configuration that governs this deposit. - `principal` 'ROLLOVER' | 'PAY': Specifies how the principal is handled once the deposit matures. - `interest` 'ROLLOVER' | 'PAY': Specifies how the interest is handled once the deposit matures. - `reason` string: Optional audit-trail reason. - `renewal_term` RenewalTermOverrideRequest: Specifies the recurring rollover term, not to be confused with the initial `maturity_period`. You must provide either `unit` with `value` or `renewal_calendar_maturity_date`. A `ROLLOVER` configuration in principal or interest is required. When you pass `renewal_calendar_maturity_date`, the Pismo platform converts the interval from today into a day count and stores it at attach time in normalized form: `{unit: DAYS, value: }`. - `unit` 'DAYS' | 'WEEKS' | 'MONTHS' | 'YEARS': Time unit of the renewal term. Required together with `value` when calendar form is not used. - `value` integer: Number of units. Required together with `unit` when calendar form is not used. - `renewal_calendar_maturity_date` string, date: Explicit calendar date (`YYYY-MM-DD`), the date must be a future date, and does not coincide with `unit`+`value`. - `penalties` PenaltiesPatchRequest: PATCH envelope for `deposit_configs.overrides.penalties`. Penalty types support three‑state semantics: omit to retain the existing value, use `null` to clear the override and restore the inherited configuration, or provide a value object to replace it. `reason` is optional metadata. - `reason` string - `grace_period` GracePeriodOverrideRequest: Grace period override. Type-specific fields are optional pointers, when omitted, the Pismo platform follows the normal fallback sequence, moving from the account level to the program and then to the product defaults. - `waived` boolean, required: `true` = fully exempt; `false` = penalty active (customize via the fields below). - `duration_days` integer - `penalty_interest_days` integer - `valid_until` string, date-time: Schedules the revert of this override via EventBridge. This value must be a future date and follows the ISO 8601 standard. - `early_withdrawal_after_opening` EarlyWithdrawalAfterOpeningOverrideRequest: Override for early withdrawal after account opening. - `waived` boolean, required - `applicable_within_days` integer - `penalty_interest_days` integer - `valid_until` string, date-time - `withdrawal_fee` WithdrawalFeeOverrideRequest: Withdrawal fee override. - `waived` boolean, required - `type` 'PERCENTAGE' | 'FIXED' - `value` number: Same format as the product's `withdrawal_fee.value`. - `valid_until` string, date-time - `tiered_interest_forfeiture` TieredInterestForfeitureOverrideRequest: Tiered interest forfeiture override. Tiers replace the product's tiers when provided. - `waived` boolean, required - `tiers` TieredInterestForfeitureTierRequest[] - `min_days_held` integer, required - `max_days_held` integer: Optional. Open-ended tier when omitted. - `forfeited_interest_days` integer, required - `valid_until` string, date-time - `subsequent_withdrawals` SubsequentWithdrawalsOverrideRequest: Subsequent withdrawals (Regulation D) override. - `waived` boolean, required - `applicable_within_days` integer - `penalty_interest_days` integer - `window_behavior` 'ROLLING' | 'FIXED' - `valid_until` string, date-time ## Response `200` OK - AccountAttachment - `product_type` 'deposit' | 'savings-account': Product type. - `product_id` string: Product identifier. - `external_account_id` string: External account ID. Returned only when the account has an external account identifier. - `interest_plan_id` string: Interest rate plan ID. This corresponds to the ID you created using the [Create interest plan version](ref:patch-v1-interest-plan)) endpoint. - `maturity_period` MaturityPeriod: Defines when the deposit matures. There are three usage modes: * **Relative period**: Sends `unit` + `value` (e.g. `MONTHS` + `6`). * **Explicit date**: Sends `calendar_maturity_date` (e.g. `2027-06-15`). * **Default**: Omits the field or sends `{}`. The product's configured default maturity term (`PRODUCT_DEFAULT_MATURITY_DATE_DAYS`, typically `10950` days ≈ 30 years) is applied. **NOTE**: `calendar_maturity_date` and `unit`/`value` are mutually exclusive, sending both in the same request returns a `400` validation error. In the **attach** endpoints, the response returns exactly what was sent in the request: * Send `unit` + `value` returns `unit` + `value` * Send `calendar_maturity_date` returns `calendar_maturity_date` * Send nothing (default fallback applied) returns `unit=DAYS` and `value` equal to the product's configured `PRODUCT_DEFAULT_MATURITY_DATE_DAYS` **NOTE**: this behavior applies only to attach. The `GET` attachment endpoints and `PATCH /v1/deposits/accounts/{accountId}/attachment` return the resolved term, with `unit`, `value`, and `calendar_maturity_date` populated together. A `PATCH` sent in explicit‑date form is returned normalized as `{unit: DAYS, value: , calendar_maturity_date: }`. - `unit` 'DAYS' | 'WEEKS' | 'MONTHS' | 'YEARS': Time unit for the relative maturity period. It's used together with `value` and cannot coincide with `calendar_maturity_date`. - `DAYS`: Uses `value` directly. Example: `value=90` → 90 days. - `WEEKS`: Multiplies `value` by 7. Example: `value=4` → 28 days. - `MONTHS`: Calculates calendar-month with end-of-month (EOM) clamping when the target day does not exist. The maturity date falls on the same day of the month as the start date. Example: `2026-09-22` + 3 months = `2026-12-22`; `2024-01-31` + 1 month = `2024-02-29` (leap year) or `2025-02-28` (non-leap year). - `YEARS`: Calculates calendar-year, for example: `2024-02-29` + 1 year = `2025-02-28`. Note that there is no Feb 29 in 2025. For `WEEKS`, `MONTHS`, and `YEARS`, the resulting calendar date is converted back to a day count to validate against the product's configured minimum or maximum term. - `value` integer: Number of time units until maturity. Must be greater than `0`. Mutually exclusive with `calendar_maturity_date`. - `calendar_maturity_date` string, date: Maturity date. Format is `YYYY-MM-DD`. The date must be a future date. This date cannot coincide with `unit`/`value`, sending both in the same request returns a `400` validation error. - `attachment_date` string, date-time: Timestamp that indicates when the attachment was created (when the attach API call was made). The datetime format follows the ISO 8601 standard `yyyy-mm-ddThh:mm:ss.sssZ`. - `effective_date` string, date: The effective date of the attachment in `YYYY-MM-DD` format This is the date when the attachment becomes valid. Maturity is calculated from this date. For attachments created in the past, the date defaults to the value of `attachment_date`. - `fee_model_id` string: Fee model identifier, if applicable. - `payout_account` PayoutAccount: The payout account defines where outbound payments are sent, and it is used in two operational contexts.
* **Capitalization flow**: When the capitalization mode is set to `PAYOUT`, the capitalized interest is directed to this account. If the mode is `REINVEST`, the payout account is not involved because the interest is added to the principal instead. * **Maturity instruction flow**: At maturity, this account receives principal or interest whenever the maturity instructions specify `PAY` for either `maturity_instructions.principal` or `maturity_instructions.interest`. This flow always relies on the payout account, regardless of how capitalization is configured. Both flows reference the same payout account settings. Choosing `REINVEST` for capitalization does not remove or disable the payout account, and it remains fully available for maturity‑related payments. - `label` string: Label to identify the account - `type` 'INTERNAL' | 'EXTERNAL': Payout account type, either `INTERNAL` or `EXTERNAL` - `internal_account_id` number: Internal account ID for the account that receives the payments. Required for type `INTERNAL` and not allowed for `EXTERNAL`. - `external_account` object: Contains user-defined key-value pairs that identify the external account receiving the payments. Note that external account information is client-provided. Required for type `EXTERNAL` and not allowed for `INTERNAL`. - `interest_capitalization_mode` 'PAYOUT' | 'REINVEST': Present only when this account attachment explicitly defines `interest_capitalization_mode`. If the field is missing, the effective value is `REINVEST`, inherited from the program configuration or, if the program does not specify it, from the product’s default settings. - `overrides` AttachmentOverridesSnapshot: Representation of the persisted overrides, present only when the request defined at least one override. Sub-fields are included only when set. The `renewal_term` always returns all three fields together (`unit`, `value` and `renewal_calendar_maturity_date`), mirroring the behavior of `maturity_period`. - `maturity_instructions` MaturityInstructionsOverrideRequest: Overrides the deposit’s behavior at maturity. If a field is omitted, the Pismo platform uses the value defined at the higher‑level configuration that governs this deposit. - `principal` 'ROLLOVER' | 'PAY': Specifies how the principal is handled once the deposit matures. - `interest` 'ROLLOVER' | 'PAY': Specifies how the interest is handled once the deposit matures. - `reason` string: Optional audit-trail reason. - `renewal_term` RenewalTermResponse: Renewal term applied on each rollover. Always returns all three fields together — `unit`, `value` and `renewal_calendar_maturity_date` — regardless of the form the client used to configure it, mirroring `maturity_period`. Legacy terms persisted before the calendar date was stored return only `unit`+`value`. - `unit` 'DAYS' | 'WEEKS' | 'MONTHS' | 'YEARS' - `value` integer - `renewal_calendar_maturity_date` string, date: Returned only when the request uses the calendar format. Format = `YYYY-MM-DD`. - `penalties` PenaltiesOverrideSnapshot: Persisted penalty overrides for each type. Types appear only when set. Each entry includes `waived`, the relevant type-specific fields, and an optional `valid_until` for scheduling the revert. - `reason` string - `grace_period` GracePeriodOverrideRequest: Grace period override. Type-specific fields are optional pointers, when omitted, the Pismo platform follows the normal fallback sequence, moving from the account level to the program and then to the product defaults. - `waived` boolean, required: `true` = fully exempt; `false` = penalty active (customize via the fields below). - `duration_days` integer - `penalty_interest_days` integer - `valid_until` string, date-time: Schedules the revert of this override via EventBridge. This value must be a future date and follows the ISO 8601 standard. - `early_withdrawal_after_opening` EarlyWithdrawalAfterOpeningOverrideRequest: Override for early withdrawal after account opening. - `waived` boolean, required - `applicable_within_days` integer - `penalty_interest_days` integer - `valid_until` string, date-time - `withdrawal_fee` WithdrawalFeeOverrideRequest: Withdrawal fee override. - `waived` boolean, required - `type` 'PERCENTAGE' | 'FIXED' - `value` number: Same format as the product's `withdrawal_fee.value`. - `valid_until` string, date-time - `tiered_interest_forfeiture` TieredInterestForfeitureOverrideRequest: Tiered interest forfeiture override. Tiers replace the product's tiers when provided. - `waived` boolean, required - `tiers` TieredInterestForfeitureTierRequest[] - `min_days_held` integer, required - `max_days_held` integer: Optional. Open-ended tier when omitted. - `forfeited_interest_days` integer, required - `valid_until` string, date-time - `subsequent_withdrawals` SubsequentWithdrawalsOverrideRequest: Subsequent withdrawals (Regulation D) override. - `waived` boolean, required - `applicable_within_days` integer - `penalty_interest_days` integer - `window_behavior` 'ROLLING' | 'FIXED' - `valid_until` string, date-time - `accrual_model` 'DEPOSIT_BASIS' | 'BALANCE_BASIS': Accrual model inherited from the attached product. `DEPOSIT_BASIS` or `BALANCE_BASIS`. - `balance_type` 'VALUE_DATED_BALANCE' | 'LEDGER_BALANCE': Balance type inherited from the attached product. Only meaningful when `accrual_model` is `BALANCE_BASIS`. ## Other responses - `400`: Bad Request - `404`: Not Found - `409`: Conflict - `500`: Internal Server Error --- [API](https://skmtc.dev/pismo/apis/banking-interest-bearing-accounts.md) - [All operations](https://skmtc.dev/pismo/apis/banking-interest-bearing-accounts/llms.txt) - [OpenAPI document](https://skmtc.dev/pismo/apis/banking-interest-bearing-accounts/revisions/c68f61feb8a8?raw)