Adding custom data to rewards

Tremendous has a feature called Custom Fields that allows you to attach custom data to a reward, use it for search / tracking purposes, and even use the values provided in message copy.

Access custom fields via the dashboard UI here:

Setting custom field values in orders

Suppose we have a custom field called Harry Potter House, configured within the UI as follows:

If we'd like to set field as part of an order, we can do it as follows:

1. Obtain the field ID by querying the /fields endpoint

curl --request GET \
     --url https://testflight.tremendous.com/api/v2/fields \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer YOUR-API-KEY'

This will return a response like this:

{
  "fields": [
    {
      "id": "JLTZSBH3577S",
      "label": "harry_potter_house",
      "data_type": "Dropdown",
      "data": {
        "options": [
          "Gryffindor",
          "Slytherin",
          "Ravenclaw",
          "Hufflepuff"
        ]
      },
      "required": false,
      "scope": "REWARD"
    }
  ]
}

2. Supply the custom field value in the order, as follows:

curl --url 'https://testflight.tremendous.com/api/v2/orders' \
     --header 'Authorization: Bearer YOUR-API-KEY' \
     --header 'Content-Type: application/json' \
     --data '
{
     "payment": {
          "funding_source_id": "YOUR-FUNDING-SOURCE-ID"
     },
     "rewards": [
          {
               "value": {
                    "denomination": 50.00
               },
               "delivery": {
                    "method": "EMAIL"
               },
               "recipient": {
                    "name": "Jane Doe",
                    "email": "[email protected]"
               },
               "products": [
                    "OKMHM2X2OHYV"
               ],
               "custom_fields": [
                 {
                   "id": "JLTZSBH3577S",
                   "value": "Hufflepuff"
                 }
               ]
          }
     ]
}
'

This will return a successful order creation response. You can log into the UI and confirm that the custom field value was set:

Querying by custom fields

You can query for rewards by custom field attributes using the field label and values. Here's an example:

curl --request GET \
     --url 'https://testflight.tremendous.com/api/v2/rewards?harry_potter_house=Hufflepuff' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer YOUR-API-KEY'

This will return rewards with fields that have matching values:

{
   "rewards" : [
      {
        "id": "IG637YQY4BFY",
        "order_id": "U4HULVD8W7T9",
        "created_at": "2021-11-03 16:37:26 UTC",
        "value": {
          "denomination": 50.0,
          "currency_code": "USD"
        },
        "delivery": {
          "method": "EMAIL",
          "status": "PENDING"
        },
        "recipient": {
          "email": "[email protected]",
          "name": "Jane Doe"
        },
        "custom_fields": [
          {
            "id": "JLTZSBH3577S",
            "value": "Hufflepuff",
            "label": "harry_potter_house"
          }
        ]
      }
   ]
}