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.
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
<- trem_client_new(api_key = "TEST_YOUR-KEY-HERE", test_client 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.
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 = "firstname.lastname@example.org", 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 )
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")
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 = "email@example.com", name = "Example Person", role = "MEMBER"))
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. <- trem_get(test_client, "invoices") current_invoices # Get the invoice ID for 'unique-invoice-id' to delete <- current_invoices$invoices[which(current_invoices$invoices$po_number == "unique-invoice-id"), "id"] my_invoice_id # Perform a DELETE request for the specific invoice. <- trem_delete(test_client, paste0("invoices/", my_invoice_id)) del # 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. <- trem_get(test_client, "invoices") new_invoices # Check that the invoice is was deleted; this should be FALSE $invoice$id %in% new_invoices$invoices$id del