--- title: "Archive a Payee" method: DELETE path: "/payables/payer_accounts/{payer_id}/payees/{id}" tags: ["Payees"] --- # Archive a Payee `DELETE /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: (a function with typed inputs; its response is checked against the schema) Archive a payee. Archiving is a soft delete: the payee's record and payment history are retained, but the payee can no longer be paid. Returns the archived payee. **Archiving reaches the payments already in flight, up to a point.** A credit already submitted to the network completes — nothing recalls an ACH entry. A payment still holding the payer's funds is not paid out: it stays held rather than failing, and would resume only if the payee were active again, which archiving rules out. Archiving is also always allowed, whatever the payer account's status. Archiving is one-way — there is no unarchive operation, and `status` is not writable through `UpdatePayee`. To pay a party again after archiving it, create a new payee. ## Path parameters - `payer_id` string, required - `id` string, required ## Headers - `Authorization` string, required ## Response `200` Payee was archived 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). - `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)