# Prices Resources

Use Prices Resources to read the prices of the plans assigned to your DIDWW account. You can
look up what one number costs (for SMS, also every price of one country), or download the
whole price list of a plan as a compressed CSV file.

Prices are served by three dedicated services, each on its own host. They are not served by
`api.didww.com`: send each request to the host of the service whose prices you need.

| Service | Prices | Production | Sandbox |
| --- | --- | --- | --- |
| Inbound Call Rates | Inbound calls to toll-free, shared-cost and metered numbers. | `https://api-vin.didww.com/v3` | `https://api-vin-sandbox.didww.com/v3` |
| Outbound Call Rates | Outbound calls to each destination, including scheduled price changes. | `https://api-vout.didww.com/v3` | `https://api-vout-sandbox.didww.com/v3` |
| SMS Rates | SMS IN, and SMS OUT for the A2P, P2P and OTP plans. | `https://api-sms.didww.com/v3` | `https://api-sms-sandbox.didww.com/v3` |

All prices are the values of the plan assigned to the account, in USD, VAT excluded.

## Resource overview

| Resource | Use it to |
| --- | --- |
| [Inbound Call Prices](inbound-call-prices/index.html) | Look up the inbound call prices of a number, or download the inbound call price file. |
| [Outbound Call Prices](outbound-call-prices/index.html) | Look up the current and next outbound call prices of a number, or download the outbound call price file. |
| [SMS Prices](sms-prices/index.html) | Look up the SMS IN or SMS OUT prices of a number or a country, or download the SMS price files. |

## Endpoints

| Service | Action | Method | Endpoint |
| --- | --- | --- | --- |
| Inbound Call Rates | Look up prices | `GET` | `/v3/lookup/prices` |
| Inbound Call Rates | Download price file | `GET`, `HEAD` | `/v3/prices.csv.gz` |
| Outbound Call Rates | Look up prices | `GET` | `/v3/lookup/prices` |
| Outbound Call Rates | Download price file | `GET`, `HEAD` | `/v3/prices.csv.gz` |
| SMS Rates | Look up SMS IN prices | `GET` | `/v3/sms_in/lookup/prices` |
| SMS Rates | Download SMS IN price file | `GET`, `HEAD` | `/v3/sms_in/prices.csv.gz` |
| SMS Rates | Look up SMS OUT prices | `GET` | `/v3/sms_out/{a2p|p2p|otp}/lookup/prices` |
| SMS Rates | Download SMS OUT price file | `GET`, `HEAD` | `/v3/sms_out/{a2p|p2p|otp}/prices.csv.gz` |

Inbound Call Rates and Outbound Call Rates use the same paths. The host of the request selects the
service.

## Authentication

Every request is authenticated with a bearer access token in the `Authorization` header:

```
Authorization: Bearer [access token]
```

