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.

Categories API

Get all active categories with pagination.

GET /api/v1/categories
X-API-Key: sk_live_abc123def456
X-API-Secret: your-secret-here

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 25, max: 100)

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}
X-API-Key: sk_live_abc123def456
X-API-Secret: your-secret-here

Example Response:

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

Subcategories API

List Subcategories

Get all active subcategories with pagination.

GET /api/v1/subcategories
X-API-Key: sk_live_abc123def456
X-API-Secret: your-secret-here

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 25, max: 100)

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}
X-API-Key: sk_live_abc123def456
X-API-Secret: your-secret-here

Example Response:

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

Countries API

List Countries

Get all countries with pagination and filtering options.

GET /api/v1/countries
X-API-Key: sk_live_abc123def456
X-API-Secret: your-secret-here

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 25, max: 100)

Example Response:

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

Get Country by ID

Retrieve a specific country by its unique identifier.

GET /api/v1/countries/{id}
X-API-Key: sk_live_abc123def456
X-API-Secret: your-secret-here

Example Response:

{
  "id": 1,
  "name": "United States",
  "alpha2": "US",
  "alpha3": "USA",
  "official_name": "United States of America",
  "numeric_code": "840",
  "dialing_prefix": "+1"
}

Currencies API

List Currencies

Get all currencies with pagination support.

GET /api/v1/currencies
X-API-Key: sk_live_abc123def456
X-API-Secret: your-secret-here

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 25, max: 100)

Example Response:

[
  {
    "id": 1,
    "country_id": 1,
    "name": "US Dollar",
    "currency": "USD",
    "symbol": "$",
    "currency_code": "USD",
    "precision": 2
  },
  {
    "id": 2,
    "country_id": 2,
    "name": "Pound Sterling",
    "currency": "GBP",
    "symbol": "£",
    "currency_code": "GBP",
    "precision": 2
  }
]

Get Currency by ID

Retrieve a specific currency by its unique identifier.

GET /api/v1/currencies/{id}
X-API-Key: sk_live_abc123def456
X-API-Secret: your-secret-here

Example Response:

{
  "id": 1,
  "country_id": 1,
  "name": "US Dollar",
  "currency": "USD",
  "symbol": "$",
  "currency_code": "USD",
  "precision": 2
}

Code Example

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

Response Fields

Category Fields

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

Subcategory Fields

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

Country Fields

Field	Type	Description
`id`	integer	Unique country identifier
`name`	string	Common country name
`alpha2`	string	ISO 3166-1 alpha-2 country code
`alpha3`	string	ISO 3166-1 alpha-3 country code
`official_name`	string	Official country name
`numeric_code`	string	ISO 3166-1 numeric country code
`dialing_prefix`	string	International dialing prefix

Currency Fields

Field	Type	Description
`id`	integer	Unique currency identifier
`country_id`	integer	Associated country ID
`name`	string	Full currency name
`currency`	string	Currency abbreviation
`symbol`	string	Currency symbol
`currency_code`	string	ISO currency code
`precision`	integer	Decimal precision for amounts

Common Use Cases

Use categories and subcategories to create hierarchical product filters:

Fetch all categories for top-level navigation
```
GET /api/v1/categories?per_page=100
```
Load subcategories for detailed filtering
```
GET /api/v1/subcategories?per_page=100
```

Use category/subcategory IDs in product search queries

GET /api/v1/products?category_id=1&subcategory_id=101

Localization and Currency Display

Combine country and currency data for proper localization. Use the country_id on each currency to map a user's country to their preferred currency, then format prices using the currency's precision and symbol fields.

Error Responses

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

Best Practices

Caching Strategy

Reference data changes infrequently, making it ideal for caching:

Cache categories and subcategories for 24 hours
Cache countries indefinitely (they rarely change)
Cache currencies for 1 hour (exchange rates may affect display)

Pagination

Always handle pagination for large datasets:

Use reasonable per_page values (25-100)
Check X-Total-Pages header for complete data
Implement client-side pagination for better user experience

Data Validation

Validate reference data IDs before making API calls:

Ensure IDs are positive integers
Handle cases where referenced data might be inactive
Provide fallback options for missing reference data

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

Localization and Currency Display

Error Responses

Best Practices

Caching Strategy

Data Validation

On this page