RibiRewards API

Send gifts across Africa programmatically. RESTful API with webhooks, white-label support, and comprehensive error handling.

Fast Integration

Go live in hours with simple REST endpoints

10+ Countries

Pan-African coverage with local fulfillment

White-Label

Full branding customization included

Base URL

Production

https://api.ribirewards.com/v1

Sandbox

https://sandbox-api.ribirewards.com/v1

Authentication

Authenticate your API requests using Bearer tokens. Get your API key from your dashboard.

Getting Your API Key

Log in to your dashboard
Navigate to Settings → API Keys
Click "Generate New Key"
Copy and securely store your key

Important:

API keys are shown only once. Store them securely and never commit them to version control.

Making Authenticated Requests

cURL

curl https://api.ribirewards.com/v1/choice-cards \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "coffee",
    "amount": 50,
    "recipients": [{"email": "employee@company.com"}]
  }'

Quick Start

Send your first gift in 5 minutes. Here's a complete example.

Complete Example: Send a Coffee Gift Card

This will send a $50 coffee gift card to one recipient with your branding.

JavaScript

const fetch = require('node-fetch');

const sendGift = async () => {
  const response = await fetch('https://api.ribirewards.com/v1/choice-cards', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      category: 'coffee',
      amount: 50,
      recipients: [
        { email: 'employee@company.com', name: 'John Doe' }
      ],
      branding: {
        company_name: 'Your Company',
        from_email: 'rewards@yourcompany.com',
        message: 'Thanks for your hard work!'
      }
    })
  });

  const data = await response.json();
  console.log('Order ID:', data.order_id);
  console.log('Status:', data.status);
};

sendGift();

Choice Cards

Send category-based gift cards. Recipients choose products within their budget from 100+ categories.

POST/v1/choice-cards

Create and send choice-based gift cards to one or more recipients.

Request Parameters

Parameter	Type	Required	Description
`category`	string	REQUIRED	Gift category: `coffee`, `wine`, `fashion`, `golf`, `home`, `beauty`, `books`, `gourmet`
`amount`	integer	REQUIRED	Gift value in USD ($10-$1000)
`recipients`	array	REQUIRED	Array of recipient objects with `email` and optional `name`
`branding`	object	OPTIONAL	Branding customization: `company_name`, `logo_url`, `from_email`, `message`
`validity_days`	integer	OPTIONAL	Days until expiry (default: 90, max: 365)
`metadata`	object	OPTIONAL	Custom key-value pairs for your reference

Response

200 OK - Success

{
  "order_id": "RG-CC-2026-0127-001",
  "status": "sent",
  "category": "coffee",
  "amount": 50,
  "recipients_count": 1,
  "total_cost": 50.00,
  "created_at": "2026-01-27T10:30:00Z",
  "expires_at": "2026-04-27T10:30:00Z",
  "recipient_links": [
    {
      "email": "employee@company.com",
      "redemption_url": "https://redeem.ribirewards.com/abc123def456",
      "status": "sent"
    }
  ]
}

Gift Boxes

Send curated physical gift boxes delivered to recipients' addresses.

POST/v1/gift-boxes

Order physical gift boxes with delivery to specified addresses.

Available Box Types

corporate_welcome

Corporate Welcome Box - $45

box_type: "corporate_welcome"

executive_appreciation

Executive Appreciation - $120

box_type: "executive_appreciation"

holiday_celebration

Holiday Celebration - $65

box_type: "holiday_celebration"

new_parent_care

New Parent Care - $55

box_type: "new_parent_care"

Example Request

Request

{
  "box_type": "corporate_welcome",
  "recipients": [
    {
      "name": "Jane Smith",
      "email": "jane@company.com",
      "address": {
        "street": "123 Main Street",
        "city": "Lagos",
        "state": "Lagos",
        "postal_code": "100001",
        "country": "NG"
      }
    }
  ],
  "branding": {
    "company_name": "Your Company",
    "include_logo": true,
    "card_message": "Welcome to the team!"
  },
  "delivery_date": "2026-02-10"
}

Spa Experiences

Send spa and wellness experiences. Recipients book at their preferred spa from 1,000+ verified vendors.

POST/v1/experiences

Send spa experience gifts with self-booking capabilities.

Experience Packages

single_treatment

One spa service - $30-$80

spa_day

Multiple treatments - $100-$200

couples_experience

Spa day for two - $150-$300

premium_wellness

Full-day luxury - $250-$500

Example Request

Request

