Create order

post https://testflight.tremendous.com/api/v2/orders

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

id

string

Tremendous ID of the order

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.

created_at

string date-time

Date the order has been created

status

string

Execution status of a given order

Status	Description
`CART`	The order has been created, but hasn't yet been processed.
`EXECUTED`	The order has been executed. Payment has been handled and rewards are being delivered (if applicable).
`FAILED`	The order could not be processed due to an error. E.g. due to insufficient funds in the account.

payment

object

Cost breakdown of the order (cost of rewards + fees). Cost and fees are always denominated in USD, independent from the currency of the ordered rewards. Note that this property will only appear for processed orders (status is EXECUTED).

Show object properties

Property Type Description

subtotal

number double

Total price of the order before fees (in USD)

total

number double

Total price of the order including fees (in USD)

fees

number double

Fees for the order (in USD)

funding_source_id

string

ID of the funding source linked to your account, to draw funds from for this order

refund

object

Breakdown of the order refunds (total amount in USD, independent from the currency of the ordered rewards). Note that this property will only appear for canceled orders or orders with canceled rewards.

Show object properties

Property	Type	Description
`total`	number double	Total amount of the order refunds (in USD)

channel

string

Name of the channel in which the order was created

invoice_id

string

The ID for the invoice associated with this order

rewards

array

Show array item type

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 campaign_id property.

value

object

Show object properties

Property	Type	Description
`denomination`	integer	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	Email address of the recipient
`phone`	string	Phone number of the recipient. For non-US phone numbers, specify the country code (prefixed with +).

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

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

status

string

Current status of the delivery of the reward:

SCHEDULED - Reward is scheduled for delivery and will be delivered soon.
FAILED - Delivery of reward failed (e.g. email bounced).
SUCCEEDED - Reward was successfully delivered (email or text message delivered or reward link opened).
PENDING - Delivery is pending but not yet scheduled.

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.

Synchronous processing (single reward)

Orders for exactly 1 reward will be processed synchronously.
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.

Asynchronous processing (multiple rewards)

Orders for 2 or more rewards at once are be processed asynchronously.
The HTTP status code 202 on the response will be used to indicate that the order was accepted for processing.

After acceptance orders will have a status of CART.
Orders will generally be processed within 30s of submission.

To react on whether an order was processed successfully or failed, you can:

Poll the /orders/{id} endpoint with the returned order id
Listen for order-related webhooks.

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.