---
title: "Actualizar metadata de un Beneficiary"
method: PATCH
path: "/payouts-beneficiary/{id_beneficiary}/metadata"
tags: ["Beneficiaries"]
---

# Actualizar metadata de un Beneficiary

`PATCH /payouts-beneficiary/{id_beneficiary}/metadata`

## Request

- Base URL: `https://api.trytoku.com`
- URL: `https://api.trytoku.com/payouts-beneficiary/{id_beneficiary}/metadata`
- Auth: API key in header `x-api-key`

Fusiona claves en la `metadata` de un Beneficiary sin reemplazarla por completo.

Las claves enviadas se escriben sobre la metadata existente: las que ya estaban con otro valor se sobrescriben y las que no vienen en la solicitud se conservan. No hay forma de borrar una clave por esta vía.

El campo `metadata` es obligatorio. Cada clave se escribe como una ruta anidada, así que una clave vacía, que empiece con `$` o que contenga un punto se rechaza con `422`.

**Límite de tasa:** 1000 solicitudes por hora. Al superarlo, la API responde `429`. Ver [Límites de tasa](/reference/limites-de-tasa).

## Path parameters

- `id_beneficiary` string, uuid, required: Identificador del Beneficiary.

## Request body

- PatchBeneficiaryMetadataPayload: Additive metadata update: the provided keys are merged into the beneficiary's existing metadata (top-level), overwriting collisions and preserving the rest. ``metadata`` is required — a missing field is a client error, not an empty patch. Keys are written as nested ``metadata.<key>`` paths for an atomic per-key merge, so a key must be non-empty and may not contain ``.`` or a NUL character or start with ``$`` (those are MongoDB path/operator syntax and would otherwise fail the update at write time).
  - `metadata` object, required: Claves que se fusionan en la metadata del Beneficiary.

## Response `200`

El Beneficiary con su metadata ya fusionada.

- BeneficiaryResponse: Un Beneficiary: la persona o empresa que recibe un pago de la Organization.
  - `country_code` string, required: País del Beneficiary, en formato ISO.
  - `created_at` string, date-time, required: Momento en que se creó el Beneficiary.
  - `created_by` string, nullable: Correo del usuario de la webapp que creó el Beneficiary. Vacío cuando la carga vino de una integración por API key.
  - `email` string, nullable: Correo de contacto del Beneficiary.
  - `external_id` string, required: Identificador del Beneficiary en el sistema de origen.
  - `id_beneficiary` string, required: Identificador del Beneficiary.
  - `id_beneficiary_batch` string, required: Identificador del lote de carga en que se creó el Beneficiary.
  - `identity_document` IdentityDocument
    - `number` string, required
    - `type` 'CURP' | 'RFC' | 'RUT' | 'TAX_ID', required: Tipos de documento con que se identifica a un Beneficiary. Cada uno corresponde a un país: `RUT` es el rol único tributario chileno y solo se acepta en Chile; `RFC` es el registro tributario mexicano, `CURP` la clave de registro poblacional y `TAX_ID` el registro tributario genérico para un Beneficiary sin RFC, y los tres solo se aceptan en México.
  - `metadata` object: Datos libres que la Organization asocia al Beneficiary.
  - `name` string, required: Nombre o razón social del Beneficiary.
  - `organization_id` string, required: Identificador de la Organization dueña del Beneficiary.
  - `phone` string, nullable: Teléfono de contacto del Beneficiary.
  - `types` BeneficiaryType[], required: Categorías con que la Organization clasifica al Beneficiary según la relación que tiene con él. Son etiquetas descriptivas: puede llevar varias y ninguna cambia cómo se le paga ni qué validaciones se le aplican.
  - `updated_at` string, date-time, required: Momento de la última modificación del Beneficiary.

## Other responses

- `404`: No existe un Beneficiary con ese identificador.
- `422`: Falta el campo `metadata`, o alguna de sus claves está vacía, empieza con `$` o contiene un punto.

## Changes

- **2026-11-03** `a6ef070075b1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/trytoku/apis/toku-api/changes/payouts-beneficiary/:id_beneficiary/metadata/patch.md)

---

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