---
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 program attachment overrides
Partially updates `deposit_configs.overrides` and `deposit_configs.interest_capitalization_mode` on an active deposit program attachment. Each field follows three‑state `PATCH` rules, allowing values to be set, changed, or cleared. At the program level, the only supported override inside `overrides` is `renewal_term`.
* **Omitted**: Keeps the current value
* `null`: Removes the override; falls back through the cascade (product)
* **Value**: Replaces the current value
**NOTES**:
* At least one of `deposit_configs.overrides` or `deposit_configs.interest_capitalization_mode` must be provided.
* Sending `penalties` inside `overrides` returns `400 EIBACC0317`
* Sending `maturity_instructions` inside `overrides` results in a `400 EIBACC0318` error. This field cannot be modified at the program level and must be configured on each account attachment instead.
* An empty `overrides` envelope returns `400 EIBACC0315`
* `renewal_term` still requires `ROLLOVER` configured in `maturity_instructions` somewhere in the fallback sequence (`400 EIBACC0310` otherwise)
This endpoint generates a [Program attachment updated](https://developers.pismo.io/events/docs/deposit-product-program-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": "Program attachment",
"description": "Endpoints that manage program 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
},
"programIdPath": {
"description": "Program ID",
"in": "path",
"name": "programId",
"required": true,
"schema": {
"type": "integer"
},
"example": 123
}
},
"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"
}
}
},
"ProgramAttachmentOverridesPatchRequest": {
"type": "object",
"description": "PATCH envelope for program-level `deposit_configs.overrides`.
\n**NOTES**:\n * Only `renewal_term` is valid and uses three-state semantics: omit for no change, `null` to clear the override, or supply a value to replace it\n * `penalties` and `maturity_instructions` are not allowed and produce `400 EIBACC0317` and `EIBACC0318`\n * An empty `overrides` object is rejected with `400 EIBACC0315`\n",
"properties": {
"renewal_term": {
"allOf": [
{
"$ref": "#/components/schemas/RenewalTermOverrideRequest"
}
],
"nullable": true
}
}
},
"UpdateProgramAttachmentRequest": {
"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": "Updates the program-level default capitalization mode. Inherited by all accounts attached to this program unless overridden at account level.\n\nSend `null` to remove the program-level value and revert to the product default.\n",
"example": "PAYOUT"
},
"overrides": {
"$ref": "#/components/schemas/ProgramAttachmentOverridesPatchRequest"
}
}
}
}
},
"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"
}
}
},
"ProgramAttachment": {
"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 vaue 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 program attachment explicitly defines `interest_capitalization_mode`. If the field is missing, the Pismo platform applies `PAYOUT` as the default behavior. All accounts linked to the program inherit this value unless an account‑level configuration provides its own setting.\n",
"example": "PAYOUT"
},
"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/programs/{programId}/attachment": {
"patch": {
"tags": [
"Program attachment"
],
"summary": "Update deposit program attachment overrides",
"description": "Partially updates `deposit_configs.overrides` and `deposit_configs.interest_capitalization_mode` on an active deposit program attachment. Each field follows three‑state `PATCH` rules, allowing values to be set, changed, or cleared. At the program level, the only supported override inside `overrides` is `renewal_term`.\n * **Omitted**: Keeps the current value\n * `null`: Removes the override; falls back through the cascade (product)\n * **Value**: Replaces the current value\n\n**NOTES**:\n* At least one of `deposit_configs.overrides` or `deposit_configs.interest_capitalization_mode` must be provided.\n* Sending `penalties` inside `overrides` returns `400 EIBACC0317`\n* Sending `maturity_instructions` inside `overrides` results in a `400 EIBACC0318` error. This field cannot be modified at the program level and must be configured on each account attachment instead.\n* An empty `overrides` envelope 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 a [Program attachment updated](https://developers.pismo.io/events/docs/deposit-product-program-attachment-updated-1) event.\n",
"operationId": "interest-bearing-v1-deposit-update-program-attachment",
"parameters": [
{
"$ref": "#/components/parameters/programIdPath"
},
{
"$ref": "#/components/parameters/authorizationTokenHeader"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateProgramAttachmentRequest"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProgramAttachment"
}
}
}
},
"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"
}
},
"programLevelPenaltiesNotSupported": {
"summary": "penalties not supported at program-level",
"value": {
"code": "EIBACC0317",
"message": "deposit_configs.overrides.penalties is not supported at program-level; apply per-account instead"
}
},
"programLevelMaturityInstructionsNotSupported": {
"summary": "maturity_instructions not supported at program-level",
"value": {
"code": "EIBACC0318",
"message": "deposit_configs.overrides.maturity_instructions is not supported at program-level; apply per-account instead"
}
},
"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 program",
"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": []
}
]
}
```