Sending a reward [old]

Send your first reward programmatically through the API.

๐Ÿšง

This guide has moved

Visit the new Sending reward guides for up-to-date instructions.

๐Ÿ“˜

Prerequisites

This guide assumes that you have obtained an API key and made a successful request. If you haven't yet, you can follow the instructions here.

To send a reward, we need to create an order for it on Tremendous.

To create an order, we first need to figure out two things:

  1. What redemption options do we want to offer the recipient? (e.g. let them choose between an Amazon gift card, a Visa debit card and dozens of other redemption options)?
  2. How do we want to pay for the reward?

Choose a product

On Tremendous, a "product" refers to a type of payout option available to the recipient of a reward.

Available products include gift cards (e.g. Amazon.com gift cards), prepaid cards (e.g. Visa cards), cash options (e.g. PayPal), charity donations, etc. The full list of products is available at https://www.tremendous.com/catalog or via the List Products API endpoint.

Every reward must specify one or more products. If you create an order with more than one product, the recipient can choose which theyโ€™d like.

For this example, we will stick to a single product: an Amazon.com gift card. The Amazon.com gift cards product has the ID OKMHM2X2OHYV.

๐Ÿ“˜

Product IDs may vary between environments. To get an up-to-date list of all available products, query the List Products API endpoint.

Choose a funding source

There are different ways to pay for orders. Each payment mechanism is called a "funding source." Creating an order requires specifying the ID of the funding source that will be used for payment.

Weโ€™ll use your Tremendous pre-funded balance as the funding source for this order. Every organization comes with this funding source enabled by default. And in the sandbox environment, we pre-load your balance with $5,000 USD.

Weโ€™ll need the ID of the funding source. We can do that with this request (see reference):

curl --url 'https://testflight.tremendous.com/api/v2/funding_sources' \
     --header 'Authorization: Bearer YOUR-API-KEY'

๐Ÿšง

Make sure to replace YOUR-FUNDING-SOURCE-ID with the ID of the funding source you obtained above.

The response should look like this:

{
  "funding_sources": [
    {
      "method": "balance",
      "id": "**YOUR-FUNDING-SOURCE-ID**",
      "meta": {
        "available_cents": 500000,
        "pending_cents": 0
      }
    }
  ]
}

Make a note of the returned id field. You will need it in a second.

Send the reward

It is showtime. We have everything we need to place our first order.

Letโ€™s send a $50 reward to Jane Doe:

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,
                    "currency_code": "USD"
               },
               "delivery": {
                    "method": "EMAIL"
               },
               "recipient": {
                    "name": "Jane Doe",
                    "email": "[email protected]"
               },
               "products": [
                    "OKMHM2X2OHYV"
               ]
          }
     ]
}
'

API response

The API responds like this:

{
  "order": {
    "id": "DD3SX1CWBA7P",
    "external_id": null,
    "created_at": "2021-07-30T19:59:52.889Z",
    "status": "EXECUTED",
    "payment": {
      "subtotal": 50.0,
      "total": 50.0,
      "fees": 0.0
    },
    "rewards": [
      {
        "id": "O2VG4D88KZ3N",
        "order_id": "DD3SX1CWBA7P",
        "value": {
          "denomination": 50.0,
          "currency_code": "USD"
        },
        "delivery": {
          "method": "EMAIL",
          "status": "PENDING"
        },
        "recipient": {
          "email": "[email protected]",
          "name": "Jane Doe"
        }
      }
    ]
  }
}

You can see a couple of things in the response:

  1. The status of the order is set to EXECUTED โ€” which tells you that the order was created successfully
  2. The rewards array has a single item in it. You can also use a single order to send multiple rewards at once.
  3. The reward will be delivered via email. The field delivery.status is PENDING, meaning that the email has not yet been delivered. In a moment, it will be updated to SUCCEEDED, meaning the reward was successfully delivered to the recipient.

Next steps

Here are some ideas what to explore next:

  • Check the balance of your funding source โ€” after sending out the gift card (see funding source endpoint's reference)
  • Redeem the reward you just sent by following the instructions in the email. (see reward endpoint's reference).
  • Send another reward, but allow the recipient to choose between reward options (e.g. Amazon gift card, Visa card, charitable donation, etc).

Next up

Personalize and style rewards and further simplify your integration by using campaigns