ReloadPi

Step 1

Install

Install the package in your app or partner integration:

bash

npm install @crossabc/reloadpi-browse-sdk

Step 2

Dead Simple Rules

Use the SDK on the backend

Initialize and call the SDK from your server, route handlers, or API routes.

Do not expose private API keys

Keep API keys on the server. The frontend should only call your own API endpoints.

Fetch catalog data from your own route

Your frontend should call your own route like /api/catalog/vouchers/offers.

Redirect users to ReloadPi

Users browse inside your app, then click Buy and complete the purchase on ReloadPi.

Important: this SDK is for browsing and referral flows. It is read-only. You are not building checkout inside your app.

Step 3

Integration Flow

This is the recommended integration pattern for Next.js and similar apps:

Frontend UI (React / Next.js)

Your API route

ReloadPi Browse SDK

ReloadPi API

↓

User clicks Buy → redirected to ReloadPi

Step 4

Backend Setup

Create one shared SDK instance on the server. A good place is lib/reloadpi/sdk.ts.

import { ShoppiBrowseSDK } from "@crossabc/reloadpi-browse-sdk";

const sdk = new ShoppiBrowseSDK({
  baseUrl: process.env.RELOADPI_API_BASE_URL!,
  apiKey: process.env.RELOADPI_API_KEY!,
  shopUrl: process.env.NEXT_PUBLIC_RELOADPI_SHOP_URL || "https://reloadpi.com",
  referralCode: process.env.NEXT_PUBLIC_RELOADPI_REFERRAL_CODE,
});

export default sdk;

Step 5

API Route Example

Expose your own API route. Your frontend should fetch from this route instead of calling ReloadPi directly.

Example file: app/api/catalog/vouchers/offers/route.ts

import { NextRequest, NextResponse } from "next/server";
import sdk from "@/lib/reloadpi/sdk";

export async function GET(req: NextRequest) {
  try {
    const { searchParams } = new URL(req.url);

    const country = searchParams.get("country") || undefined;
    const brand = searchParams.get("brand") || undefined;
    const limit = Number(searchParams.get("limit") || 12);
    const offset = Number(searchParams.get("offset") || 0);

    const result = await sdk.vouchers.searchOffers({
      country,
      brand,
      limit,
      offset,
    });

    return NextResponse.json({
      items: result.items ?? [],
      total: result.total ?? 0,
    });
  } catch (error) {
    const message =
      error instanceof Error ? error.message : "Failed to load catalog.";

    return NextResponse.json({ error: message }, { status: 500 });
  }
}

Step 6

Frontend Fetch Example

In your client component, fetch from your own route and render the catalog items.

tsx

"use client";

import { useEffect, useState } from "react";

type Offer = {
  offerId: string;
  brandName?: string;
  brand?: string;
  name?: string;
  country?: string;
};

export default function VoucherGrid() {
  const [items, setItems] = useState<Offer[]>([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function load() {
      try {
        const res = await fetch(
          "/api/catalog/vouchers/offers?country=NG&limit=12",
          { cache: "no-store" }
        );

        const data = await res.json();
        setItems(data.items ?? []);
      } finally {
        setLoading(false);
      }
    }

    load();
  }, []);

  if (loading) return <p>Loading offers...</p>;

  return (
    <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">
      {items.map((item) => (
        <div key={item.offerId} className="rounded-xl border p-4">
          <h3 className="font-semibold">
            {item.brandName ?? item.brand ?? item.name ?? item.offerId}
          </h3>
          {item.country ? (
            <p className="mt-1 text-sm text-stone-500">{item.country}</p>
          ) : null}
        </div>
      ))}
    </div>
  );
}

Step 7

Buy Link Example

Use the SDK to generate the final ReloadPi product link with your referral code attached.

import sdk from "@/lib/reloadpi/sdk";

const buyUrl = sdk.getBuyUrl("vouchers", "AMAZON_NG_001");

// Example output:
// https://reloadpi.com/vouchers/offer/AMAZON_NG_001?ref=PARTNER_ABC

For vouchers and top-ups, the SDK generates links like:

https://reloadpi.com/vouchers/offer/OFFER_ID?ref=YOUR_CODE

Users should browse in your app, then click the Buy button and finish the purchase on ReloadPi.

Referral tracking: when you generate links with getBuyUrl(), the ?ref= parameter is handled automatically by ReloadPi.

Step 8

Available Modules

Vouchers

Gift card offers by brand, country, and filters.

sdk.vouchers.searchOffers(...)

Top-ups

Mobile top-up offers by country and operator.

sdk.topups.searchOffers(...)

eSIMs

eSIM plans and country-based browsing.

sdk.esims.searchPlans(...)

Step 9

Environment Variables

Recommended environment variables for a Next.js integration:

env

RELOADPI_API_BASE_URL=https://shoppi-backend.onrender.com/api/catalog/
RELOADPI_API_KEY=your_private_api_key

NEXT_PUBLIC_RELOADPI_SHOP_URL=https://reloadpi.com
NEXT_PUBLIC_RELOADPI_REFERRAL_CODE=PARTNER_ABC

RELOADPI_API_KEY should stay on the server.
NEXT_PUBLIC_RELOADPI_SHOP_URL can be public.
NEXT_PUBLIC_RELOADPI_REFERRAL_CODE can be public if intended for browser-visible referral flows.

Step 10

API Access Notes

CORS: partner domains may need to be whitelisted before direct access is allowed.

Authentication: the SDK sends your API key on requests for you. Keep the key on the server.

Header used: x-api-key

Step 11

Rate Limits

Default partner limits:

10,000 requests per month
120 requests per minute

If you expect higher volume, contact ReloadPi before launch.

Step 12

Troubleshooting

401 Unauthorized

API key is missing, invalid, or the partner account is inactive.

403 Forbidden

The requested catalog type is not included in your allowed access.

429 Too Many Requests

You reached your rate or monthly request limit.

Frontend request blocked

Your domain may not be whitelisted yet for CORS access.

Step 13

Quick Summary

The simplest way to think about this SDK is:

Fetch offers → show them in your UI → redirect users to ReloadPi

The SDK handles authentication using your configured API key, and ReloadPi handles referral attribution when you generate buy links.

Become a Partner Back to Top