{
  "package": "spa_day",
  "amount": 150,
  "recipients": [
    {
      "email": "employee@company.com",
      "name": "Sarah Johnson"
    }
  ],
  "location_preference": "johannesburg",
  "validity_days": 90,
  "branding": {
    "company_name": "Your Company",
    "message": "Take time for yourself!"
  }
}

Orders

Retrieve order information and track redemption status.

GET/v1/orders/:order_id

Get detailed information about a specific order.

Response

200 OK

{
  "order_id": "RG-CC-2026-0127-001",
  "type": "choice_card",
  "status": "active",
  "category": "coffee",
  "amount": 50,
  "recipients_count": 1,
  "redeemed_count": 0,
  "redemption_rate": 0,
  "created_at": "2026-01-27T10:30:00Z",
  "expires_at": "2026-04-27T10:30:00Z",
  "recipients": [
    {
      "email": "employee@company.com",
      "name": "John Doe",
      "status": "sent",
      "sent_at": "2026-01-27T10:30:15Z",
      "redeemed_at": null,
      "redemption_url": "https://redeem.ribirewards.com/abc123"
    }
  ]
}

List All Orders

GET/v1/orders

List all orders with optional filtering.

Query Parameters:

?status=active - Filter by status
?type=choice_card - Filter by type
?limit=50 - Results per page (max 100)
?page=2 - Pagination

Webhooks

Receive real-time notifications when gifts are sent, redeemed, or expired.

Setting Up Webhooks

Navigate to Settings → Webhooks in your dashboard
Add your webhook endpoint URL (must be HTTPS)
Select which events you want to receive
Save and copy your webhook secret

Available Events

gift.sent

Gift email has been sent to recipient

gift.redeemed

Recipient has redeemed their gift

gift.expired

Gift has expired without redemption

order.completed

All recipients in an order have redeemed

Webhook Payload Example

gift.redeemed event

{
  "event": "gift.redeemed",
  "timestamp": "2026-01-27T14:22:00Z",
  "data": {
    "order_id": "RG-CC-2026-0127-001",
    "recipient_email": "employee@company.com",
    "recipient_name": "John Doe",
    "gift_type": "choice_card",
    "category": "coffee",
    "amount": 50,
    "redeemed_at": "2026-01-27T14:21:45Z",
    "products_selected": [
      {
        "name": "Ethiopian Yirgacheffe Coffee",
        "price": 18.99
      },
      {
        "name": "French Press",
        "price": 29.99
      }
    ]
  }
}

Error Handling

The API uses standard HTTP response codes and returns detailed error messages in JSON format.

HTTP Status Codes

200

Request succeeded

400

Bad Request

Invalid parameters or missing required fields

401

Unauthorized

Invalid or missing API key

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Something went wrong on our end

Error Response Format

400 Bad Request

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid category. Must be one of: coffee, wine, fashion, golf, home, beauty, books, gourmet",
    "param": "category",
    "type": "validation_error"
  }
}

White-Labeling

Customize the recipient experience with your branding. All gift redemption pages can be fully white-labeled.

Full Branding Control

Recipients see your company name, logo, colors, and messaging throughout their entire gift experience.

Custom email branding
Branded redemption pages
Your domain (CNAME support)
Custom color schemes

Branding Object

Full branding configuration

{
  "branding": {
    "company_name": "Merit Incentives",
    "logo_url": "https://yourcompany.com/logo.png",
    "from_email": "rewards@meritincentives.com",
    "reply_to_email": "support@meritincentives.com",
    "primary_color": "#2563eb",
    "message": "Congratulations on your achievement!",
    "email_footer": "Questions? Contact us at support@meritincentives.com"
  }
}

Custom Domain: Contact support to set up CNAME records for fully branded redemption URLs (e.g., gifts.yourcompany.com)

Rate Limits

API requests are rate limited to ensure fair usage and system stability.

Current Limits

Standard Tier

100 req/min

Free and paid accounts

Enterprise Tier

1000 req/min

Contact sales for enterprise access

Rate Limit Headers

Every API response includes rate limit information:

Response Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1706358000

Sandbox Environment

Test your integration without sending real gifts or incurring charges.

Safe Testing Environment

The sandbox mirrors production but doesn't send real emails or charge your account. Perfect for development and testing.

Sandbox Base URL

Sandbox URL

https://sandbox-api.ribirewards.com/v1

Testing Tips

Use test API keys (start with test_)
Emails sent in sandbox are logged but not delivered
Access sandbox orders in dashboard → Sandbox Orders
Simulate webhooks using test endpoints

Need Help Integrating?

Our developer support team is here to help you get up and running quickly.

Email Developer Support Get API Key

