Actualizar un suscriptor
Actualiza identidad y propiedades de un suscriptor sin transferir el consentimiento a otra dirección o número.
PATCH /v1/subscribers/:id
Requiere el permiso subscribers:write o full. Los permisos se comprueban en el servidor. Las claves test se rechazan con 403 test_mode_unavailable; no existe un sandbox aislado.
Actualiza el suscriptor indicado. Los campos omitidos conservan su valor; properties se combina clave por clave. Una clave enviada sustituye su valor y una omitida se conserva.
El cuerpo no admite consent, lists ni tags. Utiliza subscribe y unsubscribe para registrar decisiones explícitas de consentimiento. Cambiar email retira el alta del email anterior; cambiar phone no transfiere las altas de SMS o WhatsApp al nuevo número. Las bajas y supresiones anteriores se conservan.
Parámetro de ruta
id es el identificador sub_… del suscriptor. También se admite el UUID sin prefijo, con o sin guiones. Cualquier otro formato devuelve 400 invalid_param.
Cuerpo de la petición
Se rechazan campos desconocidos con 400 invalid_param. Un cuerpo vacío devuelve el objeto actual sin cambios.
| Campo | Tipo | Descripción |
|---|---|---|
email | string o null | Nueva dirección, hasta 255 caracteres, recortada y en minúsculas. null la elimina; conserva un teléfono. |
phone | string o null | Nuevo teléfono, entre 3 y 32 caracteres. null lo elimina. |
first_name | string o null | Nombre, hasta 100 caracteres; null lo borra. |
last_name | string o null | Apellidos, hasta 100 caracteres; null los borra. |
external_id | string o null | Identificador propio, hasta 255 caracteres; null lo borra. |
properties | object | Se combina con las propiedades actuales. null como valor de una clave guarda ese valor, no elimina la clave. No se admiten claves con prefijo __. |
Respuesta
El objeto actualizado con 200 OK.
Ejemplo
curl -X PATCH https://fluyio.com/api/v1/subscribers/sub_9f1c2b3a4d5e6f708192a3b4c5d6e7f8 \
-H "Authorization: Bearer $FLUYIO_API_KEY" \
-H "Fluyio-Version: 2026-05-15" \
-H "Content-Type: application/json" \
-d '{
"first_name": "Ada",
"properties": {
"plan": "enterprise",
"trial_ended_at": "2026-05-10T00:00:00Z"
}
}'Respuesta
{
"id": "sub_9f1c2b3a4d5e6f708192a3b4c5d6e7f8",
"object": "subscriber",
"email": "[email protected]",
"phone": "+34600000000",
"first_name": "Ada",
"last_name": "Lovelace",
"external_id": "user_12345",
"consent": {
"email": "subscribed",
"sms": "subscribed",
"whatsapp": "never_subscribed"
},
"properties": {
"company": "Analytical Engines",
"plan": "enterprise",
"country": "ES",
"trial_ended_at": "2026-05-10T00:00:00Z"
},
"lists": ["lst_0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f"],
"tags": ["beta", "vip"],
"created_at": "2026-05-11T12:34:56.000Z",
"updated_at": "2026-05-11T18:02:11.000Z",
"last_active_at": "2026-05-11T15:00:00.000Z"
}El cambio de email no utiliza la misma comprobación previa de duplicados que la creación. Resuelve primero la identidad en tu sistema y usa external_id para localizar el suscriptor. No presupongas que un conflicto al actualizar devolverá el mismo 409 que al crear.
Errores
| HTTP | code | Descripción |
|---|---|---|
| 401 | missing_api_key / invalid_api_key | Falta la clave, no es válida, ha caducado o está revocada. |
| 403 | missing_scope | La clave no permite esta operación. |
| 403 | test_mode_unavailable | El modo de pruebas no está disponible. |
| 400 | invalid_param | ID, tipo, longitud, dirección, propiedad o campo no válidos. |
| 404 | resource_not_found | El suscriptor no existe en esta marca. |
| 409 | idempotency_key_reuse | Se reutilizó una clave con otro cuerpo. |