v0.1 — Early Access

Embed gift cards, top-ups & eSIMs in minutes

The official ReloadPi Browse SDK gives your app read-only access to our full digital goods catalog — with built-in referral tracking and AI agent support.

↗ npm install GitHub →
quickstart.ts 
import { ShoppiBrowseSDK } from "@crossabc/reloadpi-browse-sdk";

const sdk = new ShoppiBrowseSDK({
  baseUrl: "https://shoppi-backend.onrender.com/api/catalog/", // trailing slash required
  apiKey: "YOUR_API_KEY",
  referralCode: "PARTNER_ABC",
});

// Browse gift cards
const vouchers = await sdk.vouchers.searchOffers({
  country: "NG",
  brand: "Amazon",
});

// Get referral link → you earn on every sale
const url = sdk.getBuyUrl("vouchers", vouchers.items[0].id);
// https://reloadpi.com/vouchers/offer/ID?ref=PARTNER_ABC
INSTALL npm install @crossabc/reloadpi-browse-sdk
How it works

From install to live in under 10 minutes

The SDK talks exclusively to ReloadPi's public API. You never touch provider APIs, handle crypto, or manage fulfillment.

01

Install & configure

Add the npm package, pass your API key and referral code. One object, three optional fields.

02

Browse the catalog

Query gift cards, mobile top-ups, or eSIM plans. Filter by country, brand, or operator. Clean typed responses every time.

03

Send users to ReloadPi

Generate a referral link with getBuyUrl(). We handle checkout, crypto payment, and delivery. You earn commission.

Modules

Three domains. One clean interface.

Every module follows the same pattern: search, get by ID, list metadata. No surprises.

🎟️

Vouchers

Gift cards for global brands — Amazon, Adidas, Asda and hundreds more. Filter by country and brand.

searchOffers() getOfferById() listBrands()
📱

Mobile Top-ups

Instant recharges for phone numbers worldwide. Filter by country and operator.

searchOffers() getOfferById() listOperators()
📶

eSIM Plans

Travel eSIM data plans for international roaming. Requires eSIM-capable, carrier-unlocked device.

searchPlans() getPlanById() listCountries()
Referral model

You browse. We sell. You earn.

Every link your app generates includes your referral code. When a user completes a purchase on ReloadPi, you get credit. No payment integration required on your side.

1
User browses your app
Your frontend queries the SDK for vouchers, top-ups, or eSIMs
2
SDK generates a referral link
One call to getBuyUrl() or getCatalogUrl()
3
User lands on ReloadPi
Pays with Pi Coin, USDC, Bitcoin, or other supported crypto
4
You earn commission
Tracked via your referral code. Settled in crypto.

GENERATED LINK

reloadpi.com
https://reloadpi.com/vouchers/offer/AMAZON_NG_001?ref=PARTNER_ABC
catalog link
https://reloadpi.com/vouchers?country=NG&ref=PARTNER_ABC

A 5% conversion fee applies if the payment currency differs from the creator's settlement currency or if a Pi-supported wallet is not used. All transactions are final once confirmed.

Security model

Read-only by design.

This SDK cannot make purchases, trigger payments, or modify account state. Safe to embed in client-side apps and AI agents.

What this SDK can do SAFE

  • Browse and search the full product catalog
  • Fetch individual offer or plan details
  • List brands, operators, and countries
  • Generate referral URLs for any product
  • Be used inside AI agent tool-calling flows
  • Be embedded in frontend apps without risk

What this SDK cannot do BLOCKED

  • Initiate purchases or transactions
  • Process or handle crypto payments
  • Access or modify account balances
  • Create user accounts or sessions
  • Access provider APIs directly
  • Expose internal system data
API key handling: Your API key is sent as a request header to api.shoppi.com only. Never expose your key in client-side code — use the SDK server-side or behind a proxy. Keys can be rotated or revoked at any time. Rate limits and permissions are enforced server-side.
Platform note: ReloadPi is the consumer product. The underlying platform is Shoppi, operated by CrossLabs. The SDK hits api.shoppi.com — this is intentional. ReloadPi is built on Shoppi infrastructure, and the API contract is stable. The shopUrl config option defaults to https://reloadpi.com, so all referral links point to the consumer storefront correctly.
Error handling

Typed errors, always.

Every API failure throws a ShoppiError with a status code, error code, and message — no raw HTTP surprises.

error-handling.ts 
import { ShoppiBrowseSDK, ShoppiError } from "@crossabc/reloadpi-browse-sdk";

try {
  await sdk.vouchers.searchOffers({ country: "NG" });
} catch (err) {
  if (err instanceof ShoppiError) {
    console.error(err.status, err.code, err.message);
    // e.g. 401 "UNAUTHORIZED" "Invalid or missing API key"
  }
}
AI-ready

Built for agents.

The SDK ships with a tool layer for OpenAI function calling, LangChain, and MCP-style integrations.

agent.ts 
import { ShoppiBrowseSDK, createBrowseTools } from "@crossabc/reloadpi-browse-sdk";

const sdk = new ShoppiBrowseSDK({
  baseUrl: "https://shoppi-backend.onrender.com/api/catalog/",
  apiKey: "...",
  referralCode: "...",
});

// Drop into any OpenAI / LangChain / MCP agent
const tools = createBrowseTools(sdk);

// Tools available to your agent:
// search_voucher_offers, get_voucher_offer
// search_topup_offers, get_topup_offer
// search_esim_plans, get_esim_plan
Environment variables

Recommended setup.

Use environment variables for all credentials — never hardcode them. For Next.js partners, this is the recommended pattern.

.env 
# Server-only (never expose to browser)
RELOADPI_API_BASE_URL=https://shoppi-backend.onrender.com/api/catalog/
RELOADPI_API_KEY=your_private_api_key

# Safe to expose to browser
NEXT_PUBLIC_RELOADPI_SHOP_URL=https://reloadpi.com
NEXT_PUBLIC_RELOADPI_REFERRAL_CODE=PARTNER_ABC
RELOADPI_API_KEY — keep server-side only. Never in client bundles.
NEXT_PUBLIC_RELOADPI_SHOP_URL — safe to expose, used for referral link generation.
NEXT_PUBLIC_RELOADPI_REFERRAL_CODE — safe to expose if used in browser-visible referral flows.
Limits & errors

Know the boundaries.

Default partner limits and the error codes you'll encounter.

RATE LIMITS
Monthly requests 10,000
Per minute 120
Expect higher volume? Contact us before launch to discuss elevated limits.
ERROR CODES
401 Unauthorized
API key missing, invalid, or partner account inactive.
403 Forbidden
Catalog type not included in your access scope.
429 Too Many Requests
Rate or monthly limit reached.
CORS Blocked request
Your domain may need whitelisting. Use SDK server-side.
CORS note: The SDK is designed to run server-side. If you call it from a browser directly, your domain must be whitelisted. The recommended pattern is to proxy requests through your own API route and never expose your API key to the client.
Partner access

Request your API key

The package is publicly installable. API access is controlled via keys issued to approved partners.

Apply as Partner View ReloadPi SDK Page