Integration

Application Settings

Your application settings define the rules that govern how rewards are earned and redeemed, including cashback percentages, points conversion rates, redemption thresholds, and expiration policies. These settings are configured in the Otonum Rewards application and can be read programmatically through the API.

For operation details, see the API Reference.

Why Read Settings Through the API?

Your integration should know program rules so it can:

• Communicate accurately with members, for example: "You will earn 5% cashback on this purchase"
• Gate redemption correctly. Offer redemption only when the member is truly eligible; showing redemption below threshold creates friction and failures.
• Display expiration warnings when rewards expire, so members are informed before they lose value.

Cashback Settings

Cashback configuration exposes three controls that directly affect member UX:

Setting	How to use it in your integration
minimumRedemptionAmount	Show "Redeem cashback" only when member cashback balance is at or above this threshold. Voucher creation below this threshold fails.
earningCaps	Use it to compute and display exact reward preview for a transaction (for example: "Earn up to X cashback").
expiration	If defined, show expiration messaging in member portal. If None, urgency messaging is not needed.

Example response:

Code
{
  "expiration": "None",
  "minimumRedemptionAmount": 5.0,
  "earningCaps": 100.0
}

Field	Type	Description
expiration	string	Expiration policy: "None", "Month1", "Month3"
minimumRedemptionAmount	number	Minimum cashback balance required before redemption
earningCaps	number	Maximum cashback that can be earned per transaction

Error responses:

Status	Meaning
400	Cashback settings are not configured for this application
401	Invalid API key
409	Conflict. Settings are in an inconsistent state
429	Rate limit exceeded

Points Settings

Points configuration drives conversion calculations across your integration:

Setting	How to use it in your integration
minimumPointRequiredForRedemption	Gate "Redeem points" behind this threshold. Show missing gap to members (for example: "You need 80 more points to redeem").
minimumPointRequiredCashValue	Use as conversion rate for estimated reward value. Example: if minimumPointRequiredCashValue is 1.00 and minimumPointRequiredForRedemption is 100, then 1 point = 0.01.
expiration	Same as cashback. Show expiration messaging when defined.

Example response:

Code
{
  "expiration": "None",
  "minimumPointRequiredForRedemption": 100,
  "minimumPointRequiredCashValue": 1.0
}

Field	Type	Description
expiration	string	Expiration policy: "None", "Month1", "Month3"
minimumPointRequiredForRedemption	integer	Minimum points required before a redemption voucher can be created
minimumPointRequiredCashValue	number	Cash value of minimum redeemable points (example: 100 points = 1.00)

Error responses:

Status	Meaning
400	Points settings are not configured for this application
401	Invalid API key
409	Conflict. Settings are in an inconsistent state
429	Rate limit exceeded

Points Endpoint Contract

Use the points settings route documented in the API Reference to retrieve your application points configuration before enabling point redemption in checkout and profile experiences.

When to Fetch Settings

Settings are stable and rarely change. You do not need to fetch them on every transaction. A good pattern is:

1. Fetch once at startup (or daily with a scheduled job)
2. Cache the result in your service layer
3. Refresh on rule failure. If you receive unexpected threshold-related failures, refresh cache and retry once.

This keeps your integration responsive without unnecessary API calls.

Common Use Cases

Show Program Rules to Members

Fetch settings at app startup to display exact program terms to members. See the API Reference for route and payload details.

Cache Settings Server-Side

Program settings rarely change. Cache them server-side (for example for 1 hour) to avoid rate limit pressure:

Code
let settingsCache = null;
let expiresAt = 0;

async function getSettings() {
  if (Date.now() < expiresAt) return settingsCache;
  settingsCache = await fetchSettings();
  expiresAt = Date.now() + 60 * 60 * 1000; // 1 hour
  return settingsCache;
}