Rewards Store

The Rewards Store lets your users spend their earned points to get real prizes. Think of it like a shop inside your app where players can browse available rewards, pick what they want, and redeem their points for it.

What You Can Do

For Your Users

• Browse rewards - See what prizes are available and how many points each costs
• Purchase rewards - Spend points to get a reward
• View order history - Check past purchases and their status
• Claim pending rewards - Some rewards need extra info (like a phone number or shipping address) before delivery

For Your Admins

• Create rewards - Add new prizes to your store (airtime, merchandise, vouchers, etc.)
• Set prices - Choose how many points each reward costs
• Manage stock - Set limits on how many of each prize are available
• Grant rewards - Give prizes directly to users (for promotions, customer service, etc.)
• Track orders - See all purchases and update their status

How It Works

1. Setting Up Your Rewards

First, add rewards to your catalog. Each reward can have different options (called "variants").

Example: Mobile Airtime

• Reward: "Airtime Top-up"
• Variants:
  • 10 ETB airtime → 100 points
  • 25 ETB airtime → 250 points
  • 50 ETB airtime → 500 points

Example: Branded T-Shirt

• Reward: "Phoenix T-Shirt"
• Variants:
  • Small → 1,000 points
  • Medium → 1,000 points
  • Large → 1,000 points

2. Users Browse the Store

Users can see all available rewards with:

• Name and description
• Picture (optional)
• Available options and their prices
• Whether it's in stock

3. Users Make a Purchase

When a user wants to redeem their points:

1. They pick a reward and select which option they want
2. They may need to fill in some information (like their phone number)
3. The system checks if they have enough points
4. Points are deducted and the order is created

4. Reward Delivery

What happens next depends on the type of reward:

5. Order Status Updates

Users can track their orders:

• Waiting - Order received, waiting to be processed
• Processing - Being prepared for delivery
• Completed - Successfully delivered
• Failed - Something went wrong (user can retry or get refund)

Creating Rewards (Admin Guide)

Use the Admin Gateway to add rewards to your catalog.

Add a New Reward

Send a request to create a reward with its options:

Example: Airtime Top-up

POST /v1/rewards-catalog?tenant_id=${tenant_id}

{
  "slug": "airtime",
  "name": "Airtime Top-up",
  "description": "Mobile phone airtime credit",
  "fields": [
    {
      "name": "phone",
      "label": "Phone Number",
      "required": true,
      "placeholder": "0912345678"
    }
  ],
  "variants": [
    {
      "variant_id": "10",
      "label": "10 ETB",
      "purchase": {
        "prices": [{"currency": "POINTS", "amount": 100}]
      }
    },
    {
      "variant_id": "25",
      "label": "25 ETB",
      "purchase": {
        "prices": [{"currency": "POINTS", "amount": 250}]
      },
      "stock": 100
    }
  ]
}

View Your Rewards

GET /v1/rewards-catalog?tenant_id=${tenant_id}

Granting Rewards (Admin Guide)

Sometimes you want to give rewards directly to users without them spending points:

• Customer service gesture
• Contest prizes
• Promotional campaigns
• Bug compensation

Grant a Reward

POST /v1/grants?tenant_id=${tenant_id}

{
  "user_id": "user_123",
  "reward_id": "reward-uuid-here",
  "variant_id": "25",
  "source_type": "admin",
  "source_ref": "customer_support_ticket_456"
}

The user will see this reward in their order history and can claim it if needed.

User-Facing Features

Your app can use these to build the store experience for users.

List Available Rewards

Show users what they can purchase (Query Gateway; tenant from JWT):

GET /v1/rewards-store

Returns all active rewards with their prices and stock availability.

Get Reward Details

Show full details for a specific reward:

GET /v1/rewards-store/{slug}

Returns the reward with all its options, required fields, and stock info.

Purchase a Reward

When a user wants to buy:

POST /v1/rewards-store/{slug}/purchase

{
  "user_id": "user_123",
  "variant_id": "25",
  "currency": "POINTS",
  "fields": {
    "phone": "0912345678"
  },
  "idempotency_key": "purchase-abc123"
}

