---
updatedAt: 2026-06-15T16:48:40.000Z
---
Fetch the complete documentation index at: https://developers.pismo.io/pismo-docs/llms.txt. Use this file to discover all available pages before exploring further.
# Update deposit account attachment overrides
Partially updates `deposit_configs.overrides` and `deposit_configs.interest_capitalization_mode` on an active deposit account attachment. Each field is 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.overrides` or `deposit_configs.interest_capitalization_mode` must be provided.
* 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).
This endpoint generates an [Account attachment updated](https://developers.pismo.io/events/docs/deposit-product-account-attachment-updated-1) event.
# OpenAPI definition
```json
{
"openapi": "3.1.3",
"info": {
"title": "Banking - Interest-bearing accounts",
"version": "1.0.0",
"description": "API for interest-bearing account functionality",
"contact": {
"name": "API Support",
"url": "https://developers.pismo.io/support/"
},
"license": {
"name": "Copyright Pismo"
}
},
"servers": [
{
"url": "https://sandbox.pismolabs.io/savings-products",
"description": "Sandbox API server for testing"
}
],
"tags": [
{
"name": "Account attachment",
"description": "Endpoints that manage account attachments to interest-bearing account products"
}
],
"components": {
"parameters": {
"authorizationTokenHeader": {
"name": "AuthorizationToken",
"in": "header",
"schema": {
"type": "string"
},
"required": true,
"description": "Account token. Token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a 401 Unauthorized error.\n",
"example": 1234
},
"accountId": {
"description": "Account ID",
"in": "path",
"name": "accountId",
"required": true,
"schema": {
"type": "integer"
},
"example": 123456
}
},
"schemas": {
"ErrorResponse": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error type code",
"example": "EIBACC0003"
},
"details": {
"type": "string",
"description": "Error details",
"example": "error EIBACC0008: Validation error [(Field 'Order' is invalid)]"
},
"message": {
"description": "Error message",
"example": "Bad Request",
"type": "string"
}
}
},
"PayoutAccount": {
"type": "object",
"description": "The payout account defines where outbound payments are sent, and it is used in two operational contexts.
\n\n* **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.\n* **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.\n\nBoth 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.\n",
"properties": {
"label": {
"type": "string",
"description": "Label to identify the account\n",
"example": "My payout account"
},
"type": {
"type": "string",
"description": "Payout account type, either `INTERNAL` or `EXTERNAL`\n",
"enum": [
"INTERNAL",
"EXTERNAL"
],
"example": "INTERNAL"
},
"internal_account_id": {
"type": "number",
"description": "Internal account ID for the account that receives the payments.\nRequired for type `INTERNAL` and not allowed for `EXTERNAL`.\n",
"example": 123456
},
"external_account": {
"type": "object",
"description": "Contains user-defined key-value pairs that identify the external account receiving the payments.\nNote that external account information is client-provided.\n\nRequired for type `EXTERNAL` and not allowed for `INTERNAL`.\n",
"example": {
"key": "value"
}
}
}
},
"MaturityPeriod": {
"type": "object",
"description": "Defines when the deposit matures. There are three usage modes:\n\n* **Relative period**: Sends `unit` + `value` (e.g. `MONTHS` + `6`).\n* **Explicit date**: Sends `calendar_maturity_date` (e.g. `2027-06-15`).\n* **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.\n\n**NOTE**: `calendar_maturity_date` and `unit`/`value` are mutually exclusive, sending both in the same request returns a `400` validation error.\n\nThe response returns exactly what was sent in the request:\n* Send `unit` + `value` returns `unit` + `value`\n* Send `calendar_maturity_date` returns `calendar_maturity_date`\n* Send nothing (default fallback applied) returns `unit=DAYS` and `value` equal to the product's configured `PRODUCT_DEFAULT_MATURITY_DATE_DAYS`\n",
"properties": {
"unit": {
"$ref": "#/components/schemas/MaturityPeriodUnit"
},
"value": {
"$ref": "#/components/schemas/MaturityPeriodValue"
},
"calendar_maturity_date": {
"$ref": "#/components/schemas/CalendarMaturityDate"
}
}
},
"MaturityPeriodUnit": {
"type": "string",
"description": "Time unit for the relative maturity period. It's used together with `value` and cannot coincide with `calendar_maturity_date`.\n\n- `DAYS`: Uses `value` directly. Example: `value=90` → 90 days.\n- `WEEKS`: Multiplies `value` by 7. Example: `value=4` → 28 days.\n- `MONTHS`: Calculates calendar-month with end-of-month (EOM) clamping when the target day does not exist. Example: `2024-01-31` + 1 month = `2024-02-29` (leap year) or `2025-02-28` (non-leap year).\n- `YEARS`: Calculates calendar-year, for example: `2024-02-29` + 1 year = `2025-02-28`. Note that there is no Feb 29 in 2025.\n\nFor `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.\n",
"enum": [
"DAYS",
"WEEKS",
"MONTHS",
"YEARS"
],
"example": "MONTHS"
},
"MaturityPeriodValue": {
"type": "integer",
"description": "Number of time units until maturity. Must be greater than `0`. Mutually exclusive with `calendar_maturity_date`.\n",
"minimum": 1,
"example": 6
},
"CalendarMaturityDate": {
"type": "string",
"format": "date",
"description": "Maturity date. Format is `YYYY-MM-DD`. The date must be a future date.\n\nThis date cannot coincide with `unit`/`value`, sending both in the same request returns a `400` validation error.\n",
"example": "2027-06-15"
},
"MaturityInstructionsOverrideRequest": {
"type": "object",
"description": "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.\n",
"properties": {
"principal": {
"type": "string",
"enum": [
"ROLLOVER",
"PAY"
],
"description": "Specifies how the principal is handled once the deposit matures.",
"example": "ROLLOVER"
},
"interest": {
"type": "string",
"enum": [
"ROLLOVER",
"PAY"
],
"description": "Specifies how the interest is handled once the deposit matures.",
"example": "PAY"
},
"reason": {
"type": "string",
"maxLength": 100,
"description": "Optional audit-trail reason.",
"example": "Customer preference at onboarding"
}
}
},
"RenewalTermOverrideRequest": {
"type": "object",
"description": "Specifies the recurring rollover term, not to be confused with the initial `maturity_period`.\n\nYou must provide either `unit` with `value` or `renewal_calendar_maturity_date`.\n\nA `ROLLOVER` configuration in principal or interest is required.\n\nWhen 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: }`.\n",
"properties": {
"unit": {
"type": "string",
"enum": [
"DAYS",
"WEEKS",
"MONTHS",
"YEARS"
],
"description": "Time unit of the renewal term. Required together with `value` when calendar form is not used.",
"example": "MONTHS"
},
"value": {
"type": "integer",
"minimum": 1,
"description": "Number of units. Required together with `unit` when calendar form is not used.",
"example": 6
},
"renewal_calendar_maturity_date": {
"type": "string",
"format": "date",
"description": "Explicit calendar date (`YYYY-MM-DD`), the date must be a future date, and does not coincide with `unit`+`value`.",
"example": "2027-05-22"
}
}
},
"GracePeriodOverrideRequest": {
"type": "object",
"description": "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.",
"required": [
"waived"
],
"properties": {
"waived": {
"type": "boolean",
"description": "`true` = fully exempt; `false` = penalty active (customize via the fields below)."
},
"duration_days": {
"type": "integer",
"minimum": 0
},
"penalty_interest_days": {
"type": "integer",
"minimum": 0
},
"valid_until": {
"type": "string",
"format": "date-time",
"description": "Schedules the revert of this override via EventBridge. This value must be a future date and follows the ISO 8601 standard."
}
}
},
"EarlyWithdrawalAfterOpeningOverrideRequest": {
"type": "object",
"description": "Override for early withdrawal after account opening.",
"required": [
"waived"
],
"properties": {
"waived": {
"type": "boolean"
},
"applicable_within_days": {
"type": "integer",
"minimum": 0
},
"penalty_interest_days": {
"type": "integer",
"minimum": 0
},
"valid_until": {
"type": "string",
"format": "date-time"
}
}
},
"WithdrawalFeeOverrideRequest": {
"type": "object",
"description": "Withdrawal fee override.",
"required": [
"waived"
],
"properties": {
"waived": {
"type": "boolean"
},
"type": {
"type": "string",
"enum": [
"PERCENTAGE",
"FIXED"
]
},
"value": {
"type": "number",
"minimum": 0,
"exclusiveMinimum": true
},
"valid_until": {
"type": "string",
"format": "date-time"
}
}
},
"TieredInterestForfeitureOverrideRequest": {
"type": "object",
"description": "Tiered interest forfeiture override. Tiers replace the product's tiers when provided.",
"required": [
"waived"
],
"properties": {
"waived": {
"type": "boolean"
},
"tiers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TieredInterestForfeitureTierRequest"
}
},
"valid_until": {
"type": "string",
"format": "date-time"
}
}
},
"TieredInterestForfeitureTierRequest": {
"type": "object",
"required": [
"min_days_held",
"forfeited_interest_days"
],
"properties": {
"min_days_held": {
"type": "integer",
"minimum": 0
},
"max_days_held": {
"type": "integer",
"minimum": 0,
"description": "Optional. Open-ended tier when omitted."
},
"forfeited_interest_days": {
"type": "integer",
"minimum": 0
}
}
},
"SubsequentWithdrawalsOverrideRequest": {
"type": "object",
"description": "Subsequent withdrawals (Regulation D) override.",
"required": [
"waived"
],
"properties": {
"waived": {
"type": "boolean"
},
"applicable_within_days": {
"type": "integer",
"minimum": 1
},
"penalty_interest_days": {
"type": "integer",
"minimum": 1
},
"window_behavior": {
"type": "string",
"enum": [
"ROLLING",
"FIXED"
]
},
"valid_until": {
"type": "string",
"format": "date-time"
}
}
},
"AttachmentOverridesPatchRequest": {
"type": "object",
"description": "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`.\n",
"properties": {
"maturity_instructions": {
"allOf": [
{
"$ref": "#/components/schemas/MaturityInstructionsOverrideRequest"
}
],
"nullable": true
},
"renewal_term": {
"allOf": [
{
"$ref": "#/components/schemas/RenewalTermOverrideRequest"
}
],
"nullable": true
},
"penalties": {
"$ref": "#/components/schemas/PenaltiesPatchRequest"
}
}
},
"PenaltiesPatchRequest": {
"type": "object",
"description": "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.\n",
"properties": {
"reason": {
"type": "string",
"maxLength": 100,
"example": "Update — Q1 2027 VIP retention package"
},
"grace_period": {
"allOf": [
{
"$ref": "#/components/schemas/GracePeriodOverrideRequest"
}
],
"nullable": true
},
"early_withdrawal_after_opening": {
"allOf": [
{
"$ref": "#/components/schemas/EarlyWithdrawalAfterOpeningOverrideRequest"
}
],
"nullable": true
},
"withdrawal_fee": {
"allOf": [
{
"$ref": "#/components/schemas/WithdrawalFeeOverrideRequest"
}
],
"nullable": true
},
"tiered_interest_forfeiture": {
"allOf": [
{
"$ref": "#/components/schemas/TieredInterestForfeitureOverrideRequest"
}
],
"nullable": true
},
"subsequent_withdrawals": {
"allOf": [
{
"$ref": "#/components/schemas/SubsequentWithdrawalsOverrideRequest"
}
],
"nullable": true
}
}
},
"UpdateAccountAttachmentRequest": {
"type": "object",
"required": [
"deposit_configs"
],
"properties": {
"deposit_configs": {
"type": "object",
"description": "At least one of `overrides` or `interest_capitalization_mode` must be provided.\n",
"properties": {
"interest_capitalization_mode": {
"type": "string",
"enum": [
"PAYOUT",
"REINVEST"
],
"nullable": true,
"description": "Defines how capitalized interest is treated.
\n\n* `PAYOUT` (default): The capitalized amount is routed to `payout_account`. If no payout account is configured, the amount remains in the base account.\n* `REINVEST`: the capitalized amount is added to the principal through the interest engine. The updated principal becomes the basis for the next accrual cycle.\n\nThis field applies only to the capitalization flow. The maturity instruction flow always uses `payout_account` regardless of this setting.
\n\nIf the field is not provided, it is absent in the attachment and defaults to `PAYOUT` at runtime.\n",
"example": "REINVEST"
},
"overrides": {
"$ref": "#/components/schemas/AttachmentOverridesPatchRequest"
}
}
}
}
},
"AttachmentOverridesSnapshot": {
"type": "object",
"description": "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` retains the structure provided by the client (calendar form or `unit`+`value`), mirroring the behavior of `maturity_period`.\n",
"properties": {
"maturity_instructions": {
"$ref": "#/components/schemas/MaturityInstructionsOverrideRequest"
},
"renewal_term": {
"$ref": "#/components/schemas/RenewalTermResponse"
},
"penalties": {
"$ref": "#/components/schemas/PenaltiesOverrideSnapshot"
}
}
},
"RenewalTermResponse": {
"type": "object",
"description": "Renewal term applied on each rollover. The platform preserves the client’s original format: `unit`+`value` appears when provided, and `renewal_calendar_maturity_date` is returned as a string when that form is used.\n",
"properties": {
"unit": {
"type": "string",
"enum": [
"DAYS",
"WEEKS",
"MONTHS",
"YEARS"
],
"example": "MONTHS"
},
"value": {
"type": "integer",
"minimum": 1,
"example": 6
},
"renewal_calendar_maturity_date": {
"type": "string",
"format": "date",
"description": "Returned only when the request uses the calendar format. Format = `YYYY-MM-DD`.",
"example": "2027-05-22"
}
}
},
"PenaltiesOverrideSnapshot": {
"type": "object",
"description": "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.\n",
"properties": {
"reason": {
"type": "string",
"example": "Q4 2026 VIP retention package"
},
"grace_period": {
"$ref": "#/components/schemas/GracePeriodOverrideRequest"
},
"early_withdrawal_after_opening": {
"$ref": "#/components/schemas/EarlyWithdrawalAfterOpeningOverrideRequest"
},
"withdrawal_fee": {
"$ref": "#/components/schemas/WithdrawalFeeOverrideRequest"
},
"tiered_interest_forfeiture": {
"$ref": "#/components/schemas/TieredInterestForfeitureOverrideRequest"
},
"subsequent_withdrawals": {
"$ref": "#/components/schemas/SubsequentWithdrawalsOverrideRequest"
}
}
},
"AccountAttachment": {
"type": "object",
"properties": {
"product_type": {
"type": "string",
"description": "Product type.",
"enum": [
"deposit",
"savings-account"
]
},
"product_id": {
"type": "string",
"description": "Product identifier.",
"example": "2c336e9d-d04f-4fd0-8f6e-25808f48d70c"
},
"interest_plan_id": {
"type": "string",
"description": "Interest rate plan ID. This corresponds to the ID you created using the [Create interest plan version](https://developers.pismo.io/pismo-docs/reference/patch-v1-interest-plan)) endpoint.",
"example": "263d509a-d5d0-4b3a-b909-ce1b9174beff"
},
"maturity_period": {
"$ref": "#/components/schemas/MaturityPeriod"
},
"attached_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp that indicates when the attach API call was called.\nThe datetime format follows the ISO 8601 standard `yyyy-mm-ddThh:mm:ss.sssZ`.\n",
"example": "2024-01-23T13:26:25.000Z"
},
"effective_date": {
"type": "string",
"format": "date",
"description": "The effective date of the attachment in `YYYY-MM-DD` format\nThis is the date when the attachment becomes valid. Maturity is calculated from this date.\nFor attachments created in the past, the date defaults to the value of `attached_at`.\n",
"example": "2025-12-01"
},
"fee_model_id": {
"type": "string",
"description": "Fee model identifier, if applicable.",
"example": "fee-model-123"
},
"payout_account": {
"$ref": "#/components/schemas/PayoutAccount"
},
"interest_capitalization_mode": {
"type": "string",
"enum": [
"PAYOUT",
"REINVEST"
],
"description": "Present only when this account attachment explicitly defines `interest_capitalization_mode`. If the field is missing, the effective value is `PAYOUT`, inherited from the program configuration or, if the program does not specify it, from the product’s default settings.\n",
"example": "REINVEST"
},
"overrides": {
"allOf": [
{
"$ref": "#/components/schemas/AttachmentOverridesSnapshot"
}
],
"description": "Optional. Only returned when at least one override is configured for the attachment."
}
}
}
},
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
},
"paths": {
"/v1/deposits/accounts/{accountId}/attachment": {
"patch": {
"tags": [
"Account attachment"
],
"summary": "Update deposit account attachment overrides",
"description": "Partially updates `deposit_configs.overrides` and `deposit_configs.interest_capitalization_mode` on an active deposit account attachment. Each field is processed using three‑state `PATCH` semantics, allowing values to be added, changed, or cleared as part of the update.\n * **Omitted**: Keeps the current value\n * `null`: Removes the override; falls back through the cascade (program → product)\n * **Value**: Replaces the current override with the supplied value\n\n**NOTES**:\n\n* At least one of `deposit_configs.overrides` or `deposit_configs.interest_capitalization_mode` must be provided.\n* The `overrides` envelope, if provided, must contain at least one field. Sending an empty object returns `400 EIBACC0315`.\n* `renewal_term` still requires `ROLLOVER` configured in `maturity_instructions` somewhere in the fallback sequence (`400 EIBACC0310` otherwise).\n\nThis endpoint generates an [Account attachment updated](https://developers.pismo.io/events/docs/deposit-product-account-attachment-updated-1) event.\n",
"operationId": "interest-bearing-v1-deposit-update-account-attachment",
"parameters": [
{
"$ref": "#/components/parameters/accountId"
},
{
"$ref": "#/components/parameters/authorizationTokenHeader"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateAccountAttachmentRequest"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountAttachment"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/ErrorResponse"
}
]
},
"examples": {
"emptyOverridesEnvelope": {
"summary": "deposit_configs.overrides must contain at least one field",
"value": {
"code": "EIBACC0315",
"message": "deposit_configs.overrides must contain at least one field"
}
},
"overrideValidUntilPast": {
"summary": "valid_until must be a future datetime",
"value": {
"code": "EIBACC0308",
"message": "valid_until must be a future datetime"
}
},
"renewalTermRequiresRollover": {
"summary": "renewal_term requires ROLLOVER in maturity_instructions",
"value": {
"code": "EIBACC0310",
"message": "Validation error",
"details": "renewal_term requires ROLLOVER configured in maturity_instructions.principal or maturity_instructions.interest (account/program override or product default)."
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/ErrorResponse"
}
]
},
"examples": {
"attachmentNotFound": {
"summary": "Active deposit attachment not found for this account",
"value": {
"code": "EIBACC0113",
"message": "Product attachment not found"
}
}
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/ErrorResponse"
}
]
},
"examples": {
"attachmentNotActive": {
"summary": "Attachment is not active",
"value": {
"code": "EIBACC0301",
"message": "Product attachment is not active"
}
},
"optimisticLock": {
"summary": "Product attachment was modified concurrently",
"value": {
"code": "EIBACC0314",
"message": "Product attachment was modified concurrently; retry with the latest state"
}
}
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/ErrorResponse"
}
]
},
"examples": {
"internalError": {
"summary": "Internal error",
"value": {
"code": "EIBACC0007",
"message": "Internal error"
}
},
"attachmentOverridesUpdate": {
"summary": "Failed to update attachment overrides",
"value": {
"code": "EIBACC0316",
"message": "Failed to update attachment overrides"
}
}
}
}
}
}
}
}
}
},
"security": [
{
"BearerAuth": []
}
]
}
```