Catalog endpoints

The catalog is a three-level tree: big categories hold categories, categories hold subcategories, and a subcategory is the item you actually buy. These endpoints let you mirror that tree into your own database and price an item immediately before you order it.

GET

/catalog/big-categories

List Big Categories

Get all top-level categories (e.g., Mobile Games, PC Games, Gift Cards).

Rate limit80 req / 60s per user (shared across all catalog endpoints)

Query parameters

Name	Type	Required	Description	Example
for_ui	boolean	No	Include image URLs in the response.	true

Request

curl -s "https://shop2topup.com/api/endpoints/v1/catalog/big-categories?for_ui=true" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

Example response

{
  "success": true,
  "big_categories": [
    {
      "id": 1,
      "name": "Mobile Games",
      "description": "Popular mobile game top-ups"
    },
    {
      "id": 2,
      "name": "PC Games",
      "description": "PC game credits and items"
    }
  ]
}

GET

/catalog/categories

List Categories

Get categories, optionally filtered by big category. Each category represents a game or service.

Rate limit80 req / 60s per user (shared across all catalog endpoints)

Query parameters

Name	Type	Required	Description	Example
bigCategoryId	number	No	Filter by big category ID.	1
for_ui	boolean	No	Include image URLs in the response.	true

Request

curl -s "https://shop2topup.com/api/endpoints/v1/catalog/categories?bigCategoryId=1&for_ui=true" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

Example response

{
  "success": true,
  "categories": [
    {
      "id": 12,
      "name": "Free Fire",
      "description": "Garena Free Fire diamonds",
      "big_category_id": 1,
      "big_category_name": "Mobile Games"
    }
  ]
}

GET

/catalog/subcategories

List Subcategories (Products)

Get available products/denominations. Each subcategory is a purchasable item.

Rate limit80 req / 60s per user (shared across all catalog endpoints)

Query parameters

Name	Type	Required	Description	Example
categoryId	number	No	Filter by category ID.	12

Request

curl -s "https://shop2topup.com/api/endpoints/v1/catalog/subcategories?categoryId=12" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

Example response

{
  "success": true,
  "subcategories": [
    {
      "item_id": 999,
      "name": "FF 100 Diamonds",
      "description": "100 Free Fire Diamonds",
      "category_id": 12,
      "category_name": "Free Fire",
      "price": "0.99",
      "fulfillment_type": "api",
      "returns_voucher": false
    }
  ]
}

GET

/catalog/subcategory/:itemId/price

Get Item Price

Get the current discounted price for a specific subcategory/item. Use this before creating an order to know the exact cost.

Rate limit80 req / 60s per user (shared across all catalog endpoints)

Note: The unit_price is what you will be charged. Use this value for expected_unit_price when creating orders.

Path parameters

Name	Type	Required	Description	Example
itemId	number	Yes	The subcategory/item ID.	999

Request

curl -s "https://shop2topup.com/api/endpoints/v1/catalog/subcategory/999/price" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

Example response

{
  "success": true,
  "price": {
    "item_id": 999,
    "item_name": "FF 100 Diamonds",
    "unit_price": "0.950000",
    "currency": "USD",
    "original_price": "0.990000",
    "discount_applied": true,
    "timestamp": "2024-06-15T12:00:00Z"
  }
}

GET

/catalog/category/:categoryId/requirements

Get Category Requirements

Get the dynamic requirement fields for a specific category. These fields describe what information is needed when validating a player or creating an order (e.g., player ID, server, region).

Rate limit80 req / 60s per user (shared across all catalog endpoints)

Note: Use the returned fields to build dynamic forms for player validation and order creation. Each field specifies its data_type (text, number, single_select, multi_select) and available options for select fields.

Path parameters

Name	Type	Required	Description	Example
categoryId	number	Yes	The category ID to get requirements for.	12

Request

curl -s "https://shop2topup.com/api/endpoints/v1/catalog/category/12/requirements" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

Example response

{
  "success": true,
  "requirements": [
    {
      "field_name": "player_id",
      "data_type": "text",
      "placeholder": "Enter player ID"
    },
    {
      "field_name": "server",
      "data_type": "single_select",
      "placeholder": "Select server",
      "select_options": [
        "Asia",
        "Europe",
        "America"
      ]
    }
  ]
}

Send a real request from this page

Paste an API key to call these endpoints live. The key stays in this browser tab and is sent only to the API itself.

Enter your API key to use the interactive playground. Get your API key

Choose an endpoint

Include images (for_ui=true)

Enter your API key above to try this endpoint.

Response will appear here after sending a request.

Catalog explorer

Catalog Explorer

Browse the product hierarchy and copy IDs for use in API calls.

Enter your API key above to browse the catalog.

New to the platform? Start with the game top-up API overview for resellers, or read the SHOP2TOPUP reseller programme overview for how the partner account works.