tremendousr

Getting Started

tremendous is a platform that “empowers companies to buy, track and manage digital and physical payments.” This package provides a slightly-opinionated R interface for the ‘Tremendous’ API with, dare I say, tremendously intuitive functions for sending rewards and incentives directly from R.

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.

Unsurprisingly, in order to use this package, 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 send payments as shown below.

Creating a Tremendous API Client

To use this package, you must create a Tremendous API Client by calling, which can be done by calling 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

To make your life easier for subsequent uses, I recommend calling trem_set_api_key() with your API key, which will walk you through adding this information as an R environment variable:

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.

Send Rewards

Given the most likely reason for using tremendousr is to send rewards, we provide a nice function to do just that! With your Tremendous Client created, it’s as simple as calling trem_send_reward() with the proper arguments. A simple example is below. For more documentation on each argument, please call ?trem_send_reward() in your console.

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-tremendousr-examples",
             funding_source_id = "your-funding-id-from-tremendous",
             reward_types = "Q24BD9EZ332JT", # ID for virtual visa gift card
             parse = TRUE # Return a parsed API response
             )

Perform GET Requests

tremendousr also provides support for general GET requests with the function trem_get(). Some examples from the function documentation:

# Use a GET request to list funding sources available in your Tremendous Account. 
# Documentation: https://developers.tremendous.com/reference/core-funding-source-index
trem_get(test_client, "funding_sources")

# Use a GET request to list all orders (payment history) on your Tremendous Account.
# Documentation: https://developers.tremendous.com/reference/core-orders-index
trem_get(test_client, "orders")

Perform POST Requests

tremendousr also provides support for general POST requests with the function trem_post(). An example from the function documentation:

# Use a POST request to invite new members to your Tremendous Account.
# Documentation: https://developers.tremendous.com/reference/post_members
 trem_post(test_client,
           path = "members",
           body = list(email = "example@website.com",
                       name = "Example Person",
                       role = "MEMBER"))

Perform DELETE Requests

tremendousr provides support for DELETE requests with only one endpoint to “delete an invoice.” Per the official documentation, this request “removes an invoice. This has no further consequences but is a rather cosmetic operation.” An example, and currently the only supported action, adapted from the function documentation:

  # Perform a POST request for an invoice.
  # `po_number` is Reference to the purchase order number within your organization
  # `amount` is in USD
  trem_post(test_client,
            path = "invoices",
            body = list(po_number = "unique-invoice-id",
                        amount = 50)
  )

  # Perform a GET request for listing all current (non-deleted) invoices.
  current_invoices <- trem_get(test_client, "invoices")

  # Get the invoice ID for 'unique-invoice-id' to delete
  my_invoice_id <- current_invoices$invoices[which(current_invoices$invoices$po_number == "unique-invoice-id"), "id"]

  # Perform a DELETE request for the specific invoice.
  del <- trem_delete(test_client, paste0("invoices/", my_invoice_id))

  # Perform a GET request for listing all current (non-deleted) invoices.
  # The one with id po_number 'unique-invoice-id' should no longer be here.
  new_invoices <- trem_get(test_client, "invoices")

  # Check that the invoice is was deleted; this should be FALSE
  del$invoice$id %in% new_invoices$invoices$id