RibiRewards API

Send gifts across Africa programmatically. RESTful API with webhooks, white-label support, and comprehensive error handling.

Fast Integration

Go live in hours with simple REST endpoints

10+ Countries

Pan-African coverage with local fulfillment

White-Label

Full branding customization included

Base URL

Production

https://api.ribirewards.com/v1

Sandbox

https://sandbox-api.ribirewards.com/v1

Authentication

Authenticate your API requests using Bearer tokens. Get your API key from your dashboard.

Getting Your API Key

Log in to your dashboard
Navigate to Settings → API Keys
Click "Generate New Key"
Copy and securely store your key

Important:

API keys are shown only once. Store them securely and never commit them to version control.

Making Authenticated Requests

cURL

curl https://api.ribirewards.com/v1/choice-cards \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "coffee",
    "amount": 50,
    "recipients": [{"email": "employee@company.com"}]
  }'

Quick Start

Send your first gift in 5 minutes. Here's a complete example.

Complete Example: Send a Coffee Gift Card

This will send a $50 coffee gift card to one recipient with your branding.

JavaScript

const fetch = require('node-fetch');

const sendGift = async () => {
  const response = await fetch('https://api.ribirewards.com/v1/choice-cards', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      category: 'coffee',
      amount: 50,
      recipients: [
        { email: 'employee@company.com', name: 'John Doe' }
      ],
      branding: {
        company_name: 'Your Company',
        from_email: 'rewards@yourcompany.com',
        message: 'Thanks for your hard work!'
      }
    })
  });

  const data = await response.json();
  console.log('Order ID:', data.order_id);
  console.log('Status:', data.status);
};

sendGift();

Choice Cards

Send category-based gift cards. Recipients choose products within their budget from 100+ categories.

POST/v1/choice-cards

Create and send choice-based gift cards to one or more recipients.

Request Parameters

Parameter	Type	Required	Description
`category`	string	REQUIRED	Gift category: `coffee`, `wine`, `fashion`, `golf`, `home`, `beauty`, `books`, `gourmet`
`amount`	integer	REQUIRED	Gift value in USD ($10-$1000)
`recipients`	array	REQUIRED	Array of recipient objects with `email` and optional `name`
`branding`	object	OPTIONAL	Branding customization: `company_name`, `logo_url`, `from_email`, `message`
`validity_days`	integer	OPTIONAL	Days until expiry (default: 90, max: 365)
`metadata`	object	OPTIONAL	Custom key-value pairs for your reference

Response

200 OK - Success

{
  "order_id": "RG-CC-2026-0127-001",
  "status": "sent",
  "category": "coffee",
  "amount": 50,
  "recipients_count": 1,
  "total_cost": 50.00,
  "created_at": "2026-01-27T10:30:00Z",
  "expires_at": "2026-04-27T10:30:00Z",
  "recipient_links": [
    {
      "email": "employee@company.com",
      "redemption_url": "https://redeem.ribirewards.com/abc123def456",
      "status": "sent"
    }
  ]
}

Gift Boxes

Send curated physical gift boxes delivered to recipients' addresses.

POST/v1/gift-boxes

Order physical gift boxes with delivery to specified addresses.

Available Box Types

corporate_welcome

Corporate Welcome Box - $45

box_type: "corporate_welcome"

executive_appreciation

Executive Appreciation - $120

box_type: "executive_appreciation"

holiday_celebration

Holiday Celebration - $65

box_type: "holiday_celebration"

new_parent_care

New Parent Care - $55

box_type: "new_parent_care"

Example Request

Request

{
  "box_type": "corporate_welcome",
  "recipients": [
    {
      "name": "Jane Smith",
      "email": "jane@company.com",
      "address": {
        "street": "123 Main Street",
        "city": "Lagos",
        "state": "Lagos",
        "postal_code": "100001",
        "country": "NG"
      }
    }
  ],
  "branding": {
    "company_name": "Your Company",
    "include_logo": true,
    "card_message": "Welcome to the team!"
  },
  "delivery_date": "2026-02-10"
}

Spa Experiences

Send spa and wellness experiences. Recipients book at their preferred spa from 1,000+ verified vendors.

POST/v1/experiences

Send spa experience gifts with self-booking capabilities.

Experience Packages

single_treatment

One spa service - $30-$80

spa_day

Multiple treatments - $100-$200

couples_experience

Spa day for two - $150-$300

premium_wellness

Full-day luxury - $250-$500

Example Request

Request

