Using the Custom Fields feature, programmatically.

🚧

This page is under construction

This documentation is a little rougher than we'd like, and we're still working on ensuring it's correct. If you're running into issues, feel free to email us at [email protected]

Tremendous has a feature called Custom Fields that allows you to attach custom data to a reward, and use it for search / tracking purposes, or 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
               },
               "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. Note that, at the moment, the response does not include any confirmation within the JSON that the field was set. But you can log into the UI and confirm this:

Hufflepuff is set.Hufflepuff is set.

Hufflepuff is 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" : [
      {
         "created_at" : "2021-11-03T16:37:26.381Z",
         "delivery" : {
            "method" : "EMAIL",
            "status" : "PENDING"
         },
         "id" : "IG637YQY4BFY",
         "order_id" : "U4HULVD8W7T9",
         "recipient" : {
            "email" : "[email protected]",
            "name" : "Jane Doe"
         },
         "value" : {
            "currency_code" : "USD",
            "denomination" : 50
         }
      }
   ]
}