Every time you want to send out a reward through Tremendous you need to create an order for it.

πŸ“˜

Getting started with your first order

Our step-by-step guide walks you through everything you need
to send your first gift card through the Tremendous API:

Check it out!

Request body

Property Type Description
external_id
string

Reference for this order, supplied by the customer.

When set, external_id makes order idempotent. All requests that use the same external_id after the initial order creation, will result in a response that returns the data of the initially created order. The response will have a 201 response code. These responses fail to create any further orders.

It also allows for retrieving by external_id instead of id only.

payment
object
Show object properties
Property Type Description
funding_source_id
string

Tremendous ID of the funding source that will be used to pay for the order. Use balance to use your Tremendous's balance.

reward
object

A single reward, sent to a recipient. A reward is always part of an order.

Either products or campaign_id must be specified.

Show object properties
Property Type Description
id
string

Tremendous ID of the reward

order_id
string

Tremendous ID of the order this reward is part of.

created_at
string date-time

Date the reward was created

campaign_id
string

ID of the campaign in your account, that defines the available products (different gift cards, charity, etc.) that the recipient can choose from.

products
array string

List of IDs of product (different gift cards, charity, etc.) that will be available to the recipient to choose from.

Providing a products array will override the products made available by the campaign specified using the campaign_id property unless the products array is empty. It will not override other campaign attributes, like the message and customization of the look and feel.

value
object
Show object properties
Property Type Description
denomination
number double

Amount of the reward

currency_code
string

Currency of the reward

recipient
object

Details of the recipient of the reward

Show object properties
Property Type Description
name
string

Name of the recipient

email
string

Email address of the recipient

phone
string

Phone number of the recipient. For non-US phone numbers, specify the country code (prefixed with +).

deliver_at
string date

Timestamp of reward delivery within the next year. Note that if date-time is provided, the time values will be ignored.

custom_fields
array
Show array item type
Property Type Description
id
string

Tremendous ID of the custom field

value
string

Value of the custom field

label
string

Label of the custom field

language
string

Set this to translate the redemption experience for this reward. Pass a 2-letter ISO-639-1 code for the desired language. Defaults to en.

delivery
object

Details on how the reward is delivered to the recipient.

Show object properties
Property Type Description
method
string

How to deliver the reward to the recipient.

Delivery Method Description
EMAIL Deliver the reward to the recipient by email
LINK

Deliver the reward to the recipient via a link.

The link can be retrieved on a successfully ordered reward via the /rewards or /rewards/{id} endpoint. That link must then be delivered to the recipient out-of-band.

PHONE Deliver the reward to the recipient by SMS

Funding sources

There are different ways to pay for gift cards and rewards on Tremendous. Every payment mechanism is called a "funding source".

You can retrieve a list of all available funding sources by using the Funding sources API endpoint.

The Tremendous API sandbox environment comes with a single funding source that allows you to spend up to $5,000 in fake money to test the API. Learn more about the sandbox environment.

The HTTP status code 200 on the response will be used to indicate success.

After processing successfully the reward gets queued to be delivered to it's recipient
(for delivery method EMAIL and PHONE). Delivery will happen asynchronously, after the response
has been sent.

Idempotence

Requests issued with the same external_id are idempotent.

Submitting an order with an already existing external_id, will result in a 201 response code.
In this case the response will return a representation of the already existing order in the response body.

Language
Authorization
Bearer
URL
Click Try It! to start a request and see the response here!