Skip to main content

​
All-in pricing and the surcharge schedule

Pricing and rate resolution explains how the base per-unit price is resolved — the precedence between a per-operator override, an organization markup, and the platform default. That page stops at the base rate. This page covers what stacks on top of it: the optional and registration add-ons (carrier registration, call recording, transcription, premium support) that decide what a lane really costs when every fee is counted. Read this page when a base-rate quote is not enough — for example when answering “what does US A2P SMS cost all-in” for a sales review, or when reconciling a recorded voice bill.

​
What allIn=true returns

GET /api/v1/pricing/estimate normally returns only the base per-unit rate. Pass allIn=true and the response gains an allIn object with two things:
  • baseRatePerUnit — the base rate resolved through the precedence ladder described in Pricing and rate resolution (or null when no rate is published for the lane).
  • surcharges[] — the itemized menu of add-ons that may apply to that lane for that destination, each with its own price and pricing dimension.
allIn defaults to off so the legacy response payload keeps its exact shape; opt into it when you need the full picture.

​
The surcharge code catalog

Every add-on the estimate can itemize is identified by one of four surcharge codes. The catalog is deliberately closed — these are the only codes the endpoint ever returns: Each catalog entry carries a machine-stable code, a human-readable label, the unitPrice in USD, the pricing dimension (appliesPer), an optional triggersWhen condition, and a plain-English note you can show to a customer verbatim.

​
The per-channel schedule

Which codes apply depends on the channel — the schedule is a fixed menu per channel, not a flat list:
  • SMS — a2p_10dlc_registration, premium_support.
  • Voice — call_recording, transcription, premium_support.
  • WhatsApp, RCS, Viber, Email — premium_support only.
The destination country gates one entry further: a2p_10dlc_registration applies only when the resolved destination country is US. A German SMS estimate returns the same base rate plus premium_support; the identical request to a US number adds the registration line. Channels with no add-ons return an empty surcharges list, not an error.

​
The opt-in include filter

When you only care about a subset of the menu — the sales-demo “show me just the registration fee” flow — pass include with one or more surcharge codes. The endpoint accepts a repeated query parameter (include=a2p_10dlc_registration&include=premium_support) or a comma-separated string (include=a2p_10dlc_registration,premium_support); both shapes normalize to the same filtered list. Codes outside the catalog are rejected with a 422.

​
appliesPer: three pricing dimensions

Read each surcharge through its appliesPer value — it tells you how the unit price scales:
  • message — a per-message fee that multiplies with message count on a messaging lane.
  • minute — a per-minute fee on a voice lane (recording and transcription both price this way).
  • monthly_flat — a flat monthly fee, independent of volume (US A2P registration and premium support both price this way).
Never sum a base rate and a monthly-flat surcharge into a single per-message number — the estimate keeps them as separate line items precisely so you can read each on its own dimension.

​
Relationship to the rate resolver

The base-rate precedence — per-operator override verbatim, then organization markup, then the platform default — applies to the base rate only. Surcharges are not resolved through that ladder and are not marked up: they itemize additively on top of whatever base the resolver returned. A per-operator override that lowers your US SMS base rate does not touch the US A2P registration fee; both appear in the same allIn block and the two layers stay cleanly separated.

​
Worked example

Field by field:
  • channel, to — echo the lane you asked about.
  • countryCode — the destination country the endpoint resolved from to; this is what gates the US-only registration entry.
  • rate — the base-rate block, present whenever a rate is published (null otherwise).
  • allIn.baseRatePerUnit — the same resolved base rate, repeated inside the all-in block so a consumer reading only allIn has the full picture.
  • allIn.currency — USD; when no base rate is published it still says USD.
  • allIn.surcharges[].code — one of the four catalog codes above.
  • allIn.surcharges[].unitPrice + appliesPer — the fee and the dimension it scales on; read them together.
  • triggersWhen / note — display-ready strings explaining when the fee applies and what it covers.
When no base rate is published for the lane, rate is null and baseRatePerUnit is null — the surcharge menu still returns so the add-on picture is complete even for contact-sales lanes.