---
title: "Update earmark (Pismo account ID)"
method: PATCH
path: "/cash-management/v2/earmarks/{earmarkId}"
tags: ["Earmarking (Pismo account ID)"]
---

# Update earmark (Pismo account ID)

`PATCH /cash-management/v2/earmarks/{earmarkId}`

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 a Pismo 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-cash-management-v2-earmarks-earmarkid-cancel), instead.

## Path parameters

- `earmarkId` string, required

## Request body

- UpdateEarmarkRequestV2
  - `internal_operation` InternalOperation2, required — Data used in transactions executed internally during the request.
    - `tracking_id` string, required — Customer created tracking ID. Must consist of alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and colons (:), with a length from 1 to 128. The Pismo platform uses this field to implement idempotency and prevent duplicates.
    - `business_date` string, date — Specifying a `business_date` value impacts the account balance history.<br> <b>Notes</b>: - The business date is in ISO 8601 format. - The business date allows users to designate the balance history cycle in which a payment is posted. - You can specify a `business_date` within the current working day or up to one working day before or after.
    - `validation_rules` ValidationRules — Rules that determine which validations are executed during the payment process.<br> Available validation rules: - `LEDGER` - `ACCOUNT_STATUS` - `FLEX_CONTROLS` - `RATES`<br> `force` is only supported for `LEDGER`. `override` is supported for `ACCOUNT_STATUS`, `FLEX_CONTROLS`, and `RATES`.
    - `metadata` CancelEarmarkMetadata — Key-value pairs containing data intended for storage in the Pismo system.<br> **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).
  - `description` string — Earmark description
  - `update_type` 'INCREASE' | 'DECREASE' | 'SET_AMOUNT' — Operation type. Default is `SET_AMOUNT`.
  - `amount` number, float — New amount to be set when `update_type` is `SET_AMOUNT` or delta. Value cannot be zero.<br> `minimum: 0.01` `maximum: 18446744073709551617`
  - `release_datetime` string, date-time — RFC 3339 date/time for earmark release. Used to schedule a cash-out (usually a payment) at the specified release date and time. At `release_datetime`, an automatic process releases the earmarked funds and settles the cash-out. If no `release_datetime` is set, the earmarked amount is held indefinitely until the customer cancels the earmark.
  - `force_post` boolean — 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: - `CREDIT ONLY`: No force debit allowed - `ANY`: No force allowed - `MANUAL`: No force allowed

## Response `200`

OK

- EarmarkResponse
  - `earmark_id` string — 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).
  - `account_id` integer — Account ID generated by [Create Corporate Account](https://developers.pismo.io/pismo-docs/reference/post-account).<br> `minimum: 1` `maximum: 4294967295`
  - `external_account_id` string — External ID of the account on which the earmark is created. Should be the same `external_account_id` that was used to log in. Should be the same `external_account_id` used in [Create Corporate Account](https://developers.pismo.io/pismo-docs/reference/post-account).
  - `description` string — Earmark description
  - `amount` number, float — Earmark amount<br> `minimum: 0.01` `maximum: 18446744073709551617`
  - `balance` number — 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.<br> `minimum: 0` `maximum: 18446744073709551617`
  - `release_datetime` string, date-time — RFC 3339 date/time for earmark release. Used to schedule a cash-out (usually a payment) at the specified release date and time. At `release_datetime`, an automatic process releases the earmarked funds and settles the cash-out. If no `release_datetime` is set, the earmarked amount is held indefinitely until the customer cancels the earmark.
  - `internal_operations` InternalOperation[] — List of internal operations performed to hold or release the earmark funds.
    - `tracking_id` string, required — Customer created tracking ID. Must consist of alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and colons (:), with a length from 1 to 128. The Pismo platform uses this field to implement idempotency and prevent duplicates.
    - `business_date` string, date — Specifying a `business_date` value impacts the account balance history.<br> <b>Notes</b>: - The business date is in ISO 8601 format. - The business date allows users to designate the balance history cycle in which a payment is posted. - You can specify a `business_date` within the current working day or up to one working day before or after.
    - `type` 'HOLD_FUNDS' | 'RELEASE_FUNDS' | 'INCREASE' | 'DECREASE' — Internal operation type.<br> `minLength: 1` `maxLength: 13`
    - `processing_code` string — Processing code for the debit transaction. If `split_transaction` is `false` (the default), each installment payment is recorded as one debit transaction equal to the installment amount minus the discount, and `processing_code` is the processing code for that transaction. If `split_transaction` is `true`, each installment payment is recorded as two transactions: a debit transaction for the installment amount and a credit transaction for the discount. In this case, `processing_code` is the processsing code for the debit transaction, and `second_processing_code` is the processing code for the credit transaction.
    - `amount` number — Internal operation amount<br> `minimum: 0` `maximum: 18446744073709551617`
    - `validation_rules` ValidationRules — Rules that determine which validations are executed during the payment process.<br> Available validation rules: - `LEDGER` - `ACCOUNT_STATUS` - `FLEX_CONTROLS` - `RATES`<br> `force` is only supported for `LEDGER`. `override` is supported for `ACCOUNT_STATUS`, `FLEX_CONTROLS`, and `RATES`.
    - `created_at` string, datetime — Internal operation creation time. Format = yyyy-mm-dd:hr:mm:ss.
    - `metadata` InternalOperationMetadata — Key-value pairs containing data intended for storage in the Pismo system.<br> **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).

## Other responses

- `400` — A Bad Request validation error.
- `401` — Unauthorized operation.
- `403` — The request has been lost
- `404` — Not Found
- `409` — Conflict
- `500` — Internal server error

---

[API](https://skmtc.net/pismo/apis/platform-authentication.md) · [All operations](https://skmtc.net/pismo/apis/platform-authentication/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pismo/platform-authentication/versions/935b62e16de4/schema)