Mint the token with `POST /token` on the token service of the environment you call
(`https://auth.didww.com/token` for Production, `https://auth-sandbox.didww.com/token`
for Sandbox), with an API key of that environment. A token minted in one environment is
refused by the other. See [Authentication](../authentication.html#authentication-v35).

A service accepts a token only when the token's `aud` lists the audience of that service.
The audience is the production host name of the service, on the production and on the
sandbox host alike:

| Service | Audience (`aud`) |
| --- | --- |
| Inbound Call Rates | `api-vin.didww.com` |
| Outbound Call Rates | `api-vout.didww.com` |
| SMS Rates | `api-sms.didww.com` |

These audiences apply to the price lookup, download and file-header endpoints listed
above. To configure phone numbers or voice and SMS trunks, use `api.didww.com`.
See [Audiences](../authentication.html#authentication-audiences-v35) for the complete service mapping.

Mint one token per service, or one token that lists every service you call. Every prices
operation only reads, so a token minted with the `read` scope is enough. For example, the
body of a `POST /token` request for a read-only token accepted by all three services:

```
1{
2  "aud": ["api-vin.didww.com", "api-vout.didww.com", "api-sms.didww.com"],
3  "scope": "read"
4}
```

## Price lookups

A lookup is a JSON:API `GET` request that returns a collection of resources of type
`prices`.

- Send `Accept: application/vnd.api+json`. A request whose `Accept` header admits
  neither `application/vnd.api+json` nor `*/*` returns `406 Not Acceptable`.
- `filter` is the only query parameter a lookup reads. `sort`, `page`, `fields`,
  `include`, a filter the lookup does not support and any unrecognised parameter return
  `400 Bad Request`.
- `data` is never empty. When nothing in the plan matches the filters, the response is
  `404` with the error code `price_not_found`.
- `meta.total_records` is the number of resources in `data`. Lookups are not paginated.
- Each resource has a UUID `id` that names the answering price. It is a name, not an
  address: there is no endpoint that returns a single price by its ID.
- Prices are decimal strings. In inbound call, outbound call, and SMS OUT lookups, a destination
  that the plan rejects is still returned: its `reject_calls` or `reject_sms` attribute
  is `true` and its current price (`rate` and `connection_fee`, or `price`) is `null`.

## Price files

A price file contains the whole price list of the plan assigned to the account.

- `GET` returns the file as a gzipped CSV (`Content-Type: application/gzip`): UTF-8, LF
  line endings, and a header row. The file is served whole, without byte ranges.
- `HEAD` returns the same headers without the body, so you can check whether your copy is
  current before you download the file.
- The file belongs to the account. One URL returns each account the file of its own plan.

A successful response carries these headers:

| Header | Description |
| --- | --- |
| Content-Disposition | `attachment` with the file name of the price domain, for example `voice_in_prices.csv.gz`. |
| Last-Modified | HTTP date of the later of the last change of the file content and the last change of the account's plan assignment. Send it back in `If-Modified-Since`. |
| Cache-Control | Always `private`. The file is served per account. |
| Accept-Ranges | Always `none`. The file is served whole. |
| Vary | Always `Authorization`. A cache keyed by the URL alone must not return the file to another account. |
| Content-Length | Size of the gzipped file in bytes. A `HEAD` response returns the size that the download sends. |

### Conditional requests

Conditional requests use `Last-Modified` and `If-Modified-Since` only:

- Send the `Last-Modified` value of the copy you hold in the `If-Modified-Since` request
  header. If the file has not changed since that date, the response is `304 Not Modified`
  with the headers of the `200` response except `Content-Length`, and no body.
- No `ETag` is sent. A request that carries `If-None-Match` is always answered in full,
  and its `If-Modified-Since` header is ignored.
- Because `Last-Modified` also reflects changes of the plan assignment, an account that is
  moved to another plan never receives `304` for the prices of the plan it left.

When the file cannot be served, for example because the assigned plan has no generated file
yet, the response is `503 Service Unavailable` with the error code `serving_failure` and a
`Retry-After` header.

## Errors

Errors are returned as JSON:API error documents (see [Error
objects](../../specification/errors/index.html#api-error-objects)).
Responses to `HEAD` requests carry no body. Each prices service counts the requests of
an account in its own budget; once it is spent, that service returns `429 Too Many Requests`.

| Status | Error code | Returned when |
| --- | --- | --- |
| 400 | Numeric JSON:API code, for example `102` | Lookups only. A filter is missing or malformed, a filter is not supported, or the request carries another query parameter (`sort`, `page`, `fields`, `include` or an unrecognised one). |
| 401 | `401` | The bearer token was refused: absent, malformed, expired, signed by a key this service does not hold, minted for another audience or environment, presented from an address outside the IP allowlist of the API key it was minted with, or naming an account this service has no record of. The response carries `WWW-Authenticate: Bearer error="invalid_token"`. |
| 403 | `403` | The token does not carry the `read` scope (title `Insufficient scope`). The response carries `WWW-Authenticate: Bearer error="insufficient_scope"`. |
| 404 | `price_plan_not_assigned` | No price plan is assigned to the account. For SMS Rates, the account holds no price plan of the service in the requested domain. |
| 404 | `price_not_found` | Lookups only. Nothing in the plan matches the filters. |
| 406 |  | Lookups only. The `Accept` header admits neither `application/vnd.api+json` nor `*/*`. |
| 429 | `too_many_requests` | The request budget of the account on this service for the current window is spent. `Retry-After` gives the number of seconds to wait. |
| 503 | `serving_failure` | Price files only. The file could not be served. `Retry-After` gives the number of seconds to wait. |

Example of an error response:

```
HTTP/1.1 404 Not Found
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "title": "Price plan not assigned",
      "detail": "No price plan is assigned to this account.",
      "code": "price_plan_not_assigned",
      "status": "404"
    }
  ]
}
```

## Common prices use cases

| Use case | Description |
| --- | --- |
| Show the price of a call before it is made | Look up a number on Outbound Call Rates and read `rate`, `connection_fee` and the billing increments. |
| Track upcoming outbound call price changes | Read the `next_` attributes, `effective_at` and `comment` of a lookup, or the Next, Effective date and Comment columns of the outbound call price file. |
| Estimate the cost of inbound toll-free traffic | Look up a toll-free number on Inbound Call Rates, optionally for a given source country. |
| Compare SMS prices of a destination country | Look up the SMS OUT prices of a country with `filter[dst_country_iso]`. |
| Keep a local copy of a price list | Download a price file, then check it periodically with `HEAD` or a conditional `GET` that sends `If-Modified-Since`. |

## Related resources

- [Authentication](../authentication.html#authentication-v35) - Mint the access token that the prices services
  accept.
- [Download Pricelists](../../../phone-numbers/buy-numbers/download-pricelists.html) -
  Download price lists from the user panel.
- [DIDWW Pricing](../../../billing/billing-and-prices/didww-pricing.html) - Overview of DIDWW
  pricing models.
