Skip to main content

​
Overview

The catalog endpoint returns all available gift cards and digital products organized by categories like Gaming Cards, Streaming Services, etc. Products should be cached to minimize API calls since the catalog changes infrequently.
Cache catalog data for at least 24 hours. Products are added/removed rarely.

​
API Reference

GET /v3/gift-cards/catalog

Complete endpoint documentation

​
Basic Catalog Loading

async function loadCatalog() {
  const response = await fetch(
    "https://api.oneclickdz.com/v3/gift-cards/catalog",
    {
      headers: {
        "X-Access-Token": process.env.API_KEY,
      },
    }
  );

  if (!response.ok) {
    throw new Error(`Failed to load catalog: ${response.status}`);
  }

  const result = await response.json();
  return result.data;
}

// Usage
const catalog = await loadCatalog();
console.log(`Total categories: ${catalog.categories.length}`);
console.log(
  `Total products: ${catalog.categories.reduce(
    (sum, cat) => sum + cat.products.length,
    0
  )}`
);

​
Response Structure

{
  "success": true,
  "data": {
    "categories": [
      {
        "name": "Gaming Cards",
        "products": [
          {
            "id": "507f1f77bcf86cd799439011",
            "title": "PlayStation Network",
            "enabled": true,
            "region": "dz"
          },
          {
            "id": "507f1f77bcf86cd799439012",
            "title": "Google Play Gift Card",
            "enabled": true
          }
        ]
      },
      {
        "name": "Streaming Services",
        "products": [
          {
            "id": "507f1f77bcf86cd799439014",
            "title": "Netflix Gift Card",
            "enabled": true
          }
        ]
      }
    ]
  },
  "meta": {
    "totalCategories": 8,
    "totalProducts": 127
  }
}

​
Caching Implementation

class CatalogCache {
  constructor(ttlMinutes = 10) {
    this.data = null;
    this.timestamp = 0;
    this.ttl = ttlMinutes * 60 * 1000;
  }

  async get() {
    const now = Date.now();

    // Return cached if still valid
    if (this.data && now - this.timestamp < this.ttl) {
      console.log("Returning cached catalog");
      return this.data;
    }

    // Fetch fresh data
    console.log("Fetching fresh catalog");
    const response = await fetch(
      "https://api.oneclickdz.com/v3/gift-cards/catalog",
      {
        headers: { "X-Access-Token": process.env.API_KEY },
      }
    );

    this.data = await response.json();
    this.timestamp = now;

    return this.data;
  }

  invalidate() {
    this.data = null;
    this.timestamp = 0;
  }
}

// Usage
const cache = new CatalogCache(10); // 24 hours TTL

// First call - fetches from API
const catalog1 = await cache.get();

// Second call within 24 hours - returns cached
const catalog2 = await cache.get();

// Force refresh
cache.invalidate();
const catalog3 = await cache.get(); // Fetches fresh

​
Filtering Products

Only show enabled products to customers: 
function getEnabledProducts(catalog) {
  const enabled = [];

  for (const category of catalog.categories) {
    const enabledInCategory = category.products.filter((p) => p.enabled);

    if (enabledInCategory.length > 0) {
      enabled.push({
        categoryName: category.name,
        products: enabledInCategory,
      });
    }
  }

  return enabled;
}

// Usage
const catalog = await cache.get();
const enabledProducts = getEnabledProducts(catalog.data);
console.log("Enabled products:", JSON.stringify(enabledProducts, null, 2));

​
Region Filtering

Filter products by region if targeting specific markets: 
function filterByRegion(catalog, region = "dz") {
  return catalog.categories
    .map((category) => ({
      ...category,
      products: category.products.filter(
        (p) => p.enabled && (!p.region || p.region === region)
      ),
    }))
    .filter((cat) => cat.products.length > 0);
}

// Usage
const algerianProducts = filterByRegion(catalog.data, "dz");

​
Best Practices

Handle Errors Gracefully

Fall back to cached data if API is temporarily unavailable

Organize by Category

Use category structure for better user experience

​
Next Steps

Check Products

Get pricing and stock for selected products

Place Orders

Submit orders with validation

API Reference

Complete endpoint documentation

Overview

Back to integration overview

Track Status

Monitor order fulfillment

Secure Delivery

Encrypt and deliver cards