---
title: "Get shipping rates"
method: POST
path: "/v1/rates"
tags: ["ship"]
---

# Get shipping rates

`POST /v1/rates`

## Request

- Base URL: `https://api.noerrands.com/c/ship`
- URL: `https://api.noerrands.com/c/ship/v1/rates`
- Auth: HTTP bearer

Quote a US package (from, to, weight and size) and get up to 6 carrier options, cheapest first, each with its own quote_id, delivery days and all-in price_cents (the carrier rate x 142% + 150); free (up to 30 quotes an hour per account), nothing is bought, and every quote expires in 60 minutes. Set return_label true for a return (from = the human, to = the merchant's returns address).

## Request body

- object
  - `from` object, required: Where the package starts. For a return, the human sending it back.
    - `name` string, required: Recipient or sender name, 1-40 characters.
    - `company` string: Optional company line, up to 40 characters.
    - `line1` string, required: Street address, up to 64 characters.
    - `line2` string: Apartment, suite, or unit, up to 64 characters.
    - `city` string, required
    - `state` string, required: Two-letter US state code.
    - `zip` string, required: ZIP code, 5 digits or ZIP+4.
    - `country` 'US': US only in v0.
    - `phone` string: Optional. Some carriers print it or call it about a delivery problem.
    - `email` string: Optional. Some carriers send delivery notices to it.
  - `to` object, required: Where it goes. For a return, the merchant's returns address, exactly as the merchant gives it.
    - `name` string, required: Recipient or sender name, 1-40 characters.
    - `company` string: Optional company line, up to 40 characters.
    - `line1` string, required: Street address, up to 64 characters.
    - `line2` string: Apartment, suite, or unit, up to 64 characters.
    - `city` string, required
    - `state` string, required: Two-letter US state code.
    - `zip` string, required: ZIP code, 5 digits or ZIP+4.
    - `country` 'US': US only in v0.
    - `phone` string: Optional. Some carriers print it or call it about a delivery problem.
    - `email` string: Optional. Some carriers send delivery notices to it.
  - `parcel` object, required: The package. weight_oz is always required. Then either all three dimensions in inches, or a preset, or neither (the carrier then prices by weight).
    - `weight_oz` number, required: Weight in ounces, packed. 16 oz = 1 lb. Use what the human says it weighs.
    - `length_in` number: Inches.
    - `width_in` number: Inches.
    - `height_in` number: Inches.
    - `preset` 'envelope' | 'small_box' | 'medium_box' | 'large_box' | 'flat_rate_envelope' | 'small_flat_rate_box' | 'medium_flat_rate_box' | 'large_flat_rate_box': Instead of dimensions: envelope (padded envelope, 12 x 9.5 x 1 in); small_box (small box, 9 x 6 x 3 in); medium_box (medium box, 12 x 10 x 6 in); large_box (large box, 18 x 14 x 10 in); flat_rate_envelope (USPS Priority Mail flat rate envelope); small_flat_rate_box (USPS Priority Mail small flat rate box); medium_flat_rate_box (USPS Priority Mail medium flat rate box); large_flat_rate_box (USPS Priority Mail large flat rate box). Flat rate presets are priced by USPS Priority Mail only.
  - `return_label` boolean: True for a return label (then use create_return_label to buy it).

## Response `200`

Success.

- object
  - `quotes` object[], required: Cheapest first, at most 6.
    - `quote_id` string, required: Opaque id, "sq_...". Pass it to buy_label or create_return_label.
    - `carrier` string, required: USPS, UPS, FedEx, ...
    - `service` string, required: The carrier's service name, e.g. GroundAdvantage, Priority.
    - `delivery_days` integer: Business days in transit, as the carrier estimates it.
    - `price_cents` integer, required: What the label costs in credits, everything included.
    - `retail_cents` integer: What the same label costs over a post office counter, when the carrier reports it. For comparison only.
    - `qr_code_available` boolean, required: True for USPS: the label can come as a QR code the human shows at a post office instead of printing.
  - `expires_at` string, date-time, required: Every quote above can be bought until then (60 minutes).
  - `return_label` boolean, required
  - `address_notes` string[], required
  - `balance_cents` integer, required: General credit available right now.

## Other responses

- `400`: invalid_request
- `401`: unauthorized. Carries WWW-Authenticate: Bearer resource_metadata="..."
- `403`: forbidden_scope: a write tool called with a read-only key.
- `404`: not_found
- `429`: rate_limited
- `502`: provider_error

---

[API](https://skmtc.dev/noerrands/apis/no-errands-ship-api.md) · [All operations](https://skmtc.dev/noerrands/apis/no-errands-ship-api/llms.txt) · [OpenAPI document](https://skmtc.dev/noerrands/apis/no-errands-ship-api/revisions/f0615c6bd5d8?raw)