Questo endpoint esegue un flusso di accumulo personalizzato per un cliente. Punti, limiti di ricorrenza e limite per cliente sono quelli impostati nel flusso dalla dashboard. L'API avvia semplicemente l'esecuzione.

Usalo quando vuoi che un sistema esterno a JeriCommerce, come il CRM, una piattaforma di recensioni o uno strumento per sondaggi, stabilisca se il cliente ha diritto ai punti.

Per la specifica completa consultabile dalla macchina, con prova interattiva, vedi l'endpoint Execute Custom Earning Flow nella documentazione API JeriCommerce.

Endpoint 

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

Sostituisci {programId} con l'ID effettivo del programma, disponibile in Settings → Technical → Program Information, e {earningFlowId} con uno di questi valori:

  • L'identificativo dello slot del flusso: CUSTOM_1, CUSTOM_2, CUSTOM_3, CUSTOM_4 o CUSTOM_5.
  • L'UUID della riga specifica ProgramEngagementFlow, se preferisci usare identificativi stabili.

Lo slot è l'opzione più semplice perché non cambia anche se reimposti il flusso.

Autenticazione

L'endpoint accetta due metodi di autenticazione. Scegli quello adatto al caso d'uso.

Usa la chiave API del programma nell'header `api-key`. Consulta [Autenticazione tramite API](/integrations/api/1-authentication-through-the-api/).

Con una chiave API puoi eseguire il flusso per **qualsiasi** cliente del programma. L'email del cliente è obbligatoria nel corpo della richiesta.

Passa il JWT del cliente nell'header `Authorization`. Il flusso viene eseguito per il cliente autenticato e il corpo della richiesta è vuoto.

Usa questo metodo quando è il browser o l'app del cliente a chiamare l'endpoint, per esempio da un'integrazione storefront personalizzata.

Corpo della richiesta 

{
  "customerEmail": "customer@example.com"
}
Campo Tipo Obbligatorio Note
customerEmail string Obbligatorio con autenticazione API key. Ignorato con autenticazione JWT cliente. Email del cliente che deve ricevere i punti. Deve corrispondere a un cliente già iscritto al programma.

Risposta

Una richiesta riuscita restituisce 200 con un corpo JSON:

{
  "pointsAwarded": 100,
  "remainingExecutions": 0,
  "recurrence": "lifetime"
}
Campo Tipo Note
pointsAwarded number Punti accreditati sul saldo del cliente durante questa esecuzione.
remainingExecutions number Quante volte il cliente può ancora eseguire il flusso nella finestra di ricorrenza corrente. 0 indica che ha raggiunto il limite.
recurrence string Finestra di ricorrenza del flusso: once, daily, weekly, monthly, quarterly, semiannually o yearly.

Errori

Se la richiesta non può essere completata, l'API restituisce un codice di errore per permettere all'integrazione di reagire.

Codice Significato
CUSTOMER_EMAIL_REQUIRED È stata usata l'autenticazione API key senza inserire customerEmail nel corpo.
EARNING_FLOW_NOT_FOUND earningFlowId non esiste in questo programma.
NOT_A_CUSTOM_EARNING_FLOW L'ID indica un flusso standard (per esempio INCENTIVIZE_PURCHASES), che non può essere attivato in questo modo.
EARNING_FLOW_INACTIVE Il flusso esiste, ma è disattivato nella dashboard.
EARNING_FLOW_NOT_CONFIGURED Mancano proprietà obbligatorie del flusso (punti, ricorrenza o numero massimo di esecuzioni). Aprilo e salvalo nella dashboard.
CUSTOMER_NOT_FOUND Il programma non contiene un cliente con questa email.
MAX_EXECUTIONS_REACHED Il cliente ha già eseguito il flusso il numero massimo di volte consentito nella finestra di ricorrenza corrente.

Esempio

Configuri CUSTOM_2 per assegnare 100 punti, una volta nella vita, dopo il completamento di un sondaggio post-acquisto. Lo strumento per sondaggi chiama l'endpoint dopo l'invio di una risposta.

// 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"
}

Il saldo del cliente aumenta di 100 punti e la scheda del flusso nella web app mostra «Hai già ottenuto questo premio».

Se attivi il flusso da Shopify Flow o Klaviyo, non devi creare la richiesta manualmente. Usa l'azione Execute earning flow descritta in Shopify Flows ed eventi oppure genera un webhook pronto da incollare con il Klaviyo Webhook Builder.