---
updatedAt: 2026-04-20T19:56:08.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 earmark
Update an earmark balance.
This endpoint generates the following events:
- [Platform authorization created](https://developers.pismo.io/events/docs/platform-authorization-platform-authorization-1)
- [Account balance changed](https://developers.pismo.io/events/docs/account-balances-balance-change-1)
- [Account balance changed (Availables)](https://developers.pismo.io/events/docs/availables-change-available-1)
- [Transaction created](https://developers.pismo.io/events/docs/transaction-creation-1)
- [Earmark created, updated, or canceled](https://developers.pismo.io/events/docs/corporate-earmark-1) with `UPDATED` action.
**NOTES**:
- This endpoint requires an account token - an access token encoded with an external account ID. Tokens can expire quickly, which can result in a **401 Unauthorized** message.
- To find the correct reason IDs, refer to the [List account status reasons](https://developers.pismo.io/pismo-docs/reference/get-accounts-v1-accounts-status-reasons) endpoint.
- The maximum number of internal operation inputs (updates that change the earmark amount) allowed is 2,000. Update requests that exceed this limit return bad request errors.
- An earmark balance cannot be reduced to zero as a result of this operation. If successfully executing the request would result in a zero balance, the request fails and a bad request error is returned. If you want to reduce the balance to zero, you must use [Cancel earmark](https://developers.pismo.io/pismo-docs/reference/post-corporate-v2-earmarks-earmarkid-cancel), instead.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "Banking - Transaction banking",
"version": "0.9.0",
"description": "Transaction banking API",
"contact": {
"name": "API Support",
"url": "https://developers.pismo.io/support/"
},
"license": {
"name": "Copyright Pismo"
}
},
"servers": [
{
"url": "https://sandbox.pismolabs.io",
"description": "Sandbox API server for testing"
}
],
"security": [
{
"BearerAuth": []
}
],
"tags": [
{
"name": "Earmarking (external accounts)",
"description": "Earmarking endpoints supporting external accounts"
}
],
"components": {
"parameters": {
"EarmarkIdPath": {
"name": "earmarkId",
"in": "path",
"description": "Earmark ID generated by [Create earmark](https://developers.pismo.io/pismo-docs/reference/post-corporate-v2-earmarks).",
"schema": {
"type": "string"
},
"required": true,
"example": "1234"
}
},
"schemas": {
"AccountID3": {
"type": "integer",
"format": "int64",
"description": "Account ID generated by [Create Corporate Account](https://developers.pismo.io/pismo-docs/reference/post-account).
\n`minimum: 1`\n`maximum: 4294967295`\n",
"example": 102701621
},
"BusinessDate": {
"type": "string",
"format": "date",
"description": "Specifying a `business_date` value impacts the account balance history.
\nNotes:\n - The business date is in ISO 8601 format.\n - The business date allows users to designate the balance history cycle in which a payment is posted.\n - You can specify a `business_date` within the current working day or up to one working day before or after.\n",
"example": "2023-03-09"
},
"CancelEarmarkMetadata": {
"type": "object",
"description": "Key-value pairs containing data intended for storage in the Pismo system.
\n\n**Note**: This field must not be used to send Personally Identifiable Information (PII), Payment Card Industry (PCI) data, or any sensitive/regulated information. Metadata fields are intended for operational, non-sensitive data only. For sensitive data, use the specific parameters designed for that purpose. For more information, refer to [Get started with Pismo APIs](https://developers.pismo.io/pismo-docs/reference/get-started-with-pismo-apis).\n"
},
"EarmarkAmount": {
"type": "number",
"format": "float",
"description": "Earmark amount
\n`minimum: 0.01`\n`maximum: 18446744073709551617`\n",
"minimum": 0.01,
"maximum": 18446744073709552000,
"example": 50
},
"EarmarkBalance": {
"type": "number",
"description": "Earmark balance. Initially equal to the earmarked amount and decreases as the reserved funds are used up or decreased in a decrease operation. It can also increase if an increase operation is performed.
\n`minimum: 0`\n`maximum: 18446744073709551617`\n",
"minimum": 0,
"maximum": 18446744073709552000,
"example": 123.45
},
"EarmarkDescription": {
"type": "string",
"description": "Earmark description",
"minLength": 1,
"maxLength": 40
},
"EarmarkForcePost": {
"type": "boolean",
"description": "If the account has any reason-based force debit payment restrictions, and the force earmark creation violates any of those restrictions, it fails. The reasons that restrict force debit operations are:\n - `CREDIT ONLY`: No force debit allowed\n - `ANY`: No force allowed\n - `MANUAL`: No force allowed\n"
},
"EarmarkIdReturned": {
"type": "string",
"description": "Earmark ID. Used as the primary key for query and update operations. It has the same value as the tracking ID, if one is provided. Generated by [Create Earmark](https://developers.pismo.io/pismo-docs/reference/post-corporate-v2-earmarks).",
"example": "da85b309-a7f7-4316-b2ad-f069f0838058"
},
"EarmarkReleaseDatetime": {
"type": "string",
"description": "RFC 3339 date/time for earmark release.\nUsed to schedule a cash-out (usually a payment) at the specified release date and time.\nAt `release_datetime`, an automatic process releases the earmarked funds and settles the cash-out.\nIf no `release_datetime` is set, the earmarked amount is held indefinitely until the customer cancels the earmark.\n",
"minLength": 20,
"maxLength": 30,
"example": "2022-02-10T15:00:00Z",
"format": "date-time"
},
"EarmarkResponse": {
"type": "object",
"properties": {
"earmark_id": {
"$ref": "#/components/schemas/EarmarkIdReturned"
},
"account_id": {
"$ref": "#/components/schemas/AccountID3"
},
"external_account_id": {
"$ref": "#/components/schemas/ExternalAccountIdForEarmark"
},
"description": {
"$ref": "#/components/schemas/EarmarkDescription"
},
"amount": {
"$ref": "#/components/schemas/EarmarkAmount"
},
"balance": {
"$ref": "#/components/schemas/EarmarkBalance"
},
"release_datetime": {
"$ref": "#/components/schemas/EarmarkReleaseDatetime"
},
"internal_operations": {
"$ref": "#/components/schemas/InternalOperations"
}
}
},
"EarmarkUpdateAmount": {
"type": "number",
"format": "float",
"description": "New amount to be set when `update_type` is `SET_AMOUNT` or delta. Value cannot be zero.
\n`minimum: 0.01`\n`maximum: 18446744073709551617`\n",
"minimum": 0.01,
"maximum": 18446744073709552000,
"example": 1000.53
},
"EarmarkUpdateType": {
"type": "string",
"enum": [
"INCREASE",
"DECREASE",
"SET_AMOUNT"
],
"description": "Operation type. Default is `SET_AMOUNT`.",
"example": "INCREASE",
"default": "SET_AMOUNT"
},
"ErrorCode": {
"description": "Error code\n`minLength: 1`\n`maxLength: 12`\n",
"type": "string",
"minLength": 1,
"maxLength": 12,
"example": "WPMT0017"
},
"ErrorMessage": {
"description": "Error message\n`minLength: 1`\n`maxLength: 1000`\n",
"type": "string",
"minLength": 1,
"maxLength": 1000,
"example": "Invalid JSON payload received: Error unmarshalling request"
},
"ErrorResponse": {
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/ErrorCode"
},
"message": {
"$ref": "#/components/schemas/ErrorMessage"
}
}
},
"ExternalAccountIdForEarmark": {
"type": "string",
"description": "External ID of the account on which the earmark is created.\nShould be the same `external_account_id` that was used to log in.\nShould be the same `external_account_id` used in [Create Corporate Account](https://developers.pismo.io/pismo-docs/reference/post-account).\n",
"maxLength": 60,
"pattern": "^[a-zA-Z0-9-]+$",
"example": "b993ba96-b3e8-4ef7-9cf7-7eee5ddafdab"
},
"Force": {
"type": "boolean",
"description": "Whether a payment validation rule should be executed in a forced state (`true`) or not (`false`).
\nAllowed for `LEDGER` validation rule.\n",
"example": false
},
"InternalOperation": {
"type": "object",
"description": "Internal operation performed to hold or release funds",
"properties": {
"tracking_id": {
"$ref": "#/components/schemas/TrackingID"
},
"business_date": {
"$ref": "#/components/schemas/BusinessDate"
},
"type": {
"$ref": "#/components/schemas/InternalOperationType"
},
"processing_code": {
"$ref": "#/components/schemas/ProcessingCode"
},
"amount": {
"$ref": "#/components/schemas/InternalOperationAmount"
},
"validation_rules": {
"$ref": "#/components/schemas/ValidationRules"
},
"created_at": {
"$ref": "#/components/schemas/InternalOperationCreatedAt"
},
"metadata": {
"$ref": "#/components/schemas/InternalOperationMetadata"
}
},
"required": [
"tracking_id"
]
},
"InternalOperation2": {
"type": "object",
"description": "Data used in transactions executed internally during the request.",
"properties": {
"tracking_id": {
"$ref": "#/components/schemas/TrackingID"
},
"business_date": {
"$ref": "#/components/schemas/BusinessDate"
},
"validation_rules": {
"$ref": "#/components/schemas/ValidationRules"
},
"metadata": {
"$ref": "#/components/schemas/CancelEarmarkMetadata"
}
},
"required": [
"tracking_id"
]
},
"InternalOperationAmount": {
"type": "number",
"description": "Internal operation amount
\n`minimum: 0`\n`maximum: 18446744073709551617`\n",
"minimum": 0,
"maximum": 18446744073709552000,
"example": 50
},
"InternalOperationCreatedAt": {
"type": "string",
"format": "datetime",
"description": "Internal operation creation time. Format = yyyy-mm-dd:hr:mm:ss.\n",
"example": "2022-02-10T15:00:00Z"
},
"InternalOperationMetadata": {
"type": "object",
"description": "Key-value pairs containing data intended for storage in the Pismo system.
\n\n**Note**: This field must not be used to send Personally Identifiable Information (PII), Payment Card Industry (PCI) data, or any sensitive/regulated information. Metadata fields are intended for operational, non-sensitive data only. For sensitive data, use the specific parameters designed for that purpose. For more information, refer to [Get started with Pismo APIs](https://developers.pismo.io/pismo-docs/reference/get-started-with-pismo-apis).\n"
},
"InternalOperations": {
"type": "array",
"description": "List of internal operations performed to hold or release the earmark funds.",
"items": {
"$ref": "#/components/schemas/InternalOperation"
}
},
"InternalOperationType": {
"type": "string",
"description": "Internal operation type.
\n`minLength: 1`\n`maxLength: 13`\n",
"enum": [
"HOLD_FUNDS",
"RELEASE_FUNDS",
"INCREASE",
"DECREASE"
],
"example": "HOLD_FUNDS"
},
"Override": {
"type": "boolean",
"description": "Whether to override the validation rule in the payment process (`true`) or not (`false`).
\nAllowed for `ACCOUNT_STATUS`, `FLEX_CONTROLS`, and `RATES` validation rules.\n",
"example": false
},
"ProcessingCode": {
"type": "string",
"description": "Processing code used to create the underlying transaction. Each internal operation type uses a default processing code.
\n`minLength: 1`\n`maxLength: 6`\n",
"minLength": 1,
"maxLength": 6,
"example": "219248"
},
"TrackingID": {
"type": "string",
"description": "A unique payment tracking number provided by the client. If an existing `tracking_id` already exists in the system, the API returns a `409` error.\n\nThis field is:\n - Unique within the Organization.\n - Immutable — It can't be updated.\n - Not recyclable — You can't reuse a `tracking_id`.\n",
"minLength": 1,
"maxLength": 43,
"example": "0a50c88a-ade8-4bcc-a639-9a0b0f11e244"
},
"UpdateEarmarkRequestV2": {
"type": "object",
"properties": {
"internal_operation": {
"$ref": "#/components/schemas/InternalOperation2"
},
"description": {
"$ref": "#/components/schemas/EarmarkDescription"
},
"update_type": {
"$ref": "#/components/schemas/EarmarkUpdateType"
},
"amount": {
"$ref": "#/components/schemas/EarmarkUpdateAmount"
},
"release_datetime": {
"$ref": "#/components/schemas/EarmarkReleaseDatetime"
},
"force_post": {
"$ref": "#/components/schemas/EarmarkForcePost"
}
},
"required": [
"internal_operation"
]
},
"ValidationRule": {
"title": "ValidationRule",
"type": "object",
"properties": {
"override": {
"$ref": "#/components/schemas/Override"
},
"force": {
"$ref": "#/components/schemas/Force"
}
}
},
"ValidationRules": {
"title": "ValidationRules",
"type": "object",
"description": "Rules that determine which validations are executed during the payment process.
\nAvailable validation rules:\n - `LEDGER`\n - `ACCOUNT_STATUS`\n - `FLEX_CONTROLS`\n - `RATES`
\n\n`force` is only supported for `LEDGER`. `override` is supported for `ACCOUNT_STATUS`, `FLEX_CONTROLS`, and `RATES`.\n",
"additionalProperties": {
"$ref": "#/components/schemas/ValidationRule"
},
"example": {
"ACCOUNT_STATUS": {
"override": false
},
"LEDGER": {
"force": false
},
"FLEX_CONTROLS": {
"override": true
},
"RATES": {
"override": true
}
}
}
},
"responses": {
"403Forbidden": {
"description": "The request has been lost"
},
"404NotFound": {
"description": "The specified resource was not found"
},
"500InternalServer": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Generic internal error": {
"value": {
"code": "ECMN9999",
"message": "Internal error"
}
}
}
}
}
}
},
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
},
"paths": {
"/corporate/v2/earmarks/{earmarkId}": {
"patch": {
"summary": "Update earmark",
"description": "Update an earmark balance.\n\nThis endpoint generates the following events:\n- [Platform authorization created](https://developers.pismo.io/events/docs/platform-authorization-platform-authorization-1)\n- [Account balance changed](https://developers.pismo.io/events/docs/account-balances-balance-change-1)\n- [Account balance changed (Availables)](https://developers.pismo.io/events/docs/availables-change-available-1)\n- [Transaction created](https://developers.pismo.io/events/docs/transaction-creation-1)\n- [Earmark created, updated, or canceled](https://developers.pismo.io/events/docs/corporate-earmark-1) with `UPDATED` action.\n\n**NOTES**:\n- This endpoint requires an account token - an access token encoded with an external account ID. Tokens can expire quickly, which can result in a **401 Unauthorized** message.\n- To find the correct reason IDs, refer to the [List account status reasons](https://developers.pismo.io/pismo-docs/reference/get-accounts-v1-accounts-status-reasons) endpoint.\n- The maximum number of internal operation inputs (updates that change the earmark amount) allowed is 2,000. Update requests that exceed this limit return bad request errors.\n- An earmark balance cannot be reduced to zero as a result of this operation. If successfully executing the request would result in a zero balance, the request fails and a bad request error is returned. If you want to reduce the balance to zero, you must use [Cancel earmark](https://developers.pismo.io/pismo-docs/reference/post-corporate-v2-earmarks-earmarkid-cancel), instead.\n",
"operationId": "patch-corporate-v2-earmarks-earmarkid",
"tags": [
"Earmarking (external accounts)"
],
"parameters": [
{
"$ref": "#/components/parameters/EarmarkIdPath"
}
],
"requestBody": {
"description": "Request body",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateEarmarkRequestV2"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EarmarkResponse"
},
"examples": {
"Earmark updated": {
"value": {
"earmark_id": "da85b309-a7f7-4316-b2ad-f069f0838058",
"account_id": 102701621,
"description": "string",
"amount": 20,
"balance": 20,
"release_datetime": "2022-02-10T15:00:00.000Z",
"internal_operations": [
{
"type": "HOLD_FUNDS",
"tracking_id": "10027506-171f-b1e1-8412-67f5f5145a3b",
"business_date": "2022-02-10",
"processing_code": "219248",
"amount": 10,
"created_at": "2022-02-10T15:00:00.000Z"
},
{
"type": "INCREASE",
"tracking_id": "77260e09-2839-4b9e-a663-4aee4cf1568f",
"business_date": "2023-03-09",
"processing_code": "219248",
"amount": 10,
"created_at": "2022-02-10T15:01:00.000Z"
}
]
}
}
}
}
}
},
"400": {
"description": "A Bad Request validation error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Operations blocked for account": {
"description": "This error occurs when there's an operations block for this account",
"value": {
"code": "WOBK0007",
"message": "Operations blocked for account"
}
},
"Invalid JSON payload": {
"value": {
"code": "WEAM0014",
"message": "Invalid JSON payload received: Error unmarshalling request"
}
},
"amount must be 100,000,000,000,000,000 or less": {
"value": {
"code": "WEAM0015",
"message": "amount must be 100,000,000,000,000,000 or less"
}
},
"amount must be greater than 0": {
"value": {
"code": "WEAM0015",
"message": "amount must be greater than 0"
}
},
"description must be a maximum of 40 characters in length": {
"value": {
"code": "WEAM0015",
"message": "description must be a maximum of 40 characters in length"
}
},
"tracking_id is a required field": {
"value": {
"code": "WEAM0015",
"message": "tracking_id is a required field"
}
},
"release_datetime cannot be in the past": {
"value": {
"code": "WEAM0015",
"message": "release_datetime cannot be in the past"
}
},
"amount has invalid decimal places for currency": {
"value": {
"code": "WEAM0015",
"message": "The number of decimal places is not compatible with the specified currency"
}
},
"Invalid header account": {
"value": {
"code": "WEAM0016",
"message": "Invalid header account"
}
},
"Orgs operation not found or parameterized": {
"value": {
"code": "WEAM0017",
"message": "Orgs operations not found or parameters are incorrect or invalid"
}
},
"operation already made": {
"value": {
"code": "WEAM0018",
"message": "operation already made"
}
},
"Invalid account program type": {
"value": {
"code": "WEAM0019",
"message": "The account's program type is invalid"
}
},
"Account closed": {
"value": {
"code": "WEAM0026",
"message": "Action not permitted on a closed account"
}
},
"Force earmark decrease not allowed": {
"value": {
"code": "WEAM0027",
"message": "You cannot force a release that results in the decrease of the earmark balance"
}
},
"Maximum internal operations reached": {
"value": {
"code": "WEAM0030",
"message": "Maximum number of internal operations reached [limit]"
}
},
"Balance reduced to zero": {
"value": {
"code": "WEAM0031",
"message": "Balance cannot be reduced to zero as a result of this operation"
}
},
"Misconfigured administrative division": {
"value": {
"code": "WEAM0036",
"message": "Administrative division is misconfigured"
}
},
"Balance unchanged": {
"value": {
"code": "WEAM0038",
"message": "Earmark balance is unchanged"
}
},
"Invalid business date for the current business day cycle": {
"value": {
"code": "WEAM0039",
"message": "Invalid business date for the current business day cycle"
}
},
"Business date before account creation date": {
"value": {
"code": "WEAM0040",
"message": "The payment date cannot be earlier than the account creation date"
}
},
"Business date before account migration date": {
"summary": "Business date before account migration date",
"value": {
"code": "WEAM0047",
"message": "The payment date cannot be earlier than the account migration date"
}
},
"Business date cannot be earlier than the earmark creation date": {
"value": {
"code": "WEAM0041",
"message": "Business date cannot be earlier than the earmark creation date"
}
},
"Future dated earmark operations are not allowed": {
"value": {
"code": "WEAM0042",
"message": "Future dated earmark operations are not allowed"
}
},
"Cannot post transaction on holidays": {
"value": {
"code": "WEAM0043",
"message": "Cannot post transaction on holidays"
}
},
"Cannot post transaction on weekends": {
"value": {
"code": "WEAM0044",
"message": "Cannot post transaction on weekends"
}
},
"Back business dating disabled": {
"value": {
"code": "WEAM0045",
"message": "Back business dating is disabled"
}
},
"Invalid account currency code": {
"value": {
"code": "WEAM0046",
"message": "Invalid account currency code: 999"
}
}
}
}
}
},
"401": {
"description": "Unauthorized operation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Account cannot be debited": {
"description": "This error occurs when the account cannot be debited.",
"value": {
"code": "WEAM0023",
"message": "The account cannot be debited. Debit function is not active"
}
},
"Account cannot be credited": {
"description": "This error occurs when the account cannot be credited.",
"value": {
"code": "WEAM0024",
"message": "The account cannot be credited. Credit function is not active"
}
}
}
}
}
},
"403": {
"$ref": "#/components/responses/403Forbidden"
},
"404": {
"$ref": "#/components/responses/404NotFound"
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Tracking ID already in use": {
"description": "This error occurs when the client sends a duplicate tracking ID.",
"value": {
"code": "WEAM0025",
"message": "Tracking ID is already in use",
"data": {
"earmark_id": "da85b309-a7f7-4316-b2ad-f069f0838058",
"account_id": 102701621,
"description": "string",
"amount": 20,
"balance": 20,
"release_datetime": "2022-02-10T15:00:00.000Z",
"internal_operations": [
{
"type": "HOLD_FUNDS",
"tracking_id": "10027506-171f-b1e1-8412-67f5f5145a3b",
"processing_code": "219248",
"amount": 10,
"created_at": "2022-02-10T15:00:00.000Z"
},
{
"type": "INCREASE",
"tracking_id": "77260e09-2839-4b9e-a663-4aee4cf1568f",
"processing_code": "219248",
"amount": 10,
"created_at": "2022-02-10T15:01:00.000Z"
}
]
}
}
},
"Tracking ID already in use by another earmark or account": {
"description": "This error occurs when the client sends a duplicate tracking ID that is either already in use by another account, or by the same account with a different earmark ID than the one used in the original payment.",
"value": {
"code": "WEAM0034",
"message": "Tracking id is already in use"
}
}
}
}
}
},
"500": {
"$ref": "#/components/responses/500InternalServer"
}
}
}
}
}
}
```