openapi: 3.1.0
info:
title: Tremendous API
description: >-
The Tremendous API allows businesses to send rewards, incentives, and
payouts worldwide. Access 2000+ payout methods including gift cards,
prepaid Visa/Mastercard, PayPal, Venmo, bank transfers, and charity
donations. Supports multi-product rewards (recipient chooses from a
catalog) and single-product rewards (fixed payout method). Authentication
uses Bearer API key or OAuth 2.0.
version: '2.0'
contact:
name: Tremendous Support
url: https://developers.tremendous.com
email: [email protected]
license:
name: Proprietary
termsOfService: https://www.tremendous.com/terms
servers:
- url: https://testflight.tremendous.com/api/v2
description: Sandbox (testing)
- url: https://www.tremendous.com/api/v2
description: Production
tags:
- name: Orders
description: Create and manage reward orders
- name: Rewards
description: Manage individual rewards within orders
- name: Products
description: Browse available payout products and gift cards
- name: Funding Sources
description: Manage funding sources for sending rewards
- name: Campaigns
description: Manage reward presentation and product catalogs
- name: Organizations
description: Manage organizations (team accounts)
- name: Members
description: Manage organization members
- name: Invoices
description: View and manage invoices
- name: Webhooks
description: Configure webhook notifications
security:
- BearerAuth: []
paths:
/orders:
get:
operationId: listOrders
summary: List Orders
description: Returns a paginated list of all orders in the organization.
tags:
- Orders
parameters:
- name: offset
in: query
description: Pagination offset
schema:
type: integer
default: 0
- name: limit
in: query
description: Maximum number of results to return (max 100)
schema:
type: integer
default: 10
maximum: 100
- name: created_at_gte
in: query
description: Filter orders created at or after this date
schema:
type: string
format: date-time
- name: created_at_lte
in: query
description: Filter orders created at or before this date
schema:
type: string
format: date-time
responses:
'200':
description: List of orders
content:
application/json:
schema:
type: object
properties:
orders:
type: array
items:
$ref: '#/components/schemas/Order'
total_count:
type: integer
'401':
description: Unauthorized
'429':
description: Rate limit exceeded
post:
operationId: createOrder
summary: Create Order
description: >-
Create a new order to send one or more rewards. An order contains
rewards, a funding source, and optional external ID for idempotency.
tags:
- Orders
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrderRequest'
responses:
'200':
description: Order created successfully
content:
application/json:
schema:
type: object
properties:
order:
$ref: '#/components/schemas/Order'
'400':
description: Bad request - validation error
'401':
description: Unauthorized
'402':
description: Insufficient funds
'409':
description: Conflict - duplicate external_id
'422':
description: Unprocessable entity
'429':
description: Rate limit exceeded
/orders/{id}:
get:
operationId: getOrder
summary: Get Order
description: Retrieve details of a specific order by its ID.
tags:
- Orders
parameters:
- name: id
in: path
required: true
description: Order ID
schema:
type: string
responses:
'200':
description: Order details
content:
application/json:
schema:
type: object
properties:
order:
$ref: '#/components/schemas/Order'
'401':
description: Unauthorized
'404':
description: Order not found
/orders/approve:
post:
operationId: approveOrder
summary: Approve Order
description: Approve a pending order that requires manual approval.
tags:
- Orders
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Order ID to approve
required:
- id
responses:
'200':
description: Order approved
'401':
description: Unauthorized
'404':
description: Order not found
/rewards/{id}:
get:
operationId: getReward
summary: Get Reward
description: Retrieve details of a specific reward by its ID.
tags:
- Rewards
parameters:
- name: id
in: path
required: true
description: Reward ID
schema:
type: string
responses:
'200':
description: Reward details
content:
application/json:
schema:
type: object
properties:
reward:
$ref: '#/components/schemas/Reward'
'401':
description: Unauthorized
'404':
description: Reward not found
/rewards/{id}/resend:
post:
operationId: resendReward
summary: Resend Reward
description: Resend the delivery for a reward (e.g., resend the email).
tags:
- Rewards
parameters:
- name: id
in: path
required: true
description: Reward ID
schema:
type: string
responses:
'200':
description: Reward resent
'401':
description: Unauthorized
'404':
description: Reward not found
/products:
get:
operationId: listProducts
summary: List Products
description: >-
Returns a list of available payout products (gift cards, prepaid cards,
PayPal, bank transfers, charity donations, etc.).
tags:
- Products
parameters:
- name: country
in: query
description: Filter by country (ISO 3166-1 alpha-2)
schema:
type: string
- name: currency_codes
in: query
description: Filter by currency code (comma-separated)
schema:
type: string
responses:
'200':
description: List of products
content:
application/json:
schema:
type: object
properties:
products:
type: array
items:
$ref: '#/components/schemas/Product'
'401':
description: Unauthorized
/funding_sources:
get:
operationId: listFundingSources
summary: List Funding Sources
description: Returns a list of available funding sources for the organization.
tags:
- Funding Sources
responses:
'200':
description: List of funding sources
content:
application/json:
schema:
type: object
properties:
funding_sources:
type: array
items:
$ref: '#/components/schemas/FundingSource'
'401':
description: Unauthorized
/campaigns:
get:
operationId: listCampaigns
summary: List Campaigns
description: Returns a list of all campaigns in the organization.
tags:
- Campaigns
responses:
'200':
description: List of campaigns
content:
application/json:
schema:
type: object
properties:
campaigns:
type: array
items:
$ref: '#/components/schemas/Campaign'
'401':
description: Unauthorized
/campaigns/{id}:
get:
operationId: getCampaign
summary: Get Campaign
description: Retrieve details of a specific campaign by its ID.
tags:
- Campaigns
parameters:
- name: id
in: path
required: true
description: Campaign ID
schema:
type: string
responses:
'200':
description: Campaign details
content:
application/json:
schema:
type: object
properties:
campaign:
$ref: '#/components/schemas/Campaign'
'401':
description: Unauthorized
'404':
description: Campaign not found
/organizations:
get:
operationId: listOrganizations
summary: List Organizations
description: Returns a list of organizations accessible to the authenticated member.
tags:
- Organizations
responses:
'200':
description: List of organizations
content:
application/json:
schema:
type: object
properties:
organizations:
type: array
items:
$ref: '#/components/schemas/Organization'
'401':
description: Unauthorized
post:
operationId: createOrganization
summary: Create Organization
description: Create a new organization (sub-account) within the platform.
tags:
- Organizations
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Organization name
website:
type: string
description: Organization website URL
required:
- name
responses:
'201':
description: Organization created
content:
application/json:
schema:
type: object
properties:
organization:
$ref: '#/components/schemas/Organization'
'401':
description: Unauthorized
/organizations/{id}:
get:
operationId: getOrganization
summary: Get Organization
description: Retrieve details of a specific organization.
tags:
- Organizations
parameters:
- name: id
in: path
required: true
description: Organization ID
schema:
type: string
responses:
'200':
description: Organization details
content:
application/json:
schema:
type: object
properties:
organization:
$ref: '#/components/schemas/Organization'
'401':
description: Unauthorized
'404':
description: Organization not found
/members:
get:
operationId: listMembers
summary: List Members
description: Returns a list of members in the organization.
tags:
- Members
responses:
'200':
description: List of members
content:
application/json:
schema:
type: object
properties:
members:
type: array
items:
$ref: '#/components/schemas/Member'
'401':
description: Unauthorized
post:
operationId: createMember
summary: Create Member
description: Invite a new member to the organization.
tags:
- Members
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
email:
type: string
format: email
description: Member email address
name:
type: string
description: Member full name
role:
type: string
enum: [MEMBER, ADMIN]
description: Member role
required:
- email
- name
responses:
'201':
description: Member created
'401':
description: Unauthorized
/invoices:
get:
operationId: listInvoices
summary: List Invoices
description: Returns a list of invoices for the organization.
tags:
- Invoices
parameters:
- name: offset
in: query
schema:
type: integer
default: 0
- name: limit
in: query
schema:
type: integer
default: 10
responses:
'200':
description: List of invoices
content:
application/json:
schema:
type: object
properties:
invoices:
type: array
items:
$ref: '#/components/schemas/Invoice'
'401':
description: Unauthorized
/invoices/{id}:
get:
operationId: getInvoice
summary: Get Invoice
description: Retrieve details of a specific invoice.
tags:
- Invoices
parameters:
- name: id
in: path
required: true
description: Invoice ID
schema:
type: string
responses:
'200':
description: Invoice details
content:
application/json:
schema:
type: object
properties:
invoice:
$ref: '#/components/schemas/Invoice'
'401':
description: Unauthorized
'404':
description: Invoice not found
/webhooks:
get:
operationId: listWebhooks
summary: List Webhooks
description: Returns webhook configuration for the organization.
tags:
- Webhooks
responses:
'200':
description: Webhook configuration
content:
application/json:
schema:
type: object
properties:
webhooks:
type: array
items:
$ref: '#/components/schemas/Webhook'
'401':
description: Unauthorized
post:
operationId: createWebhook
summary: Create Webhook
description: Configure a webhook endpoint for the organization.
tags:
- Webhooks
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
url:
type: string
format: uri
description: Webhook endpoint URL
private_key:
type: string
description: Private key for HMAC signature verification
required:
- url
responses:
'201':
description: Webhook created
content:
application/json:
schema:
type: object
properties:
webhook:
$ref: '#/components/schemas/Webhook'
'401':
description: Unauthorized
/webhooks/{id}:
get:
operationId: getWebhook
summary: Get Webhook
description: Retrieve details of a specific webhook configuration.
tags:
- Webhooks
parameters:
- name: id
in: path
required: true
description: Webhook ID
schema:
type: string
responses:
'200':
description: Webhook details
content:
application/json:
schema:
type: object
properties:
webhook:
$ref: '#/components/schemas/Webhook'
'401':
description: Unauthorized
'404':
description: Webhook not found
delete:
operationId: deleteWebhook
summary: Delete Webhook
description: Remove a webhook configuration from the organization.
tags:
- Webhooks
parameters:
- name: id
in: path
required: true
description: Webhook ID
schema:
type: string
responses:
'200':
description: Webhook deleted
'401':
description: Unauthorized
'404':
description: Webhook not found
/webhooks/{id}/simulate:
post:
operationId: simulateWebhook
summary: Simulate Webhook
description: Send a test event to the webhook endpoint to verify connectivity.
tags:
- Webhooks
parameters:
- name: id
in: path
required: true
description: Webhook ID
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
event:
type: string
description: "Event type to simulate (e.g., ORDERS.COMPLETED)"
required:
- event
responses:
'200':
description: Simulation sent
'401':
description: Unauthorized
'404':
description: Webhook not found
components:
schemas:
Order:
type: object
properties:
id:
type: string
description: Unique order identifier
external_id:
type: string
description: Customer-provided external reference for idempotency
status:
type: string
enum: [DRAFT, PENDING_APPROVAL, APPROVED, PROCESSING, DONE, FAILED]
description: Order status
payment:
type: object
properties:
funding_source_id:
type: string
subtotal:
type: object
properties:
currency_code:
type: string
value:
type: number
total:
type: object
properties:
currency_code:
type: string
value:
type: number
rewards:
type: array
items:
$ref: '#/components/schemas/Reward'
created_at:
type: string
format: date-time
CreateOrderRequest:
type: object
properties:
external_id:
type: string
description: Reference for idempotency and retrieval
payment:
type: object
properties:
funding_source_id:
type: string
description: "Funding source ID or 'balance'"
required:
- funding_source_id
reward:
$ref: '#/components/schemas/RewardInput'
required:
- payment
- reward
Reward:
type: object
properties:
id:
type: string
description: Unique reward identifier
order_id:
type: string
description: Parent order ID
status:
type: string
enum: [PENDING, PROCESSING, DELIVERED, FAILED, CANCELED]
description: Reward delivery status
value:
type: object
properties:
denomination:
type: number
description: Reward amount
currency_code:
type: string
description: Currency code (e.g., USD)
recipient:
$ref: '#/components/schemas/Recipient'
delivery:
type: object
properties:
method:
type: string
enum: [EMAIL, LINK, PHONE]
status:
type: string
delivered_at:
type: string
format: date-time
campaign_id:
type: string
description: Campaign used for this reward
created_at:
type: string
format: date-time
RewardInput:
type: object
properties:
value:
type: object
properties:
denomination:
type: number
currency_code:
type: string
required:
- denomination
- currency_code
recipient:
$ref: '#/components/schemas/Recipient'
delivery:
type: object
properties:
method:
type: string
enum: [EMAIL, LINK, PHONE]
default: EMAIL
campaign_id:
type: string
description: Campaign ID (defines product catalog)
products:
type: array
items:
type: string
description: Product IDs (alternative to campaign_id)
language:
type: string
description: ISO-639-1 language code for recipient communication
Recipient:
type: object
properties:
name:
type: string
description: Recipient full name
email:
type: string
format: email
description: Recipient email address
phone:
type: string
description: Recipient phone number (for SMS delivery)
required:
- name
- email
Product:
type: object
properties:
id:
type: string
description: Unique product identifier
name:
type: string
description: Product name (e.g., Amazon.com)
category:
type: string
enum: [GIFT_CARD, PREPAID_CARD, BANK_TRANSFER, PAYPAL, VENMO, CHARITY, CRYPTOCURRENCY]
description: Product category
currency_codes:
type: array
items:
type: string
description: Supported currency codes
countries:
type: array
items:
type: object
properties:
abbr:
type: string
name:
type: string
description: Countries where product is available
skus:
type: array
items:
type: object
properties:
min:
type: number
max:
type: number
denomination:
type: number
description: Available denominations/value ranges
image_url:
type: string
format: uri
description: Product logo/image URL
FundingSource:
type: object
properties:
id:
type: string
description: Unique funding source identifier
method:
type: string
enum: [BALANCE, INVOICE, CREDIT_CARD, ACH]
description: Funding method type
meta:
type: object
description: Additional metadata (account details, etc.)
balance:
type: object
properties:
currency_code:
type: string
amount:
type: number
description: Current balance (for balance funding source)
Campaign:
type: object
properties:
id:
type: string
description: Unique campaign identifier
name:
type: string
description: Campaign name
description:
type: string
description: Campaign description shown to recipients
email_style:
type: object
properties:
logo:
type: string
format: uri
subject:
type: string
body:
type: string
description: Email branding and messaging
products:
type: array
items:
type: string
description: Product IDs available in this campaign
Organization:
type: object
properties:
id:
type: string
description: Unique organization identifier
name:
type: string
description: Organization name
website:
type: string
format: uri
description: Organization website
with_api_credentials:
type: boolean
description: Whether organization has API credentials enabled
status:
type: string
enum: [ACTIVE, INACTIVE]
description: Organization status
Member:
type: object
properties:
id:
type: string
description: Unique member identifier
name:
type: string
description: Member full name
email:
type: string
format: email
description: Member email address
role:
type: string
enum: [MEMBER, ADMIN]
description: Member role
status:
type: string
enum: [ACTIVE, PENDING, INACTIVE]
description: Membership status
Invoice:
type: object
properties:
id:
type: string
description: Unique invoice identifier
po_number:
type: string
description: Purchase order number
amount:
type: object
properties:
currency_code:
type: string
value:
type: number
description: Invoice amount
remaining:
type: object
properties:
currency_code:
type: string
value:
type: number
description: Remaining balance on invoice
status:
type: string
enum: [PENDING, PAID, PARTIAL, OVERDUE, CANCELED]
description: Invoice status
created_at:
type: string
format: date-time
due_at:
type: string
format: date-time
Webhook:
type: object
properties:
id:
type: string
description: Unique webhook identifier
url:
type: string
format: uri
description: Webhook endpoint URL
events:
type: array
items:
type: string
description: Event types this webhook receives
created_at:
type: string
format: date-time
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
Bearer token authentication using a Tremendous API key.
Generate API keys in your Tremendous dashboard Settings > API.
OAuth2:
type: oauth2
description: OAuth 2.0 for third-party integrations
flows:
authorizationCode:
authorizationUrl: https://www.tremendous.com/oauth/authorize
tokenUrl: https://www.tremendous.com/oauth/token
scopes:
read: Read access to orders, rewards, products, and funding sources
write: Create orders and rewards
manage: Manage organization settings, members, and webhooks