Skip to main content
GET
Get reward
Returns the reward, including current inventory. On UNIT_BASED rewards, committed_units is inventory in use, pending_units is awaiting fulfillment, and delivered_units is captured. On AMOUNT_BASED rewards, all three are null.
For usage patterns and examples, see the Rewards Catalog guide.

Authorizations

X-API-Key
string
header
required

API key passed in the X-API-Key header.

Path Parameters

programId
string<uuid>
required

Program ID

rewardId
string<uuid>
required

Reward ID

Response

Reward details

A reward with its pricing, inventory, availability, and metadata

asset_id
string<uuid>

Asset used to price this reward

Example:

"550e8400-e29b-41d4-a716-446655440002"

available_from
string<date-time>

Start of the availability window (RFC 3339, null if always available)

Example:

"2024-01-01T00:00:00Z"

available_until
string<date-time>

End of the availability window (RFC 3339, null if no end date)

Example:

"2024-12-31T23:59:59Z"

category
string

Grouping label for organizing rewards in the catalog

Example:

"Gift Cards"

committed_units
integer | null

UNIT_BASED units currently consuming inventory. Includes delivered and pending units. Null for AMOUNT_BASED rewards.

Example:

42

created_at
string<date-time>

When this reward was created (RFC 3339)

Example:

"2024-01-15T10:30:00Z"

delivered_units
integer | null

UNIT_BASED units whose redemption has been captured. Null for AMOUNT_BASED rewards.

Example:

39

description
string

Details about the reward

Example:

"Redeemable for a $10 gift card"

id
string<uuid>

Unique identifier for this reward

Example:

"550e8400-e29b-41d4-a716-446655440000"

max_per_participant
integer | null

Per-participant redemption limit (UNIT_BASED only, null = unlimited)

Example:

2

max_total
integer | null

Global inventory limit (UNIT_BASED only, null = unlimited)

Example:

100

metadata
object

Custom key-value data attached to this reward

name
string

Display name for this reward

Example:

"$10 Gift Card"

pending_units
integer | null

UNIT_BASED units awaiting fulfillment. Null for AMOUNT_BASED rewards.

Example:

3

program_id
string<uuid>

Program this reward belongs to

Example:

"550e8400-e29b-41d4-a716-446655440001"

redemption_type
string

How the reward is redeemed: UNIT_BASED (discrete quantities) or AMOUNT_BASED (variable amounts)

Example:

"UNIT_BASED"

status
string

Lifecycle status: DRAFT, ACTIVE, OUT_OF_STOCK, or ARCHIVED

Example:

"ACTIVE"

unit_cost
string

Cost per unit in the reward's asset (decimal string for precision)

Example:

"1000.00"

updated_at
string<date-time>

When this reward was last modified (RFC 3339)

Example:

"2024-01-15T10:30:00Z"