Starship Rewards API

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: API Key + Secret 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 "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

# Get currencies with EUR as base
curl -X GET "{{host}}/api/v1/currencies?base_currency=EUR" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

# Get only active currencies
curl -X GET "{{host}}/api/v1/currencies?active_only=true" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

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

Use Cases

Currency Dropdown

Price Display

Next Steps