--- name: shoppi-backend.onrender.com description: shoppi-backend.onrender.com provides read-only catalog endpoints for digital goods including gift card vouchers, prepaid mobile top-ups, eSIM plans, and their associated geographic eligibility data. All six skills return catalog metadata only; no purchase, redemption, or activation operations are available through this host. host: shoppi-backend.onrender.com --- # shoppi-backend.onrender.com Shoppi is a digital goods catalog service targeting agents that need to discover and present purchasable options across three product verticals: gift card vouchers, prepaid mobile top-ups, and eSIM data plans. It serves as a browsing and eligibility-checking layer, supplying offer IDs, pricing, and coverage metadata that a downstream purchase flow would consume. It does not execute transactions or return live account or balance data. ## When to use this host Use this host when an agent needs to discover catalog metadata — offer IDs, brand names, pricing, coverage, or eligibility — for gift card vouchers, prepaid mobile top-ups, or eSIM plans. It is the correct starting point for any flow that must present product options to a user before a purchase. Do not use this host to execute purchases, redeem vouchers, activate eSIMs, check live network availability, or look up account balances; those operations require a separate transactional API not represented here. If the agent already has an offerId and needs to complete a transaction, route to whichever purchase or fulfillment host is paired with this catalog service. ## Capabilities ### Geographic Eligibility Determines which countries are supported for each product vertical before catalog browsing or purchase initiation, preventing wasted catalog calls for unsupported regions. - **`fetch-voucher-eligible-countries`** — Returns the list of ISO 3166-1 alpha-2 country codes for which the voucher catalog is available. - **`fetch-topups-supported-countries`** — Returns an array of ISO 3166-1 alpha-2 country codes for which mobile top-up services are available on the Shoppi platform. ### Voucher and Gift Card Catalog Returns the full set of purchasable gift card and voucher options, organized either as a flat paginated offer list or grouped by brand, including offer IDs, denominations, and USD pricing needed to select a specific product. - **`fetch-voucher-offers-catalog`** — Returns a paginated list of available voucher offers with offer IDs, brand names, countries, regions, subtypes, and fixed pricing details in USD. - **`fetch-voucher-brand-catalog`** — Returns the full catalog of purchasable voucher brands, each with brand name, image URL, and a list of available eGift offers including offer IDs, country, regions, sub-types, and price type. ### Mobile Top-Up Catalog Returns available prepaid mobile top-up and bundle offers across global carriers, including voice, SMS, and data allowances with USD pricing, enabling carrier and plan selection before purchase. - **`fetch-topup-offers-catalog`** — Returns a paginated catalog of prepaid mobile top-up and bundle offers across global carriers, including offer IDs, brands, countries, voice/SMS/data allowances, and USD pricing details. ### eSIM Plan Catalog Returns available eSIM plans with data limits, duration, regional coverage, and pricing, enabling programmatic comparison and plan selection before purchase or activation. - **`fetch-esim-offers-catalog`** — Returns a paginated list of available eSIM plans with pricing, data limits, duration, regional coverage, and product metadata for programmatic comparison. ## Workflows ### Voucher Purchase Preparation *Use when an agent needs to validate a user's country and then present available gift card or voucher options for that country before handing off to a purchase flow.* 1. **`fetch-voucher-eligible-countries`** — Retrieve the list of supported country codes and confirm the user's country is eligible before proceeding. 2. **`fetch-voucher-brand-catalog`** — Fetch all voucher brands and their offer IDs, filtering results to the user's confirmed country to present relevant options. 3. **`fetch-voucher-offers-catalog`** — Optionally retrieve the flat paginated offer list for additional filtering by category or subtype, and extract the specific offerId needed for purchase. ### Mobile Top-Up Purchase Preparation *Use when an agent needs to confirm a user's country is supported for mobile top-up and then retrieve available carrier plans before initiating a top-up transaction.* 1. **`fetch-topups-supported-countries`** — Retrieve supported country codes and validate that the user's country is eligible for top-up services. 2. **`fetch-topup-offers-catalog`** — Fetch available prepaid top-up and bundle offers, filtering by the validated country or carrier to present plan options and capture the offerId for purchase. ## Skill reference ### `fetch-voucher-eligible-countries` **Voucher Eligible Countries** — Returns the list of ISO 3166-1 alpha-2 country codes for which the voucher catalog is available. *Use when:* Use when an agent needs to determine which countries are supported for voucher availability before displaying voucher options or initiating a voucher purchase flow. *Not for:* Do not use for retrieving actual voucher products, pricing, or denominations; use a voucher catalog endpoint instead. **Returns:** Returns a JSON array of objects each containing a 'code' field with an ISO 3166-1 alpha-2 country code; the real response includes 59 countries such as US, GB, DE, FR, NG, and ZA. **Example:** `GET https://shoppi-backend.onrender.com/api/catalog/vouchers/countries` --- ### `fetch-voucher-offers-catalog` **Voucher Offers Catalog** — Returns a paginated list of available voucher offers with offer IDs, brand names, countries, regions, subtypes, and fixed pricing details in USD. *Use when:* Use when an agent needs to browse or search the catalog of purchasable gift card or voucher offers, including filtering by brand, country, or category before selecting a specific offer to purchase. *Not for:* Do not use to purchase or redeem a voucher; this endpoint only returns catalog metadata. Not suitable for real-time price feeds or non-voucher product types. **Returns:** Returns a list array of voucher offer objects each containing offerId, brandName, country, regions, subTypes, priceType, productType, and a price object with fixed amount in minor currency units, margin, and fee. **Example:** `GET https://shoppi-backend.onrender.com/api/catalog/vouchers/offers` --- ### `fetch-topup-offers-catalog` **TopUp Offers Catalog** — Returns a paginated catalog of prepaid mobile top-up and bundle offers across global carriers, including offer IDs, brands, countries, voice/SMS/data allowances, and USD pricing details. *Use when:* Use when an agent needs to browse or search available prepaid mobile top-up or bundle offers for a specific carrier, country, or region before presenting purchase options to a user. *Not for:* Do not use to execute or fulfill a top-up purchase; this endpoint only returns offer listings. Not suitable for real-time balance checks or account lookups. **Returns:** Returns a list array of prepaid mobile top-up and bundle offer objects, each with offerId, brand, country, pricing in USD cents, and voice/SMS/data allowances. **Example:** `GET https://shoppi-backend.onrender.com/api/catalog/topups/offers` --- ### `fetch-voucher-brand-catalog` **Voucher Brand Catalog** — Returns the full catalog of purchasable voucher brands, each with brand name, image URL, and a list of available eGift offers including offer IDs, country, regions, sub-types, and price type. *Use when:* Use when an agent needs to discover available voucher or eGift card brands and their specific offer IDs before initiating a voucher purchase, or when presenting a user with a list of brands and denominations they can buy. *Not for:* Do not use for real-time pricing or balance checks on already-purchased vouchers; this endpoint returns catalog metadata only, not live pricing or redemption data. **Returns:** Returns a JSON object keyed by brand slug, each containing brandName, image URL, and an offers array with offerId, country, regions, subTypes, priceType, and image for every available eGift denomination. **Example:** `GET https://shoppi-backend.onrender.com/api/catalog/vouchers/brands` --- ### `fetch-esim-offers-catalog` **eSIM Offers Catalog** — Returns a paginated list of available eSIM plans with pricing, data limits, duration, regional coverage, and product metadata for programmatic comparison. *Use when:* Use when an agent needs to browse or compare purchasable eSIM plans by country, region, data allowance, duration, or price before presenting options to a user or initiating a purchase. *Not for:* Do not use for purchasing or activating an eSIM; this endpoint only returns catalog listings. Not suitable for real-time network availability checks. **Returns:** Returns a list array of eSIM offer objects each containing offerId, country, regions, dataGB, dataUnlimited, durationDays, price in minor currency units, priceType, productType, subTypes, and notes. **Example:** `GET https://shoppi-backend.onrender.com/api/catalog/esims/offers` --- ### `fetch-topups-supported-countries` **Topups Countries Catalog** — Returns an array of ISO 3166-1 alpha-2 country codes for which mobile top-up services are available on the Shoppi platform. *Use when:* Use when an agent needs to determine which countries are supported before initiating a mobile top-up, or to validate that a user's country is eligible for top-up services. *Not for:* Do not use to fetch top-up products, denominations, or pricing — this endpoint only returns supported country codes, not catalog details. **Returns:** Returns a JSON array of objects each containing a 'code' field with an ISO 3166-1 alpha-2 country code (e.g. US, NG, IN, BR) covering 110+ supported countries. **Example:** `GET https://shoppi-backend.onrender.com/api/catalog/topups/countries` ---