Skip to main content
GET
Get reward details

Authorizations

X-API-Key
string
header
required

Per-company partner API key (zupy_pk_…). Validated by Zupy against the company integration key hash (Story 14.x); send it on every request as the X-API-Key header. Scoped read-write to the owning company's data.

Path Parameters

id
string
required

Unique identifier for this reward.

Response

Available reward in the loyalty program catalog with points cost and validity details.

id
string
required
read-only
name
string
required
read-only
description
string
required
read-only
reward_type
enum<string>
required

Functional reward type. Use 'Generic' for rewards that don't fit other categories.

Available options:
other,
generic,
welcome,
return,
birthday,
surprise,
recovery,
gift
points_required
integer
required
read-only
monetary_value
string<decimal> | null
required
read-only

The approximate monetary value of this reward.

Pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
validity_days
integer
required
read-only

Number of days the reward is valid after redemption.

is_available
string
required
read-only
quantity_available
integer | null
required
read-only

Number of rewards available. Null means unlimited.

quantity_redeemed
integer
required
read-only

Number of rewards already redeemed.

discount_type
enum<string>
required

Type of discount applied when redeeming this reward

  • none - Nenhum
  • percentage - Percentage
  • fixed_amount - Fixed Amount
  • free_shipping - Free Shipping
  • free_item - Free Item
  • conditional - Conditional
Available options:
none,
percentage,
fixed_amount,
free_shipping,
free_item,
conditional
discount_percentage
string<decimal> | null
required
read-only

Percentage discount (e.g., 15.50 for 15.5%)

Pattern: ^-?\d{0,3}(?:\.\d{0,2})?$
discount_fixed_amount
string<decimal> | null
required
read-only

Fixed amount discount in currency

Pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
maximum_discount_value
string<decimal> | null
required
read-only

Maximum discount value (for percentage discounts)

Pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
image_url
string | null
required
read-only
program_id
string
required
read-only
program_name
string
required
read-only
is_active
boolean
required
read-only
already_redeemed
boolean
default:false
required
read-only
start_date
string<date-time> | null
required
read-only
end_date
string<date-time> | null
required
read-only
created_at
string<date-time>
required
read-only
updated_at
string<date-time>
required
read-only
settlement_budget
string<decimal> | null
read-only
Pattern: ^-?\d{0,10}(?:\.\d{0,2})?$
customer_split_pct
string
read-only

Customer's share of the settlement (hardcoded constant 50.00%).

operator_split_pct
string<decimal> | null
read-only

Reserved — always null in 2026-05 production data. This field is part of a 4-way settlement-split surface (customer / operator / publisher / sharer) intended for a future cross-merchant marketplace flow where Z$ payouts route to multiple parties on redemption. Today only customer_split_pct is populated (constant 50%); the operator/publisher/sharer fields exist in the schema but are not yet wired into the redemption pipeline. Do not write partner code that depends on a non-null value here yet.

Pattern: ^-?\d{0,3}(?:\.\d{0,2})?$
publisher_split_pct
string<decimal> | null
read-only

Reserved — always null in 2026-05 production data. Same caveat as operator_split_pct: part of the 4-way settlement surface, not yet wired. Documented here so the schema stays explicit about what's live and what's coming.

Pattern: ^-?\d{0,3}(?:\.\d{0,2})?$
sharer_split_pct
string<decimal> | null
read-only

Reserved — always null in 2026-05 production data. Same caveat as operator_split_pct / publisher_split_pct.

Pattern: ^-?\d{0,3}(?:\.\d{0,2})?$
z_distributed_total
string
read-only

Total Z$ already distributed via this reward (used_redemptions × settlement_budget). null for non-marketing rewards.

origin_type
string
read-only
budget_mode
string
read-only

How the campaign budget is enforced: 'unlimited' (no cap), 'per_redemption' (each redeem consumes settlement_budget Z$), or 'pooled' (shared across all redemptions).

campaign_status
string | null
read-only

Lifecycle of the campaign that hosts this reward (draft, active, paused, ended). null for non-marketing rewards.

campaign_operator_id
string | null
read-only

ID of the partner operator who created/operates this campaign (e.g. an aggregator running the marketing reward on behalf of a merchant). null for direct-merchant rewards.

campaign_operator_name
string | null
read-only

Human-readable name of the campaign operator (paired with campaign_operator_id).