# SMS Prices

Note

For more information about SMS services in DIDWW, see [Messaging](../../../../sms/index.html).

Use the SMS Prices resource to read what SMS cost, as priced by the SMS plans assigned to
your DIDWW account.

SMS prices are served by the SMS Rates service:

| Environment | Base URL |
| --- | --- |
| Production | `https://api-sms.didww.com/v3` |
| Sandbox | `https://api-sms-sandbox.didww.com/v3` |

The access token must list `api-sms.didww.com` in its `aud`, on the sandbox host as well.
A token with the `read` scope is enough. See [Prices Resources](../index.html) for
authentication, common rules and errors.

SMS prices are split into four price domains. The account is assigned a plan in each domain
separately, and each domain has its own lookup and its own price file:

| Domain | Prices | Path prefix |
| --- | --- | --- |
| SMS OUT A2P | SMS sent through the account's A2P plan, per destination. | `/v3/sms_out/a2p` |
| SMS OUT P2P | SMS sent through the account's P2P plan, per destination. | `/v3/sms_out/p2p` |
| SMS OUT OTP | SMS sent through the account's OTP plan, per destination. | `/v3/sms_out/otp` |
| SMS IN | SMS arriving on one of the account's numbers. | `/v3/sms_in` |

Prices are in USD, VAT excluded, and are never rounded. When the account holds no price plan
of the service in a domain (no plan at all, or a plan for which the service publishes no
prices), every operation of that domain returns `404` with the error code
`price_plan_not_assigned`.

## Endpoints

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

## Look up SMS prices

Returns the prices of one number or one country in the plan of the domain. Send
`filter[dst_number]`, `filter[dst_country_iso]`, or both. At least one of them is
required.

- With `filter[dst_number]`, the longest destination prefix of the plan covering the number
  wins, and every price of the plan under that prefix is returned.
- With `filter[dst_country_iso]` alone, every price of the plan for that country is
  returned, under every prefix.
- With both, the country narrows the prices before the prefixes are ranked.

See [Look up SMS OUT Prices](lookup-sms-out-prices.html) and
[Look up SMS IN Prices](lookup-sms-in-prices.html).

```
GET /v3/sms_out/a2p/lookup/prices?filter[dst_number]=4915123456789
GET /v3/sms_in/lookup/prices?filter[dst_country_iso]=US
```

## Download SMS price files

Downloads the whole price list of the plan of a domain as a gzipped CSV file. Use `HEAD`
or `If-Modified-Since` to check whether your copy is current.

| Domain | File name |
| --- | --- |
| SMS OUT A2P | `sms_out_a2p_prices.csv.gz` |
| SMS OUT P2P | `sms_out_p2p_prices.csv.gz` |
| SMS OUT OTP | `sms_out_otp_prices.csv.gz` |
| SMS IN | `sms_in_prices.csv.gz` |

See [Get SMS OUT Price File](get-sms-out-price-file.html) and
[Get SMS IN Price File](get-sms-in-price-file.html).

```
GET /v3/sms_out/a2p/prices.csv.gz
HEAD /v3/sms_in/prices.csv.gz
```

## Data reference

- [SMS OUT Price Object](sms-out-price-object.html) - attributes returned by the SMS OUT
  lookups.
- [SMS IN Price Object](sms-in-price-object.html) - attributes returned by the SMS IN
  lookup.

## Common SMS prices use cases

| Use case | Description |
| --- | --- |
| Check what an outbound SMS to a number may cost | Look up the number in the SMS OUT domain you send through and compare the prices of each network. |
| Compare the prices of a destination country | Look up the country with `filter[dst_country_iso]`. |
| Check rejected destinations | Find SMS OUT prices where `reject_sms` is `true`. |
| Estimate the cost of inbound SMS | Look up one of your numbers in the SMS IN domain. |
| Keep a local price list | Download the price file of a domain and refresh it when `Last-Modified` changes. |

## Related resources

| Resource | Description |
| --- | --- |
| [SMS Trunks](../../inventory-resources/sms-trunks/index.html) | Trunks that receive inbound SMS and send outbound SMS. |
| [DIDs](../../inventory-resources/did/index.html) | DID phone numbers owned by the account. |
| [Inbound Call Prices](../inbound-call-prices/index.html) | Prices of inbound calls. |
| [Outbound Call Prices](../outbound-call-prices/index.html) | Prices of outbound calls. |
