Starship Rewards API
Reference Data Overview

Currencies

Access currency reference data and exchange rates

Currencies

Access currency reference data including exchange rates, currency codes, and supported denominations.

List Currencies

Get a list of all supported currencies with current exchange rates.

Endpoint

GET /api/v1/currencies

Authentication: Bearer token required

Query Parameters

ParameterTypeRequiredDescription
limitnumberNoNumber of results per page (default: 50)
pagenumberNoPage number to retrieve (default: 1)
base_currencystringNoBase currency for exchange rates (default: USD)
active_onlybooleanNoOnly return active currencies (default: true)

Response

Response Headers

HTTP/1.1 200 OK
Content-Type: application/json
X-Page: 1
X-Per-Page: 50
X-Total-Count: 45
X-Total-Pages: 1
X-Page-Size: 45
X-Has-More: false

Response Body

[
  {
    "id": 1,
    "code": "USD",
    "name": "US Dollar",
    "symbol": "$",
    "decimal_places": 2,
    "exchange_rate": 1.0,
    "base_currency": "USD",
    "is_active": true,
    "supported_denominations": [1, 5, 10, 25, 50, 100, 250, 500],
    "last_updated": "2023-12-01T14:30:00Z",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-12-01T14:30:00Z",
    "meta": {
      "base_currency": "USD",
      "last_updated": "2023-12-01T14:30:00Z"
    }
  },
  {
    "id": 2,
    "code": "EUR",
    "name": "Euro",
    "symbol": "€",
    "decimal_places": 2,
    "exchange_rate": 0.85,
    "base_currency": "USD",
    "is_active": true,
    "supported_denominations": [5, 10, 20, 50, 100, 200, 500],
    "last_updated": "2023-12-01T14:30:00Z",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-12-01T14:30:00Z",
    "meta": {
      "base_currency": "USD",
      "last_updated": "2023-12-01T14:30:00Z"
    }
  }
]

Currency Object

FieldTypeDescription
idnumberUnique currency identifier
codestringISO 4217 currency code
namestringCurrency display name
symbolstringCurrency symbol
decimal_placesnumberNumber of decimal places
exchange_ratenumberExchange rate relative to base currency
base_currencystringBase currency for exchange rate
is_activebooleanWhether currency is currently supported
supported_denominationsarrayAvailable denomination values
last_updatedstringISO 8601 timestamp of rate update
created_atstringISO 8601 timestamp
updated_atstringISO 8601 timestamp

Examples

# Get all currencies
curl -X GET "{{host}}/api/v1/currencies" \
  -H "Authorization: Bearer your_access_token"

# Get currencies with EUR as base
curl -X GET "{{host}}/api/v1/currencies?base_currency=EUR" \
  -H "Authorization: Bearer your_access_token"

# Get only active currencies
curl -X GET "{{host}}/api/v1/currencies?active_only=true" \
  -H "Authorization: Bearer your_access_token"
<?php
function getCurrencies($accessToken, $baseCurrency = 'USD', $activeOnly = true, $page = 1) {
    $params = [
        'base_currency' => $baseCurrency,
        'active_only' => $activeOnly ? 'true' : 'false',
        'page' => $page
    ];

    $url = '{{host}}/api/v1/currencies?' . http_build_query($params);

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $accessToken
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HEADER, true);

    $response = curl_exec($ch);
    $headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
    $headers = substr($response, 0, $headerSize);
    $body = substr($response, $headerSize);
    curl_close($ch);

    // Parse pagination headers
    preg_match('/X-Page: (\d+)/', $headers, $pageMatch);
    preg_match('/X-Per-Page: (\d+)/', $headers, $perPageMatch);
    preg_match('/X-Total-Count: (\d+)/', $headers, $totalCountMatch);
    preg_match('/X-Total-Pages: (\d+)/', $headers, $totalPagesMatch);
    preg_match('/X-Page-Size: (\d+)/', $headers, $pageSizeMatch);
    preg_match('/X-Has-More: (true|false)/', $headers, $hasMoreMatch);

    return [
        'data' => json_decode($body, true),
        'pagination' => [
            'page' => (int)$pageMatch[1],
            'per_page' => (int)$perPageMatch[1],
            'total_count' => (int)$totalCountMatch[1],
            'total_pages' => (int)$totalPagesMatch[1],
            'page_size' => (int)$pageSizeMatch[1],
            'has_more' => $hasMoreMatch[1] === 'true'
        ]
    ];
}

function convertCurrency($accessToken, $amount, $fromCurrency, $toCurrency) {
    $result = getCurrencies($accessToken, $fromCurrency);

    foreach ($result['data'] as $currency) {
        if ($currency['code'] === $toCurrency) {
            return $amount * $currency['exchange_rate'];
        }
    }

    throw new Exception("Currency {$toCurrency} not supported");
}
?>

Error Responses

400 Bad Request

{
  "error": "Bad Request",
  "message": "Invalid base_currency parameter"
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or expired access token"
}

503 Service Unavailable

{
  "error": "Service Unavailable",
  "message": "Exchange rate service temporarily unavailable"
}

Exchange Rate Updates

Exchange rates are updated every 15 minutes during business hours and every hour outside business hours. The last_updated field indicates when rates were last refreshed.

Rate Update Notifications

// Check if exchange rates need updating
const checkForRateUpdates = async () => {
  const result = await getCurrencies();
  // Check last updated from first currency's meta field
  const lastUpdated = new Date(result.data[0]?.meta?.last_updated);
  const now = new Date();
  const hoursSinceUpdate = (now - lastUpdated) / (1000 * 60 * 60);

  if (hoursSinceUpdate > 1) {
    console.warn('Exchange rates may be outdated');
    return false;
  }

  return true;
};

Use Cases

Currency Dropdown

const populateCurrencyDropdown = async () => {
  const result = await getCurrencies();
  const dropdown = document.getElementById('currency-select');

  result.data.forEach(currency => {
    const option = document.createElement('option');
    option.value = currency.code;
    option.textContent = `${currency.name} (${currency.symbol})`;
    dropdown.appendChild(option);
  });
};

Price Display

const displayPrice = async (amount, userCurrency = 'USD') => {
  const converter = new CurrencyConverter(accessToken);
  const convertedAmount = await converter.convert(amount, 'USD', userCurrency);
  return converter.formatCurrency(convertedAmount, userCurrency);
};

Next Steps

Countries

Access country reference data and details