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.

You can also pass one of the following magic values (case-insensitive):

BALANCE — pay from your Tremendous balance.
INVOICE — pay from your commercial invoice account.
INVOICE_THEN_BALANCE — pay from your commercial invoice account if doing so wouldn't exceed your credit limit, otherwise fall back to your Tremendous balance. The balance must have sufficient funds to pay for the order.

Note: INVOICE and INVOICE_THEN_BALANCE are only available to select Enterprise clients with an existing commercial invoicing setup. If your organization already uses commercial invoicing and you have questions, contact your Customer Success Manager.

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

expires_at

string date-time

Expiration date of the reward. If null, the reward does not expire.

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. Defaults to the organization's currency if not provided.

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 initial POST /orders response for a link reward includes the link in delivery.link.

The link must then be delivered to the recipient out-of-band.

To obtain a new link for an existing reward, call POST /rewards/{id}/generate_link.

PHONE Deliver the reward to the recipient by SMS

meta

object

Customizable reward delivery metadata, taking precedence over the related campaign settings.

Show object properties

Property	Type	Description
`sender_name`	string	The "sender name" used in the delivery. If it's an email reward, "via Tremendous" will be appended to the value. Please note that you cannot customize the sender email.
`subject_line`	string	The subject line used in the delivery.
`message`	string	The content of the message of the reward, shown in the email / SMS and on the landing page.

### 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](https://developers.tremendous.com/reference/list-funding-sources). The Tremendous API sandbox environment comes with a single funding source that allows you to spend up to $100,000 in *fake money* to test the API. [Learn more about the sandbox environment](https://developers.tremendous.com/docs/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 not create a new order. If the payload is the same as a previously issued order, our API will return a `201` response code, along with a representation of the already-existing order in the response body. If the `external_id` used is for an order with different parameters (e.g. amount, recipient), our API will return a `409` response code, indicating a conflicting resource.

200The created API key

401Authorization error, for example due to an invalid or missing API key, or because the API key is restricted to a different source IP address.

404No resource could be found for the provided ID

429Rate limit exceeded, this request was not processed. Future requests may not be processed until your account drops below the rate limit threshold

500The server encountered an unexpected error or couldn't fulfill the request in time.