In Flock, rewards can be triggered automatically or manually, depending on the selected reward trigger. If you select any trigger other than “New User Signup”, you are required to implement the reward trigger in your backend code.

This guide explains how to trigger rewards programmatically by sending a POST request to Flock’s API.

​
Step 1: Retrieve Your API Key

  1. Log in to your Flock account at app.withflock.com.
  2. Navigate to the Secrets page.
  3. Locate the Service key on the page. This is the API key you will use to authenticate your requests.

​
Step 2: Understand the Trigger Rewards Endpoint

Endpoint:

POST https://api.withflock.com/rewards/trigger

Payload: The request payload should follow this structure:

FieldTypeDescription
customerExternalIdstringA unique identifier for the customer triggering the reward.
modeenumDetermines the reward payout mode: latest (trigger only the latest reward) or all (trigger all eligible rewards).
environmentenum (recommended)The environment to trigger rewards for: test or production. This is the recommended way to trigger rewards.
campaignIdstring (alternative)The ID of a specific campaign to trigger rewards for. Use this only if you need to target a specific campaign.

Note: You must provide either environment or campaignId, but not both.

​
Step 3: Implement the API Call

Here’s an example implementation in various programming languages:

const axios = require('axios');

const triggerReward = async () => {
const url = 'https://api.withflock.com/rewards/trigger';

  // Replace with your environment and customer details
  const payload = {
    environment: 'production', // or 'test'
    customerExternalId: 'customer_123',
    mode: 'latest' // or 'all'
  };

  try {
    const response = await axios.post(url, payload, {
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'your_service_key', // Replace with your Service API key
      },
    });

    console.log('Reward triggered successfully:', response.data);
  } catch (error) {
    console.error('Error triggering reward:', error.response?.data || error.message);
  }

};

triggerReward();

​
Step 4: Testing Your Integration

  1. Use a development or staging environment to test the API call before going live.
  2. Verify the response from Flock to ensure the reward is triggered successfully.
  3. Monitor your logs to track reward triggering and debug any issues.

​
Example Response

A successful reward trigger will return a 200 OK response with the reward details:

{
  "success": true,
  "id": "reward_456",
  "message": "Reward triggered successfully."
}