# Rates

Your organization's pay-as-you-go prices for a market: calls and messages per destination, roaming data per visited country.

> Enterprise API · https://developer.telgea.com/docs/enterprise/api/rates

## The rate object {#object}

Look up pay-as-you-go retail rates for calling, messaging, and roaming data.

| Field | Type | Description |
| --- | --- | --- |
| `country` | string (required) | ISO 3166-1 alpha-2 country the price applies to — the destination for calling/SMS, the visited country for data. Example: `"DE"` |
| `ratePerUnit` | number (required) | Price per unit in `currency`, to six decimal places. `0` means the country costs nothing — either a route priced free (calls inside the EU/EEA, under roam-like-at-home) or one we publish no pay-as-you-go price for, such as a roaming-data country included in the plan. Example: `0.12` |
| `unit` | string (required) | minutes (voice), count (SMS/MMS), or mb (data). Set even when the country costs nothing. Example: `"minutes"` |
| `currency` | string (required) | The market's ISO 4217 currency — the provider's native one, the same for every country in the list. Null only when nothing in the market is priced, leaving no currency to quote. Example: `"EUR"` |
| `validFrom` | string (required) | When this rate took effect (ISO-8601), or null if unknown. Example: `"2026-01-01"` |

## Operations

- `GET` [List PAYG retail rates for a market](#list-payg-retail-rates-for-a-market)

### List PAYG retail rates for a market {#list-payg-retail-rates-for-a-market}

`GET /v1/rates` · Enterprise API + Partner API

Retrieves the pay-as-you-go retail price list for a market — international calling and messaging per destination, or roaming data per visited country.

Pass a `market` (an ISO 3166-1 alpha-2 country code — the home-plan market) and a rate `type`. The provider that prices the market is resolved internally, so the response is provider-agnostic: it carries only the country, the per-unit price, its unit, the currency and when it took effect. Prices are your organization's: any rate negotiated for it replaces the list price. They are in the provider's native currency; convert as needed.

Calling and messaging are priced from the country the subscriber is in. That is the market by default — a subscriber at home. Add `servingCountry` to price the same market's plan while roaming: `market=DE&servingCountry=DK` is a German plan used in Denmark, and the response echoes the `servingCountry` it priced from. `ROAMING_DATA` has no single serving country — it returns a per-MB price for every visited country — so it ignores the parameter and answers with `servingCountry: null`.

Calls and messages are priced outbound by default — what the subscriber pays to reach each destination. Add `direction=inbound` for the other leg: what the subscriber pays when someone in each country reaches them, which is chargeable while roaming. The response echoes the `direction` it priced; `ROAMING_DATA` has none and answers with `direction: null`.

Every country is listed, and a country that costs the subscriber nothing carries `ratePerUnit: 0` rather than being left out. That covers both a route priced free — calls inside the EU/EEA, under roam-like-at-home — and one we publish no pay-as-you-go price for, such as a roaming-data country included in the plan. For calling and messaging the serving country itself is not listed, since a call that stays inside it is not an international one.

Prices are those in effect today. Add `asOfDate` (YYYY-MM-DD) to read the list for another day — for instance, a price change scheduled to take effect next month. The response echoes the `asOfDate` it priced. The provider is always the one serving the market today.

A market no provider serves answers `403` `COUNTRY_NOT_SUPPORTED`.

**Scope:** `rates:read`.

Requires the permission `rates:read` on the key.

[Try it in the playground](https://developer.telgea.com/playground#tag/rates/GET/v1/rates). Calls run against your live organization; there is no sandbox.

**Parameters**

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `market` | query | string (required) | The home-plan market to price, as an ISO 3166-1 alpha-2 country code. The provider is resolved internally. Example: `DK` |
| `type` | query | enum (required) | The rate type to price: INTL_VOICE (per minute), INTL_SMS / INTL_MMS (per message), or ROAMING_DATA (per MB) Example: `INTL_VOICE` |
| `servingCountry` | query | string | The country the subscriber is calling from, when it differs from the market (roaming). Defaults to the market, which prices calls placed at home. Ignored for ROAMING_DATA, which prices every visited country in one list. Example: `DK` |
| `direction` | query | enum | Which leg of a call or message to price: outbound — the subscriber calls or texts the destination — or inbound — someone in that country reaches the subscriber, which is chargeable while roaming. Defaults to outbound. Ignored for ROAMING_DATA. Example: `outbound` |
| `asOfDate` | query | string (date) | The day to price (YYYY-MM-DD): the rates in effect then. Defaults to today, so a price scheduled to take effect later is never quoted early. The provider is the one serving the market today. Example: `2026-10-01` |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| `200` | Successfully retrieved the retail rates for the market. | `RatesResponse` |
| `400` | Request failed schema validation, or was refused by a business rule | none |
| `401` | Missing or invalid API key in the X-API-Key header | `UnauthorizedError` |
| `403` | The API key lacks the rates:read scope, or no provider serves the requested market | `ForbiddenError` |
| `429` | The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets. | `TooManyRequestsError` |
| `500` | Internal server error. Contact support if this persists. | `InternalError` |

**Response fields (200, RatesResponse)**

| Field | Type | Description |
| --- | --- | --- |
| `market` | string (required) | The market that was priced. Example: `"DE"` |
| `servingCountry` | string (required) | The country the calls were priced from — the requested one, or the market when none was sent. Null for ROAMING_DATA, which prices each visited country in `rates`. Example: `"DE"` |
| `direction` | enum (required) | The direction the list was priced for — the requested one, or outbound when none was sent. Null for ROAMING_DATA, which has no direction. One of: `outbound`, `inbound`. Example: `"outbound"` |
| `asOfDate` | string (date) (required) | The day the list was priced for — the requested one, or today when none was sent. Example: `"2026-09-18"` |
| `rates` | array of Rate (required) | One entry per country — every destination but the serving country for calling, every visited country for data. A country that costs nothing is listed at 0. |
| `rates.country` | string (required) | ISO 3166-1 alpha-2 country the price applies to — the destination for calling/SMS, the visited country for data. Example: `"DE"` |
| `rates.ratePerUnit` | number (required) | Price per unit in `currency`, to six decimal places. `0` means the country costs nothing — either a route priced free (calls inside the EU/EEA, under roam-like-at-home) or one we publish no pay-as-you-go price for, such as a roaming-data country included in the plan. Example: `0.12` |
| `rates.unit` | string (required) | minutes (voice), count (SMS/MMS), or mb (data). Set even when the country costs nothing. Example: `"minutes"` |
| `rates.currency` | string (required) | The market's ISO 4217 currency — the provider's native one, the same for every country in the list. Null only when nothing in the market is priced, leaving no currency to quote. Example: `"EUR"` |
| `rates.validFrom` | string (required) | When this rate took effect (ISO-8601), or null if unknown. Example: `"2026-01-01"` |

**Example request**

```bash
curl -X GET "https://api.telgea.com/v1/rates" \
  -H "x-api-key: $TELGEA_API_KEY"
```

**Response 200**

```json
{
  "market": "DE",
  "servingCountry": "DE",
  "direction": "outbound",
  "asOfDate": "2026-09-18",
  "rates": [
    {
      "country": "US",
      "ratePerUnit": 0.12,
      "unit": "minutes",
      "currency": "EUR",
      "validFrom": "2026-01-01"
    },
    {
      "country": "FR",
      "ratePerUnit": 0,
      "unit": "minutes",
      "currency": "EUR",
      "validFrom": null
    }
  ]
}
```