zendit developers Logo
Search zendit documentation

zendit Catalog

In this guide, you will be introduced to the features of the zendit catalog and learn how to effectively utilize its functionalities. By following this document, you will gain a comprehensive understanding of the catalog and be equipped with the necessary knowledge to make the most of its capabilities. Let’s dive in and explore the zendit catalog together.

Skip the preamble and just get to the example code?

Catalog

The zendit Catalog

The zendit catalog consists of several sections that offer a variety of products for different purposes. Let’s explore each section in detail:

  1. Mobile Top Up: This section focuses on providing products specifically for mobile top-ups. It enables the sale of various offerings related to mobile services across international regions. Customers can easily recharge their mobile accounts using this section.
  2. Mobile Bundles: In this section, customers can find a range of mobile bundle products. These bundles offer a combination of services such as data, minutes, and SMS, providing customers with convenient and cost-effective options to meet their mobile service needs.
  3. Mobile Data: The Mobile Data section caters specifically to customers seeking data-related products. Customers can choose from a variety of data plans and packages to fulfill their mobile data requirements.
  4. Digital Gift Cards: This section offers a diverse range of digital gift cards. Customers can select from various brands and denominations to purchase gift cards for themselves or to send as gifts to others. It provides a convenient platform for purchasing and sending digital gift cards for different occasions.
  5. Utility Payments: In this section, customers can find prepaid utility payment products. These products enable customers to conveniently make payments for essential utilities such as electricity, water, gas, and more.

By exploring the different sections of the zendit catalog, customers can discover a wide array of products and services tailored to their specific needs, ensuring a seamless and convenient experience.

Product Catalog

Countries and Regions

The Zendit catalog can be filtered by Region and Country to narrow down searching for offers. When searching by Region, the following list of Regions are available:

  • Global
  • Africa
  • Asia
  • Caribbean
  • Central America
  • Eastern Europe
  • Western Europe
  • North America
  • Oceania
  • South America
  • South Asia
  • Southeast Asia
  • Middle East and North Africa

For the Global eSIM offer, use Global as the search region to find them.

Offers

Within the Zendit catalog, each product is associated with an offer. These offers consist of several key attributes, including a subtype, a brand, and a cost associated with offering the product. To enhance your browsing experience, the catalog provides filtering options based on destination country, brand, and subtype. Additionally, you have the capability to export the catalog as a CSV file, enabling you to conveniently view and analyze the data using spreadsheet applications such as Excel.

The offers within the catalog can be categorized into two main varieties:

  1. Fixed Offers: These offers have a predetermined cost and value associated with them. The cost remains fixed, and the value is delivered accordingly.
  2. Range Offers: Unlike fixed offers, range offers provide a range of values between a minimum and maximum threshold. The specific value to be delivered depends on various factors, such as the offer’s foreign exchange rate (FX rate).

By understanding the different offer types and utilizing the filtering and exporting functionalities, you can effectively navigate and manage the zendit catalog to cater to your specific business requirements.

Fixed offers

A fixed offer in the Zendit catalog corresponds to a specific value that is sent to the designated destination, along with the associated cost to your account when selling the offer. Leveraging the zendit API, fulfilling a fixed offer is straightforward, requiring only the offer ID to be provided.

By utilizing the offer ID in your API request, you can seamlessly initiate the fulfillment process for the fixed offer. This simplifies the workflow, streamlining the transaction and ensuring a smooth experience for both you and your customers.

With the convenience of the zendit API, fulfilling fixed offers becomes a seamless task, allowing you to efficiently provide the intended value to the designated destination while keeping track of the associated costs.

Ranged offers

A ranged offer within the zendit catalog encompasses a specific range of values for the destination currency, as well as a corresponding range for the cost. The cost is determined based on an FX (foreign exchange) value applied to the offer, taking into account the specific value being sent.

When utilizing the zendit API with a ranged offer, you have three options for specifying the value to be sent:

  1. Price: The value is based on the catalog’s FX price for selling the offer. This pricing information can be found in the pricing section of the catalog.
  2. Cost: The value is based on the FX rate set as your cost. This allows you to calculate the value to be sent based on your specific cost considerations.
  3. Zend: The value is based on the desired destination value. You can specify the exact value you want to send, taking into account the limitations mentioned below.

It’s important to note that due to currency fluctuations, the value sent to the destination is an estimation and cannot be guaranteed. Additionally, values sent are rounded to the lowest unit of currency in the destination, and fractional units of currency are not supported.

