This endpoint runs a custom earning flow for a given customer. The points, the recurrence limits, and the per-customer cap are all the ones you defined when you set the flow up in the dashboard. The API just fires the execution.

Use this when you want a system outside of JeriCommerce, like your CRM, your review platform, or a survey tool, to be the source of truth for whether the customer earned the points.

For the full machine-readable spec with try-it-out, see the Execute Custom Earning Flow endpoint in the JeriCommerce API documentation.

Endpoint

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

Replace {programId} with your real program ID (find it under Settings → Technical → Program Information) and {earningFlowId} with either:

  • The slot identifier of the flow: CUSTOM_1, CUSTOM_2, CUSTOM_3, CUSTOM_4, or CUSTOM_5.
  • The UUID of the specific ProgramEngagementFlow row, if you prefer working with stable IDs.

The slot identifier is the easier choice because it stays the same even if you reset the flow.

Authentication

This endpoint accepts two authentication methods. Pick the one that fits your use case.

Use your program's API key in the Authorization header. See Authentication through the API.

With an API key you can execute the flow for **any** customer in your program. The customer's email is required in the request body.

Pass the customer's JWT in the Authorization header. The flow runs for the authenticated customer and the request body is empty.

Use this when the customer's own browser or app is the one calling the endpoint, for example from a custom storefront integration.

Request Body

{
  "customerEmail": "customer@example.com"
}
Field Type Required Notes
customerEmail string Required with API key auth. Ignored with customer JWT auth. Email of the customer who should receive the points. Must match a customer already enrolled in the program.

Response

A successful request returns 200 with a JSON body:

{
  "pointsAwarded": 100,
  "remainingExecutions": 0,
  "recurrence": "lifetime"
}
Field Type Notes
pointsAwarded number The number of points credited to the customer's balance in this execution.
remainingExecutions number How many more times this customer can execute the flow inside the current recurrence window. 0 means they have hit the cap.
recurrence string The recurrence window of the flow: once, daily, weekly, monthly, quarterly, semiannually, or yearly.

Errors

If the request cannot be completed, the API returns an error code so your integration can react.

Code Meaning
CUSTOMER_EMAIL_REQUIRED You used API key auth without sending customerEmail in the body.
EARNING_FLOW_NOT_FOUND The earningFlowId does not exist in this program.
NOT_A_CUSTOM_EARNING_FLOW The flow ID points to a standard flow (e.g. INCENTIVIZE_PURCHASES), which cannot be triggered this way.
EARNING_FLOW_INACTIVE The flow exists but is currently deactivated in the dashboard.
EARNING_FLOW_NOT_CONFIGURED The flow is missing required properties (points, recurrence, or max executions). Open it in the dashboard and save it.
CUSTOMER_NOT_FOUND No customer with that email exists in the program.
MAX_EXECUTIONS_REACHED The customer has already executed the flow the maximum number of times in the current recurrence window.

Example

You set up CUSTOM_2 to award 100 points, once per lifetime, for completing a post-purchase survey. Your survey tool calls the endpoint when a customer submits a response.

// Request

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

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

// Response

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

The customer's balance goes up by 100 points and the flow card in their webapp updates to show "You already earned this".

If you trigger from Shopify Flow or Klaviyo, you do not need to build the request yourself. Use the Execute earning flow action documented in Shopify Flows and Events, or generate a ready-to-paste webhook with the Klaviyo webhook builder.