Reference Data Overview

The Starship Rewards API provides comprehensive reference data that forms the foundation for all transactions and product interactions. This section covers all the master data you'll need to build your integration.

What is Reference Data?

Reference data consists of standardized, relatively static information that supports business operations:

• Countries: Geographic regions where products are available
• Currencies: Supported currencies with real-time exchange rates
• Categories: Product classification and organization system

Key Features

Global Coverage

• 195 Countries: Complete country list with ISO codes
• 45+ Currencies: Major global currencies with live rates
• Multi-Language: Localized names and descriptions

Real-Time Updates

• Exchange Rates: Updated every 15 minutes during business hours
• Product Availability: Dynamic country/product associations
• Category Changes: Automatic updates when new product types are added

Standardized Format

• ISO Compliance: Country codes (ISO 3166) and currency codes (ISO 4217)
• Consistent Structure: Uniform API responses across all endpoints
• Pagination Support: Efficient data loading for large datasets

Common Use Cases

1. Dropdown Population

Use reference data to populate user interface elements:

// Get countries for a country selector
const countries = await getCountries();
countries.data.forEach(country => {
    addOption(country.name, country.id);
});

2. Currency Conversion

Calculate prices in different currencies:

// Convert USD to EUR
const rate = await getExchangeRate('USD', 'EUR');
const eurPrice = usdPrice * rate;

3. Product Filtering

Filter products by region or category:

// Get products available in specific country
const products = await getProducts({ country_id: 1 });

Reference Data Endpoints

Countries

Access country information including:

• Country codes and names
• Supported currencies per country
• Regional product availability
• Geographic classifications

View Countries API Documentation →

Currencies

Manage currency operations:

• Real-time exchange rates
• Supported denominations per currency
• Currency conversion utilities
• Historical rate data

View Currencies API Documentation →

Categories

Organize products effectively:

• Hierarchical category structure
• Product counts per category
• Category-based filtering
• Subcategory management

View Categories API Documentation →

Best Practices

Caching Strategy

Reference data changes infrequently, making it ideal for caching:

• Countries: Cache for 24 hours
• Categories: Cache for 12 hours
• Currencies: Cache for 15 minutes (due to rate updates)

Error Handling

Always implement fallbacks for reference data:

try {
    const countries = await getCountries();
    return countries.data;
} catch (error) {
    // Return cached data or default list
    return getCachedCountries();
}

Performance Tips

• Use pagination for large datasets
• Implement search functionality for better UX
• Prefetch commonly used data
• Consider GraphQL for specific field selection

Ready to explore the reference data? Start with Countries to understand geographic coverage.