By understanding the options available and the limitations associated with ranged offers, you can effectively utilize the zendit API to send values within the specified range, while considering the relevant pricing and currency factors.

Offer costs

For each product listed in the zendit catalog, there is an associated cost that represents the amount of money that will be deducted from your wallet upon a successful sale. The cost corresponds to the price you will pay to purchase the product.

When a transaction is completed and the sale is successful, the cost of the purchased product will be deducted from your wallet balance. It is important to ensure that your wallet has sufficient funds to cover the cost of the product you intend to purchase. Insufficient funds may result in a failed transaction due to insufficient balance.

By keeping track of the costs associated with each product in the catalog and ensuring your wallet has adequate funds, you can facilitate smooth transactions and ensure successful purchases of the desired products.

Offer Costs

Pricing Offers

In the catalog view, you have the option to access pricing suggestions provided by zendit. These suggestions offer recommended pricing for selling each product. If you do not have your own catalog system integrated or prefer to use zendit’s catalog through our API, you can click on a product and modify its price.

For fixed price offers, you can set a specific price for selling the product or choose to set a desired margin. If you opt for the margin approach, the selling price will be automatically calculated for you.

For open range offers, you can adjust the FX rate provided to users for purchasing the product, or set a desired margin. If you choose the margin option, the FX rate will be computed accordingly.

All prices set within the catalog are readily available through the zendit API. This eliminates the need for you to maintain a separate catalog system, as the catalog data can be seamlessly accessed and utilized in your integration.

By leveraging the pricing features of the zendit catalog, you can effectively manage and customize the selling prices of the products, ensuring flexibility and convenience for your business operations.

To set the price of items, follow these steps:

  1. In the catalog view, locate the item for which you want to set the price.
  2. Look for the “Show” toggle or button with pricing options and click on it.
  3. This will expand the view to show the suggested pricing for the item.

By utilizing the pricing options and setting appropriate prices for your items, you can effectively manage your catalog and optimize your selling strategy.

Zendit Product Catalog

Enabling and Disabling Products

With the zendit catalog, you have the flexibility to disable specific products from being available for sale. This feature enables you to customize your integration by selecting and enabling only the products that are of interest to you. By disabling certain products, you can streamline the transaction process and ensure that only the desired items are available for purchase. This customization helps to create a more focused and tailored experience for your users.

Filtering the List of Items

The catalog browser provides convenient filtering options to help you find specific items. You can apply filters based on country, brand, and subtypes specifically for Digital Gift Cards. By using these filters, you can narrow down the displayed items to meet your preferences and requirements. This allows for a more efficient browsing experience and enables you to locate the desired items quickly and easily.

Viewing Details of Items

To access the detailed information of an item in the zendit catalog, simply click on the country link associated with the item. Upon clicking, a drawer will slide out from the right side of the screen, revealing the comprehensive details and the pricing editor for that particular item. This allows you to view and modify the pricing information, making it convenient to manage and customize the pricing of individual items according to your preferences.

Setting Pricing on Items

For users who prefer to utilize zendit’s catalog directly within their integration, pricing information can be easily configured for each item. There are two options for setting the price: specifying a specific price or defining a desired margin. When you update the price, the corresponding margin will be automatically calculated. Likewise, if you set a margin, the price will be calculated accordingly. This flexibility allows you to conveniently adjust the pricing of items based on your preferred pricing strategy, ensuring that your integration aligns with your desired pricing structure.

Using the zendit Catalog in integration

Using the Zendit API, you have two options for integrating the catalog into your system:

  1. Separate Catalog Integration: In this approach, you can pull the products and costs from the Zendit API and incorporate them into your own separate catalog. You can handle pricing and other aspects within your own system, independent of Zendit. This option gives you more flexibility and control over your pricing strategy, allowing you to customize the catalog according to your specific requirements.
  2. Zendit Catalog Integration: Alternatively, you can choose to set up your own prices and select the specific products you want to sell through Zendit. You can configure your prices within Zendit’s platform and use the Zendit API to retrieve the catalog and serve it to your customers. This option simplifies the process as you can leverage Zendit’s catalog infrastructure and pricing capabilities, eliminating the need to maintain a separate catalog system.

Both options provide integration possibilities, and you can choose the approach that best aligns with your business needs and technical capabilities. Whether you prefer to manage pricing independently or leverage Zendit’s catalog functionality, the Zendit API offers the flexibility to integrate the catalog seamlessly into your system.

Using the Catalog from the API

