---
title: "Update a Payee"
method: PATCH
path: "/payables/payer_accounts/{payer_id}/payees/{id}"
tags: ["Payees"]
---

# Update a Payee

`PATCH /payables/payer_accounts/{payer_id}/payees/{id}`

## Request

- Base URL: `https://api.justifi.ai/v1`
- URL: `https://api.justifi.ai/v1/payables/payer_accounts/{payer_id}/payees/{id}`
- Auth: none declared. Required headers: `Authorization`
- TypeScript: <https://skmtc.dev/justifi/apis/justifi-api-documentation/docs/payables/payer_accounts/:payer_id/payees/:id/patch.ts> (a function with typed inputs; its response is checked against the schema)

Update mutable fields on a payee. Only the fields you send are changed, except `address`, which is
replaced whole rather than merged field by field.

`entity_type` and `tax_id` are not updatable. They are the taxpayer the payee is filed against and
are fixed at create; a name or address change does not make a payee a different taxpayer, and a
change to either of those two does.

## Path parameters

- `payer_id` string, required
- `id` string, required

## Headers

- `Authorization` string, required

## Request body

- object
  - `name` string: the payee's legal name
  - `address` object: replaces the whole address. Partial addresses are not merged.
    - `line1` string: street address
    - `line2` string, nullable: suite, unit or floor, when there is one
    - `city` string
    - `state` string: two-letter state or territory code, uppercase. Not normalized — `mn` is rejected rather than corrected.
    - `postal_code` string: ZIP or ZIP+4
    - `country` 'USA': ISO 3166-1 alpha-3 country code, matching the rest of JustiFi. `USA` is the only value Payables accepts — it pays by US domestic ACH and files US tax forms — and it is what a payee gets when the field is omitted.
  - `email` string, email
  - `metadata` object

## Response `200`

Payee was updated successfully

- object: the standard JustiFi response envelope for a single record
  - `id` string, required: the object id, also found in the data object
  - `type` string, required: the object type
  - `data` object, required: A payee is a party that receives Payables payments. Payees are standalone: they can exist and be paid without being tied to a business. `business_id` reports a link to a JustiFi business where there is one, and is null by default.
    - `id` string: unique payee id
    - `type` string: the object type, matching the enclosing envelope's `type`
    - `payer_account_id` string: the id of the payer account this payee is scoped to
    - `name` string: the payee's legal name. Required on create.
    - `entity_type` 'c_corporation' | 's_corporation' | 'partnership' | 'limited_liability_company' | 'sole_proprietorship': the payee's IRS entity classification. Required on create, with no default — it decides both the tax form filed for the payee and, for `sole_proprietorship`, how the ACH credit to them is classified. Immutable — with `tax_id` it is the taxpayer this payee is filed against. The set is open and may grow; unknown values should be treated as a business entity.
    - `email` string, email, nullable: contact email for the payee, when provided
    - `tax_id_last4` string: the last four digits of the payee's taxpayer identification number — an EIN, or an SSN where the payee is a `sole_proprietorship`. The number itself is required on create and never returned — it is stored encrypted, and this is what reads back. Immutable, on the same terms as `entity_type`.
    - `address` object: the payee's address. Required on create.
      - `line1` string: street address
      - `line2` string, nullable: suite, unit or floor, when there is one
      - `city` string
      - `state` string: two-letter state or territory code, uppercase. Not normalized — `mn` is rejected rather than corrected.
      - `postal_code` string: ZIP or ZIP+4
      - `country` 'USA': ISO 3166-1 alpha-3 country code, matching the rest of JustiFi. `USA` is the only value Payables accepts — it pays by US domestic ACH and files US tax forms — and it is what a payee gets when the field is omitted.
    - `receiving_bank_account_id` string, nullable: pointer to the payee's active receiving bank account (denormalized for lookup, like capital's `accounts.payout_account_id`). In this version a payee has a single active account. Null until one is registered.
    - `business_id` string, nullable: the business this payee belongs to, where JustiFi has linked one. Null for standalone payees, and a payee is created and paid without one.
    - `status` 'pending' | 'active' | 'disabled' | 'archived': the payee's status. `pending` — created but not cleared for payments; `active` — able to receive payments, and the only state a payment can be scheduled or paid out under; `disabled` — was active previously and can no longer be paid; `archived` — was active previously and can never be paid again. A payment whose payee credit is already held is not paid out while the payee is not `active`. It stays held until the payee is active again, rather than failing. **Payables disables a payee when its bank says the account cannot be paid.** Either the bank returned a credit for a reason a retry will not change — the account is closed, frozen, not a transaction account, or does not exist — or it sent a notification of change we cannot act on, because it named no corrected numbers or corrects something Payables does not hold. Both mean the next payment would go to an account the bank has already refused. A correction about the entry rather than the account — the payee's name, the entry description — changes nothing. **Registering a corrected receiving bank account returns the payee to `active`**, and any payment held for it pays out on the next cycle. Until then those payments wait rather than failing, which is what stops a queue of payments following the first one into a closed account.
    - `metadata` object: any useful information you'd like to store alongside this payee
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `page_info` unknown, required

## Other responses

- `401`: The access token is missing, expired, or invalid.
- `403`: The credentials are valid but not permitted to access this resource.
- `404`: No resource exists for the given id (within the scoped payer account).
- `422`: The request was well-formed and passed field validation, but a business rule rejected it — for example a payer funding account that is not `verified`, or a payee with no receiving bank account to credit. Field-level validation failures return `400`, not this. `error.details` carries per-attribute messages where the rule is attributable to one.
- `429`: The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header.

---

[API](https://skmtc.dev/justifi/apis/justifi-api-documentation.md) - [All operations](https://skmtc.dev/justifi/apis/justifi-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/justifi/apis/justifi-api-documentation/revisions/dd9f3fed7e46?raw)