{
  "package": "spa_day",
  "amount": 150,
  "recipients": [
    {
      "email": "employee@company.com",
      "name": "Sarah Johnson"
    }
  ],
  "location_preference": "johannesburg",
  "validity_days": 90,
  "branding": {
    "company_name": "Your Company",
    "message": "Take time for yourself!"
  }
}

Orders

Retrieve order information and track redemption status.

GET/v1/orders/:order_id

Get detailed information about a specific order.

Response

200 OK

{
  "order_id": "RG-CC-2026-0127-001",
  "type": "choice_card",
  "status": "active",
  "category": "coffee",
  "amount": 50,
  "recipients_count": 1,
  "redeemed_count": 0,
  "redemption_rate": 0,
  "created_at": "2026-01-27T10:30:00Z",
  "expires_at": "2026-04-27T10:30:00Z",
  "recipients": [
    {
      "email": "employee@company.com",
      "name": "John Doe",
      "status": "sent",
      "sent_at": "2026-01-27T10:30:15Z",
      "redeemed_at": null,
      "redemption_url": "https://redeem.ribirewards.com/abc123"
    }
  ]
}

List All Orders

GET/v1/orders

List all orders with optional filtering.

Query Parameters:

?status=active - Filter by status
?type=choice_card - Filter by type
?limit=50 - Results per page (max 100)
?page=2 - Pagination

Webhooks

Receive real-time notifications when gifts are sent, redeemed, or expired.

Setting Up Webhooks

Navigate to Settings → Webhooks in your dashboard
Add your webhook endpoint URL (must be HTTPS)
Select which events you want to receive
Save and copy your webhook secret

Available Events

gift.sent

Gift email has been sent to recipient

gift.redeemed

Recipient has redeemed their gift

gift.expired

Gift has expired without redemption

order.completed

All recipients in an order have redeemed

Webhook Payload Example

gift.redeemed event

{
  "event": "gift.redeemed",
  "timestamp": "2026-01-27T14:22:00Z",
  "data": {
    "order_id": "RG-CC-2026-0127-001",
    "recipient_email": "employee@company.com",
    "recipient_name": "John Doe",
    "gift_type": "choice_card",
    "category": "coffee",
    "amount": 50,
    "redeemed_at": "2026-01-27T14:21:45Z",
    "products_selected": [
      {
        "name": "Ethiopian Yirgacheffe Coffee",
        "price": 18.99
      },
      {
        "name": "French Press",
        "price": 29.99
      }
    ]
  }
}

Error Handling

The API uses standard HTTP response codes and returns detailed error messages in JSON format.

HTTP Status Codes

200

Request succeeded

400

Bad Request

Invalid parameters or missing required fields

401

Unauthorized

Invalid or missing API key

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Something went wrong on our end

Error Response Format

400 Bad Request

{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid category. Must be one of: coffee, wine, fashion, golf, home, beauty, books, gourmet",
    "param": "category",
    "type": "validation_error"
  }
}

White-Labeling

Customize the recipient experience with your branding. All gift redemption pages can be fully white-labeled.

Full Branding Control

Recipients see your company name, logo, colors, and messaging throughout their entire gift experience.

Custom email branding
Branded redemption pages
Your domain (CNAME support)
Custom color schemes

Branding Object

Full branding configuration

{
  "branding": {
    "company_name": "Merit Incentives",
    "logo_url": "https://yourcompany.com/logo.png",
    "from_email": "rewards@meritincentives.com",
    "reply_to_email": "support@meritincentives.com",
    "primary_color": "#2563eb",
    "message": "Congratulations on your achievement!",
    "email_footer": "Questions? Contact us at support@meritincentives.com"
  }
}

Custom Domain: Contact support to set up CNAME records for fully branded redemption URLs (e.g., gifts.yourcompany.com)

Rate Limits

API requests are rate limited to ensure fair usage and system stability.

Current Limits

Standard Tier

100 req/min

Free and paid accounts

Enterprise Tier

1000 req/min

Contact sales for enterprise access

Rate Limit Headers

Every API response includes rate limit information:

Response Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1706358000

Sandbox Environment

Test your integration without sending real gifts or incurring charges.

Safe Testing Environment

The sandbox mirrors production but doesn't send real emails or charge your account. Perfect for development and testing.

Sandbox Base URL

Sandbox URL

https://sandbox-api.ribirewards.com/v1

Testing Tips

Use test API keys (start with test_)
Emails sent in sandbox are logged but not delivered
Access sandbox orders in dashboard → Sandbox Orders
Simulate webhooks using test endpoints

Need Help Integrating?

Our developer support team is here to help you get up and running quickly.

Email Developer Support Get API Key