When retrieving the catalog from the API or through an SDK, all items will be returned in a paginated manner, including both enabled and disabled items. Each item in the catalog will have a flag indicating whether it is enabled or not. If you are directly exposing this catalog to your integration, it is important to filter out any disabled items, as attempting to purchase a disabled item will result in a failure.

For Mobile Top Up Products, such as Mobile Top Ups, Mobile Bundles, and Mobile Data, the catalog for these products can be accessed through the /topups endpoints. To filter between the different product types, you can pass the product subtype (Mobile Top Ups, Mobile Bundles, or Mobile Data) as a parameter in the catalog request.

For Voucher Products, such as Digital Gift Cards and Utility Payments, the catalog of these products is available through the /vouchers endpoints. To specifically retrieve Utility Payments without including Digital Gift Cards, you can use the subtype filter with the value “Utilities” to filter for those specific items.

For eSIM Products, the catalog of these products is available through the /esim endpoints.

Catalog Example Code

All sample code for the catalog is written in TypeScript for Node.js with Express using the Zendit Node.js SDK. Template engine used in the example using Pug templates (sample template not included.)

import express, { Request, Response } from "express";
import { ZenditApi } from "@zenditplatform/zendit-sdk";
import { DtoESimOffersResponse } from "@zenditplatform/zendit-sdk";
import dotenv from 'dotenv';

// Load config from .env file
dotenv.config();
// Create instance of ZenditApi using the ZENDIT_API_KEY set in the .env file
const zendit = new ZenditApi(process.env.ZENDIT_API_KEY);

export const esimCatalog = express.Router();

// Get the catalog using the header acceptance to return either a page with a PUG template
// or the JSON from the catalog
esimCatalog.get("/catalog/esims", (req: Request, res: Response): void => {
    if (req.headers.accept == 'application/json') {
        // Render the JSON for the catalog
        sendJSON(req, res);
    } else {
        // Render the page for the catalog
        sendPage(req, res);
    }
})

// Sends the page version of the catalog using request filters and renders it with PUG templates
function sendPage(req: Request, res: Response) {
    // Catalog filters passed from the query sttring 
    
    // Set the _limit to the passed value or default to 10 items
    const _limit = req.query._limit == null ? 10 : Number(req.query._limit);
    // Set the _offset to the passed value or default to 0
    const _offset = req.query._offset == null ? 0 : Number(req.query._offset);
    // Set the brand to the passed value or default to an empty string (no filter)
    const brand = req.query.brand == null ? "" : String(req.query.brand);
    // Set the destination country to the passed value or default to an empty string (no filter)
    const country = req.query.country == null ? "" : String(req.query.country);
    // Set the subType to the passed value or default to an empty string (no filter)
    const subType = req.query.subType == null ? "" : String(req.query.subType);
    //Set the region to the passed value or default to an empty string (no filter)
    const region = req.query.regions == null ? "" : String(req.query.regions);

    // Get the list of eSIM offers matching the filters and then render it as JSON 
    zendit.esimOffersGet(_limit, _offset, brand, country, region, subType)
     .then(function (catalog) {
        // Render the catalog with a template
        res.render("catalog/esim", {catalog: catalog});
        
    })
    .catch(error => res.send("Error getting catalog from Zendit."));
}

// Sends the JSON version of the catalog using request flters and renders it in JSON
function sendJSON(req: Request, res: Response) {
    // Catalog filters passed from the query sttring 
    
    // Set the _limit to the passed value or default to 10 items
    const _limit = req.query._limit == null ? 10 : Number(req.query._limit);
    // Set the _offset to the passed value or default to 0
    const _offset = req.query._offset == null ? 0 : Number(req.query._offset);
    // Set the brand to the passed value or default to an empty string (no filter)
    const brand = req.query.brand == null ? "" : String(req.query.brand);
    // Set the destination country to the passed value or default to an empty string (no filter)
    const country = req.query.country == null ? "" : String(req.query.country);
    // Set the subType to the passed value or default to an empty string (no filter)
    const subType = req.query.subType == null ? "" : String(req.query.subType);
    //Set the region to the passed value or default to an empty string (no filter)
    const region = req.query.regions == null ? "" : String(req.query.regions);
   
   // Get the list of eSIM offers matching the filters and then render it as JSON
   zendit.esimOffersGet(_limit, _offset, brand, country, region, subType)
   .then(function (catalog) {
      res.json(catalog);
   })
   .catch(error => res.send("Error getting catalog from Zendit."));
   
}