Este endpoint ejecuta un flujo de acumulación personalizado para un cliente. Los puntos, los límites de recurrencia y el máximo por cliente son los que definiste al configurar el flujo en el panel. La API simplemente inicia la ejecución.

Úsalo cuando un sistema externo a JeriCommerce, como tu CRM, plataforma de reseñas o herramienta de encuestas, deba determinar si el cliente ha obtenido los puntos.

Para consultar la especificación completa, legible por máquinas y con opción de prueba, visita el endpoint Execute Custom Earning Flow en la documentación de la API de JeriCommerce.

Endpoint 

// POST
https://api.jericommerce.com/v1/programs/{programId}/custom-earning-flows/{earningFlowId}/execute

Sustituye {programId} por el ID real del programa, que encontrarás en Settings → Technical → Program Information, y {earningFlowId} por una de estas opciones:

  • El identificador de posición del flujo: CUSTOM_1, CUSTOM_2, CUSTOM_3, CUSTOM_4 o CUSTOM_5.
  • El UUID de la fila ProgramEngagementFlow concreta, si prefieres usar identificadores estables.

El identificador de posición es más sencillo porque no cambia aunque restablezcas el flujo.

Autenticación

Este endpoint acepta dos métodos de autenticación. Elige el que se adapte a tu caso.

Usa la clave API de tu programa en el encabezado `api-key`. Consulta [Autenticación mediante la API](/integrations/api/1-authentication-through-the-api/).

Con una clave API puedes ejecutar el flujo para **cualquier** cliente del programa. El cuerpo de la solicitud debe incluir el correo del cliente.

Envía el JWT del cliente en el encabezado `Authorization`. El flujo se ejecuta para el cliente autenticado y el cuerpo de la solicitud queda vacío.

Úsalo cuando el navegador o la aplicación del propio cliente llame al endpoint, por ejemplo, desde una integración personalizada de la tienda.

Cuerpo de la solicitud 

{
  "customerEmail": "customer@example.com"
}
Campo Tipo Obligatorio Notas
customerEmail string Obligatorio con autenticación API key. Se ignora con Customer JWT. Correo del cliente que recibirá los puntos. Debe coincidir con un cliente ya inscrito en el programa.

Respuesta

Una solicitud correcta devuelve 200 con un cuerpo JSON:

{
  "pointsAwarded": 100,
  "remainingExecutions": 0,
  "recurrence": "lifetime"
}
Campo Tipo Notas
pointsAwarded number Cantidad de puntos añadida al saldo del cliente en esta ejecución.
remainingExecutions number Número de veces que el cliente todavía puede ejecutar el flujo en el periodo de recurrencia actual. 0 significa que ha alcanzado el máximo.
recurrence string Periodo de recurrencia del flujo: once, daily, weekly, monthly, quarterly, semiannually o yearly.

Errores

Si no se puede completar la solicitud, la API devuelve un código de error para que tu integración pueda reaccionar.

Código Significado
CUSTOMER_EMAIL_REQUIRED Has usado API key auth sin enviar customerEmail en el cuerpo.
EARNING_FLOW_NOT_FOUND earningFlowId no existe en este programa.
NOT_A_CUSTOM_EARNING_FLOW El ID del flujo apunta a un flujo estándar, por ejemplo INCENTIVIZE_PURCHASES, que no se puede activar de esta forma.
EARNING_FLOW_INACTIVE El flujo existe, pero está desactivado en el panel.
EARNING_FLOW_NOT_CONFIGURED Faltan propiedades obligatorias del flujo, como los puntos, la recurrencia o el máximo de ejecuciones. Ábrelo en el panel y guárdalo.
CUSTOMER_NOT_FOUND No hay ningún cliente con ese correo en el programa.
MAX_EXECUTIONS_REACHED El cliente ya ha ejecutado el flujo el número máximo de veces dentro del periodo de recurrencia actual.

Ejemplo

Configuras CUSTOM_2 para conceder 100 puntos, una vez durante toda la vida, al completar una encuesta posterior a la compra. La herramienta de encuestas llama al endpoint cuando el cliente envía una respuesta.

// Request

POST https://api.jericommerce.com/v1/programs/{{program_id}}/custom-earning-flows/CUSTOM_2/execute
api-key: {your_api_key}
Content-Type: application/json

{
  "customerEmail": "customer@example.com"
}

// Response

{
  "pointsAwarded": 100,
  "remainingExecutions": 0,
  "recurrence": "lifetime"
}

El saldo del cliente aumenta en 100 puntos y la tarjeta del flujo en su aplicación web se actualiza para mostrar "Ya has obtenido esta recompensa".

Si lo activas desde Shopify Flow o Klaviyo, no tienes que crear la solicitud. Usa la acción Execute earning flow, descrita en Shopify Flows y eventos, o genera un webhook listo para pegar con el generador de webhooks de Klaviyo.