Access categories, subcategories, countries, and currencies for product filtering and localization

Reference Data API

The Reference Data API provides essential lookup data for categories, subcategories, countries, and currencies. This data is used for product filtering, localization, and building user interfaces.

For detailed documentation on each endpoint, see the dedicated reference data pages:

Categories & Subcategories

Countries

Currencies

Categories API

Get all active categories. All records are returned in a single response.

GET /api/v1/categories
Authorization: Bearer {token}

Note: Category and subcategory endpoints require the vouchers feature to be enabled for your account.

Example Response:

[
  {
    "id": 1,
    "name": "Gift Cards"
  },
  {
    "id": 2,
    "name": "Mobile Top-up"
  },
  {
    "id": 3,
    "name": "Digital Services"
  }
]

Get Category by ID

Retrieve a specific category by its unique identifier.

GET /api/v1/categories/{id}
Authorization: Bearer {token}

Example Response:

{
  "id": 1,
  "name": "Gift Cards"
}

Subcategories API

List Subcategories

Get all active subcategories. All records are returned in a single response.

GET /api/v1/subcategories
Authorization: Bearer {token}

Example Response:

[
  {
    "id": 101,
    "name": "Retail Gift Cards"
  },
  {
    "id": 102,
    "name": "Entertainment Gift Cards"
  },
  {
    "id": 201,
    "name": "Prepaid Mobile Credit"
  }
]

Get Subcategory by ID

Retrieve a specific subcategory by its unique identifier.

GET /api/v1/subcategories/{id}
Authorization: Bearer {token}

Example Response:

{
  "id": 101,
  "name": "Retail Gift Cards"
}

Countries API

List Countries

Get all countries. All records are returned in a single response.

GET /api/v1/countries
Authorization: Bearer {token}

Example Response:

[
  {
    "id": 1,
    "name": "United States of America",
    "official_name": "The United States of America",
    "alpha_2": "US",
    "alpha_3": "USA",
    "numeric_code": "840",
    "dialing_prefix": "+1"
  },
  {
    "id": 2,
    "name": "United Kingdom",
    "official_name": "The United Kingdom of Great Britain and Northern Ireland",
    "alpha_2": "GB",
    "alpha_3": "GBR",
    "numeric_code": "826",
    "dialing_prefix": "+44"
  }
]

Get Country by ID

Retrieve a specific country by its unique identifier.

GET /api/v1/countries/{id}
Authorization: Bearer {token}

Example Response:

{
  "id": 1,
  "name": "United States of America",
  "official_name": "The United States of America",
  "alpha_2": "US",
  "alpha_3": "USA",
  "numeric_code": "840",
  "dialing_prefix": "+1"
}

Currencies API

List Currencies

Get all currencies. All records are returned in a single response.

GET /api/v1/currencies
Authorization: Bearer {token}

Example Response:

[
  {
    "id": 1,
    "name": "US Dollar",
    "currency": "USD",
    "precision": 2
  },
  {
    "id": 2,
    "name": "Pound Sterling",
    "currency": "GBP",
    "precision": 2
  }
]

Get Currency by ID

Retrieve a specific currency by its unique identifier.

GET /api/v1/currencies/{id}
Authorization: Bearer {token}

Example Response:

{
  "id": 1,
  "name": "US Dollar",
  "currency": "USD",
  "precision": 2
}

Code Example

Here's a basic PHP implementation for the Reference Data API:

<?php

class ReferenceDataAPI {
    private $token;
    private $baseUrl = '{{host}}';

    public function __construct($token) {
        $this->token = $token;
    }

    public function getCategories() {
        return $this->makeRequest('/api/v1/categories');
    }

    public function getCategoryById($id) {
        return $this->makeRequest("/api/v1/categories/{$id}");
    }

    public function getSubcategories() {
        return $this->makeRequest('/api/v1/subcategories');
    }

    public function getSubcategoryById($id) {
        return $this->makeRequest("/api/v1/subcategories/{$id}");
    }

    public function getCountries() {
        return $this->makeRequest('/api/v1/countries');
    }

    public function getCountryById($id) {
        return $this->makeRequest("/api/v1/countries/{$id}");
    }

    public function getCurrencies() {
        return $this->makeRequest('/api/v1/currencies');
    }

    public function getCurrencyById($id) {
        return $this->makeRequest("/api/v1/currencies/{$id}");
    }

    private function makeRequest($endpoint) {
        $url = $this->baseUrl . $endpoint;

        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer ' . $this->token,
            'Content-Type: application/json'
        ]);

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode !== 200) {
            throw new Exception("API request failed with status {$httpCode}");
        }

        return json_decode($response, true);
    }
}

// Usage
$api = new ReferenceDataAPI('your_token_here');

try {
    $categories = $api->getCategories();
    $countries = $api->getCountries();
    $currencies = $api->getCurrencies();

    echo "Found " . count($categories) . " categories\n";
    echo "Found " . count($countries) . " countries\n";
    echo "Found " . count($currencies) . " currencies\n";
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>

Response Fields

Category Fields

Field	Type	Description
`id`	number	Unique category identifier
`name`	string	Display name of the category

Subcategory Fields

Field	Type	Description
`id`	number	Unique subcategory identifier
`name`	string	Display name of the subcategory

Country Fields

Field	Type	Description
`id`	number	Unique country identifier
`name`	string	Country common name
`official_name`	string	Official country name
`alpha_2`	string	ISO 3166-1 alpha-2 code (2 letters)
`alpha_3`	string	ISO 3166-1 alpha-3 code (3 letters)
`numeric_code`	string	ISO 3166-1 numeric code
`dialing_prefix`	string	International dialing prefix

Currency Fields

Field	Type	Description
`id`	number	Unique currency identifier
`name`	string	Full currency name
`currency`	string	ISO 4217 currency code
`precision`	number	Number of decimal places

Common Use Cases

Use categories and subcategories to create hierarchical product filters:

Fetch all categories for top-level navigation
```
GET /api/v1/categories
```
Load subcategories for detailed filtering
```
GET /api/v1/subcategories
```
Use category names in product search queries
```
GET /api/v1/products?category=Gift%20Cards
```

Price Formatting with Currency Precision

Use the precision field from the currency API to format prices correctly:

function formatPrice($amount, $currencyPrecision) {
    return number_format($amount, $currencyPrecision);
}

// USD (precision: 2) → "12.50"
// JPY (precision: 0) → "1000"

Error Handling

All reference data endpoints return consistent error responses:

Common Error Codes:

400 Bad Request: Invalid parameters or ID format
401 Unauthorized: Missing or invalid authentication token
404 Not Found: Resource not found or inactive
500 Internal Server Error: Server-side processing error

Error Response Format:

{
  "error": {
    "name": "NotFoundError",
    "code": "NOT_FOUND",
    "message": "Category not found"
  }
}

Caching

Reference data changes infrequently and is cached server-side:

Categories, subcategories, countries, and currencies are cached for 24 hours
Product catalog data uses shorter cache durations (5 minutes)

Reference Data API

Reference Data API

Categories API

Get Category by ID

Subcategories API

List Subcategories

Get Subcategory by ID

Countries API

List Countries

Get Country by ID

Currencies API

List Currencies

Get Currency by ID

Code Example

Response Fields

Category Fields

Subcategory Fields

Country Fields

Currency Fields

Common Use Cases

Building Product Filters

Price Formatting with Currency Precision

Error Handling

Caching

On this page