Skip to main content

Schedule campaign rewards

Contents​

Overview​

Spaaza Console calls issue_rewards campaigns "Scheduled Rewards" campaigns. Once the campaign itself already exists, rewards are scheduled by creating one or more task resources in the services API.

For an issue_rewards campaign, each scheduled run is represented by a task with:

  • target.action set to mass issue vouchers
  • target.campaign set to the existing issue_rewards campaign ID
  • trigger.once set to the first run date and time
  • Optional trigger.repeat set to daily, weekly, or monthly
  • Optional audience targeting through either trigger.segment_id or trigger.user_list

If neither trigger.segment_id nor trigger.user_list is provided, the task targets all customers.

This page assumes the campaign already exists. If you still need to create the campaign itself, see Adding a campaign and the issue rewards campaign fields.

Authentication and base URLs​

The task and blob endpoints used for scheduled rewards are services API endpoints.

Endpoint purposeURL
Create and list taskshttps://{Services API hostname}/tasks
Create a presigned upload for a CSV filehttps://{Services API hostname}/blobs/store

The API_ENVIRONMENT value follows the same pattern used elsewhere in the services API:

EnvironmentAPI_ENVIRONMENT value
Productionprod
Stagingtest01

Use the same admin authentication described on the Authentication page. In practice, requests should include:

  • X-Spaaza-Session-User-Id
  • X-Spaaza-Session-Key
  • X-Spaaza-Session-Chain-Id
  • X-Spaaza-API-Version

Create a task for a scheduled rewards campaign​

Create a task by POSTing JSON to the services tasks endpoint.

Example request:

curl --request POST 'https://{Services API hostname}/tasks' \
  --header 'X-Spaaza-Session-User-Id: 1' \
  --header 'X-Spaaza-Session-Key: YOUR_SESSION_KEY' \
  --header 'X-Spaaza-Session-Chain-Id: 1743' \
  --header 'X-Spaaza-API-Version: 1.0' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "chain": 1743,
    "desc": "Issue April wallet reward",
    "trigger": {
      "once": "2026-04-30T08:00:00.000Z",
      "repeat": ""
    },
    "target": {
      "action": "mass issue vouchers",
      "title": "",
      "campaign": 1234
    }
  }'

Request fields:

FieldDescription
chain(integer, required) The chain ID.
desc(string, optional but recommended) A human-readable task description. Console defaults this to Issue rewards task if you do not supply one.
trigger.once(string, required) The first run timestamp for the task, in ISO 8601 format.
trigger.repeat(string, optional) Use daily, weekly, or monthly for recurring tasks. For a one-off task, Console currently sends an empty string.
target.action(string, required) Must be mass issue vouchers.
target.campaign(integer, required) The ID of the existing issue_rewards campaign.
target.title(string, optional) Console leaves this empty for scheduled rewards tasks.

A successful response returns the created task object, including its generated id.

Target a task to a segment​

To issue rewards only to one segment, set trigger.segment_id on the task.

Example request:

{
  "chain": 1743,
  "desc": "Issue loyalty bonus to Gold members",
  "trigger": {
    "once": "2026-05-01T07:00:00.000Z",
    "repeat": "weekly",
    "segment_id": "AWNkG0vgpp3ErSgjijjG"
  },
  "target": {
    "action": "mass issue vouchers",
    "title": "",
    "campaign": 1234
  }
}

Notes:

Upload a CSV file and assign it to a task​

If you want to target a fixed CSV list instead of a segment, first upload the CSV file and then set the returned private URL as trigger.user_list.

1. Prepare the CSV file​

Console expects a CSV file with these columns:

username,id
john.doe@example.com,12345
jane.smith@example.com,67890
  • username is the customer's email address or username in Spaaza
  • id is the Spaaza user ID

2. Request a presigned upload​

Create a presigned upload request against blobs/store:

curl --request POST 'https://{Services API hostname}/blobs/store?chain_id=1743&name=scheduled-rewards.csv&public=false' \
  --header 'X-Spaaza-Session-User-Id: 1' \
  --header 'X-Spaaza-Session-Key: YOUR_SESSION_KEY' \
  --header 'X-Spaaza-Session-Chain-Id: 1743' \
  --header 'X-Spaaza-API-Version: 1.0'

Example response:

{
  "private_url": "https://...",
  "public_url": "https://...",
  "upload": {
    "url": "https://...",
    "headers": {
      "...": "..."
    }
  }
}

For scheduled rewards tasks, use the returned private_url. Console stores uploaded customer CSV files as private objects.

3. Upload the file to the returned storage URL​

Use the upload.url and every header in upload.headers from the previous response when you PUT the file to storage.

curl --request PUT 'PRESIGNED_UPLOAD_URL_FROM_BLOBS_STORE' \
  --header 'HEADER_NAME_1: HEADER_VALUE_1' \
  --header 'HEADER_NAME_2: HEADER_VALUE_2' \
  --upload-file ./scheduled-rewards.csv

4. Create or update the task with trigger.user_list​

Once the file upload succeeds, pass the returned private_url as trigger.user_list:

{
  "chain": 1743,
  "desc": "Issue make-good vouchers to uploaded users",
  "trigger": {
    "once": "2026-05-07T08:30:00.000Z",
    "repeat": "",
    "user_list": "https://PRIVATE_FILE_URL_FROM_BLOBS_STORE"
  },
  "target": {
    "action": "mass issue vouchers",
    "title": "",
    "campaign": 1234
  }
}

When you use trigger.user_list, do not also set trigger.segment_id.

If you need a source list of users to work from, Export users can be useful for generating a baseline customer file before reducing it to the username,id format required here.

Request all tasks for a scheduled rewards campaign​

To fetch tasks attached to one issue_rewards campaign, request the services tasks endpoint with the campaign ID.

Example request:

curl --request GET 'https://{Services API hostname}/tasks?chain_id=1743&campaign_id=1234&action=bulk%20issue%20rewards&modern=true&limit=100&offset=0' \
  --header 'X-Spaaza-Session-User-Id: 1' \
  --header 'X-Spaaza-Session-Key: YOUR_SESSION_KEY' \
  --header 'X-Spaaza-Session-Chain-Id: 1743' \
  --header 'X-Spaaza-API-Version: 1.0'

Relevant query parameters:

ParameterDescription
chain_id(integer, required) The chain ID.
campaign_id(integer, recommended) Restricts results to tasks linked to one campaign.
action(string, recommended) Use mass issue vouchers to limit the result set to scheduled rewards tasks.
modern(boolean, optional) When true, the response uses the paginated resources format. Console uses true by default.
limit(integer, optional) Page size. The current default and maximum is 100.
offset(integer, optional) Pagination offset.

Example response:

{
  "resources": [
    {
      "id": "task-7df3f8",
      "desc": "Issue April wallet reward",
      "trigger": {
        "once": "2026-04-30T08:00:00.000Z",
        "repeat": "",
        "segment_id": "AWNkG0vgpp3ErSgjijjG"
      },
      "target": {
        "action": "mass issue vouchers",
        "title": "",
        "campaign": 1234
      },
      "state": {
        "code": "READY",
        "last_modified": "2026-04-15T09:00:00.000Z"
      }
    }
  ],
  "limit": 100,
  "offset": 0,
  "total_count": 1,
  "result_type": "resources"
}