View Order History

Show users their past purchases:

GET /v1/orders/user/{user_id}

Claim a Pending Reward

For rewards that need user input before delivery:

POST /v1/orders/{order_id}/claim

{
  "user_id": "user_123",
  "fields": {
    "size": "Large",
    "address": "123 Main St, Addis Ababa"
  }
}

Delivery Types Explained

Instant Delivery (Internal)

Best for: Badges, in-app currency, virtual items

These are delivered immediately when purchased. No user action needed after purchase.

External Delivery (Your System Handles It)

Best for: Airtime, voucher codes, digital goods

When a user purchases:

1. Phoenix sends a request to your system
2. Your system delivers the reward
3. Your system tells Phoenix if it worked

This requires you to set up a webhook endpoint.

Manual Delivery

Best for: Physical merchandise, event tickets, high-value prizes

When a user purchases:

1. The order appears in your admin panel
2. Your team processes the order manually
3. Your team marks it as shipped/completed

User Experience Flow

Browsing the Store

Your app calls the store to get available rewards:

What Users See:

🎁 Airtime Top-up
   Mobile phone credit
   
   Options:
   • 10 ETB - 100 points
   • 25 ETB - 250 points ✓ In Stock (42 left)
   • 50 ETB - 500 points ✓ In Stock (18 left)

👕 Phoenix T-Shirt  
   Official branded merchandise
   
   Options:
   • Any Size - 1,000 points ✓ In Stock (50 left)

Making a Purchase

1. User selects "25 ETB Airtime"
2. System asks for phone number (required for airtime)
3. User enters: 0912345678
4. User confirms purchase
5. 250 points deducted, order created
6. Phoenix sends request to your airtime service
7. User receives airtime on their phone

Checking Order History

Users can see all their past purchases:

📱 25 ETB Airtime
   Purchased: Jan 9, 2026
   Status: ✅ Completed
   
👕 Phoenix T-Shirt (Large)
   Purchased: Jan 8, 2026
   Status: 📦 Shipped - Tracking: DHL123456
   
🏆 Champion Badge
   Granted: Jan 7, 2026
   Status: ⏳ Waiting for you to claim

Claiming a Pending Reward

Some rewards (like physical items or contest prizes) need the user to provide information before delivery:

🏆 Champion Badge - Ready to Claim!

You won this badge in the Weekly Challenge.
Claim it before Jan 14 to add it to your profile.

[Claim Now]

Managing Orders (Admin Guide)

View All Orders

GET /v1/reward-orders?tenant_id=${tenant_id}

You can filter by status, user, or reward.

Update Order Status

For manual fulfillment, update the status when you ship or complete:

PUT /v1/reward-orders/{order_id}?tenant_id=${tenant_id}

{
  "status": {
    "state": "completed",
    "tracking_number": "DHL123456",
    "notes": "Shipped via DHL Express"
  }
}

Retry a Failed Order

POST /v1/reward-orders/{order_id}/retry?tenant_id=${tenant_id}

Refund an Order

POST /v1/reward-orders/{order_id}/refund?tenant_id=${tenant_id}

{
  "reason": "Customer requested cancellation"
}

Best Practices

Setting Up Your Store

1. Start with simple rewards - Add a few digital rewards first to test the flow
2. Use clear names - "50 ETB Airtime" is better than "Tier 3 Mobile Credit"
3. Add images - Visual rewards are more appealing
4. Set realistic stock - Don't promise what you can't deliver

Managing Inventory

1. Monitor stock levels - Get alerts when stock is low
2. Plan for demand - Popular rewards sell out quickly after campaigns
3. Update regularly - Remove expired items, add seasonal rewards

Handling Issues

1. Failed deliveries - Most failed orders can be retried automatically
2. Refunds - You can refund points for orders that couldn't be fulfilled
3. Customer support - Use the admin panel to check order details and help users

Quick Reference

Order Statuses

Reward Types

Next Steps

• Events and Integration - Required for external delivery webhooks
• Creating Leaderboards - Award rewards to top players
• Creating Streaks - Reward daily engagement