Rate shopping
/v1/rates asks every source we quote from for its price to ship one parcel between two postal codes, and returns the quotes side by side, cheapest first, with delivery days and the surcharges itemized. Nothing is bought: a quote is information only.
Every quote says where its price came from (source) and what kind of price it is (rateType):
rateType | Meaning |
|---|---|
retail | The carrier's own counter or website price. |
list | The carrier's published list rate. |
reseller | A postage reseller's own price, usually below retail. You get it by shipping through that reseller. |
Today's source is Stamps.com (source: "stamps"): USPS, UPS and FedEx at Stamps.com's prices, for US domestic shipments. More sources, including carriers' own retail rates, are being added. Stamps.com's FedEx rates are sometimes missing; when a source leaves out a carrier it covers, errors says so.
People can use it at lastscanned.com/rates; agents call the same thing over the API or MCP.
Request
curl "https://api.lastscanned.com/v1/rates?from=94107&to=10001&weight=2.5&residential=true" \
-H "Authorization: Bearer lsk_live_..."Or POST /v1/rates with the same fields as JSON:
curl -X POST https://api.lastscanned.com/v1/rates \
-H "Authorization: Bearer lsk_live_..." \
-H "Content-Type: application/json" \
-d '{"from": "94107", "to": "10001", "weight": 2.5, "length": 12, "width": 10, "height": 6, "residential": true}'| Field | Required | Notes |
|---|---|---|
from | yes | Origin postal code. In the US, a 5-digit ZIP (ZIP+4 is cut to 5). |
to | yes | Destination postal code. |
fromCountry, toCountry | no | Two-letter country codes. Default US. |
weight | yes | Above 0, at most 150 lb. |
weightUnit | no | lb (default), oz, kg or g. |
length, width, height | no | All three or none; each at most 108 in. Carriers price large, light boxes by size. |
dimensionUnit | no | in (default) or cm. |
residential | no | true when delivering to a home. Default false. |
carriers | no | Only these carrier ids (comma-separated, or an array in JSON). Omit for every carrier we can quote. |
In JSON, from and to may also be objects: {"postalCode": "SW1A 1AA", "country": "GB", "residential": true}.
Response
| Field | Meaning |
|---|---|
quotes[] | One per carrier service, cheapest first. |
quotes[].carrier | Our carrier id, the same one GET /v1/track uses. |
quotes[].service, serviceCode | The service's name and the source's code for it. When a price needs carrier packaging, :<packaging> is appended to the code. |
quotes[].amount, currency | The quoted total, surcharges included. |
quotes[].breakdown[] | {description, amount}: the parts of the total as the source itemizes them (base price, fuel, residential, demand surcharges). |
quotes[].rateType, source | What kind of price it is (above), and where it came from. |
quotes[].packaging | Carrier packaging the price requires, such as small_flat_rate_box or fedex_one_rate; null for your own box. |
quotes[].restricted | What the service may carry when it is limited (Media Mail: books and media only), else null. |
quotes[].deliveryDays, estimatedDelivery | Business days and date (YYYY-MM-DD) the carrier quotes, or null. |
quotes[].guaranteed | Whether the carrier guarantees the date. |
cheapest, fastest | source:carrier:serviceCode of the lowest price and of the fewest quoted days, for your own box: restricted services and prices that need carrier packaging are never picked. |
errors[] | {source, carriers, code, message} for each source that couldn't quote (carrier_error, timeout, not_covered for a route it doesn't serve), each carrier a source left out (no_rates), and carriers no source covers (source: null). One failing never fails the rest. |
quotedAt | When the quotes were made. A shipment is re-quoted at most every 6 hours. |
When no carrier could quote, the answer is 502 no_quotes with the same errors, and nothing is spent.
Quotes in different currencies are never ranked against each other: they are grouped by currency, then sorted by price.
Cost
A quote request costs the same as tracking one number:
- No key: 5 free quotes a day per IP (not from cloud or hosting networks).
- API key: one lookup of the account's day.
- MPP: one credit, the same credits tracking spends.
MCP
The get_rates tool takes the same fields in snake_case (from, to, weight, weight_unit, from_country, to_country, residential, length, width, height, dimension_unit, carriers) and returns the same JSON. It is listed only while a rate source is on.