How do you Install ‘tremendousr’?

You can install tremendousr via CRAN or GitHub and load it as follows:

# Install released version from CRAN
install.packages("tremendousr")

# Or, install the development version from GitHub
remotes::install_github("jdtrat/tremendousr")

# Load package
library(tremendousr)

Background

Tremendous provides two environments for their platform:

• ‘Sandbox’ environment, a “free and fully-featured environment for application development and testing.”

• ‘Production’ environment, where real payments can be sent.

Tremendous API users typically develop their applications against the sandbox environment, and then switch their credentials to production when they are ready to go live.

To begin, you must create a Tremendous account. For the sandbox environment, you can sign up or log-in here and generate an API key by navigating to Team Settings > Developers and clicking on Add API key on the top right. You can follow the official documentation here.

With an API key, you can create a Tremendous Client in R and begin interacting with Tremendous.

Create a Tremendous Client

In order to send a payment, or access other features of Tremendous, you must use a Tremendous Client, which you can create with the function trem_client_new(). This is a convenient way to bundle your authentication (API) credentials and ensure you are using the proper environment (sandbox or production) for your calls. Conveniently, Tremendous prefixes API keys for each environment to differentiate them. If you’re using the sandbox environment, your API key would begin with TEST_; the production environment key will begin with PROD_.

test_client <- trem_client_new(api_key = "TEST_YOUR-KEY-HERE",
                               sandbox = TRUE)
# Print Tremendous API Client
test_client

#> <tremendousClient>
#>  API key: <private>
#>  API Environment: Sandbox

Sending a Reward

In Tremendous, rewards start out as orders which contain information about the recipient, reward amount and type, funding source, delivery method, and a payment description id (what they refer to as an ‘external id’). Orders can be fulfilled either immediately or upon approval by your Tremendous Account administrator. To turn on approvals, you can login to your Tremendous account and navigate to Team Settings > Approvals and click Order Approvals: OFF to toggle it on.

A screenshot from the Tremendous Web Portal showing the ‘Order Appovals’ setting.

In general, when working in the ‘Sandbox’ environment, I would not require order approvals. I think this helps you refine payment methods, reward options, etc. more quickly.¹ To take my own advice, in this post, I’ll keep orders approval off. Either way, though, to create an order and have the reward send (immediately or upon approval), you should use the function trem_send_reward() as follows:

trem_send_reward(client = test_client,
             name = "first last",
             email = "email@website.com",
             reward_amount = 10,
             currency_code = "USD",
             delivery_method = "EMAIL",
             payment_description_id = "payment-from-intro-to-tremendousr",
             funding_source_id = "your-funding-id-from-tremendous",
             reward_types = "Q24BD9EZ332JT", # ID for virtual visa gift card
             parse = TRUE # Return a parsed API response
             )

Under the hood, this function performs a POST request for creating an order using Tremendous.² For detailed documentation on each field, I encourage you to check out the function’s help documentation (?trem_send_reward) or the official Tremendous documentation.

In sending this to myself, I get an email with a link to a redeem a Visa gift card:

Preview of what redeeming a Virtual Visa Gift Card looks like. A blue box with a title “Virtual prepaid card” followed by contact information fields and terms of service information.

Setting your API key

It is best practice to never include your API key within your R script in the event you inadvertently share it. To help with this, I include a utility function, trem_set_api_key(), which can (and should) be used as follows.

trem_set_api_key("TEST_YOUR-KEY-HERE")
#> • You may wish to add your Tremendous Test API key to your '.Renviron' file:
#> TREMENDOUS_TEST_KEY=TEST_YOUR-KEY-HERE
#> [Copied to clipboard]
#> • To edit your '.Renviron' file:
#> - Check that usethis is installed.
#> - Call `usethis::edit_r_environ()`.
#> - Check that '.Renviron' ends with a new line.
test_client <- trem_client_new(api_key = NULL, # Accesses environmental variable
                               sandbox = TRUE)

Setting a Funding ID

In the sandbox environment, from what I understand, there is only one funding source (with a $5,000 limit that resets daily). Using the trem_get() function, you can easily define a variable for using trem_send_reward() as follows:

funding_id <- trem_get(test_client, "funding_sources")$funding_sources$id

Finding Payment Methods

Tremendous offers support for over 600 reward types, including Virtual Visa, Starbucks, and Amazon gift cards, as well as ACH transfers. When sending a reward, you can define as many reward types, using a character vector of the ID, which will allow them to choose what they prefer.

I think the easiest way of finding reward types is by browsing their online catalog. Using the name, you can then access their IDs as shown below. For this example, I’ll get the IDs for ‘Best Buy’, ‘Virtual Visa’, and ‘Target’ gift cards, making sure the currency is US dollars. I’m going to use the package dplyr for easy data manipulation and to show how you can use the pipe³ to pass the Tremendous API client around.

library(dplyr)
library(magrittr)

# Save the current product listing as 'prods'
prods <- test_client %>%
  trem_get("products")

# Access the 'products' data frame of prods and filter it to desired reward types, assigning the IDs as 'reward_ids'.
reward_ids <- prods$products %>% 
  # Filter so the name is either "Virtual Visa", "Target", or "Best Buy" AND the currency code is "USD"
  filter(name %in% c("Virtual Visa", "Target", "Best Buy") & currency_codes == "USD") %>% 
  # Grab the IDs
  pull(id)

I did not include the product data in the package because – from my understanding – the IDs, and available options, are subject to change.

Have a ✨Tremendous✨ Day!

Thanks for reading my blog post! I hope you find use for tremendousr (and, of course, Tremendous). If you have any feedback, I’d love for you to file an issue. For more of my work, check out my GitHub! If you want to chat about anything (including neuroscience, #rstats, piano, or my kitten), DM me on Twitter! Lastly, if you need help with an #rstats or shiny project, I’m available for consulting – just send me an email!