Get rates

Origin address — either a saved address ID (string) or an inline object. Same fields as to_address.

street1, city, zip are required.
state is required only for US, CA and AU addresses.
country (string, optional, default US).

Destination address — either a saved address ID (string) or an inline object.

street1 (string, required) · street2 (string, optional)
city (string, required)
state (string) — required only for US, CA and AU addresses. Most countries have no province system; omit it or send null.
zip (string, required)
country (string, optional, default US) — two-letter ISO code
name, company, phone, email (optional)
residential (boolean, optional) — override. Omit and the address is classified for you.

International: set country to any destination and rates come back the same way. You do not need a customs declaration to quote — but POST /v1/labels will require a customs object to buy one.

Package dimensions and weight, as an inline object. All four of length, width, height and weight are required and must be positive numbers. Optional: weight_unit (oz default | lb | g | kg) and dimension_unit (in default | cm).

A saved parcel ID is not supported. Passing a string here returns 400 PARCEL_ID_NOT_SUPPORTED — there is no saved-parcel store to resolve it against, and guessing the geometry would quote a price the purchase could not honour.

Keep only rates quoted on these carrier accounts — the carrier_account_id value returned on each rate. Every organization has one account per carrier with atoship; list them with GET /v1/carrier-accounts. Use this to choose between an atoship account and your own linked (BYOCA) account when both quote the same carrier, which carriers cannot distinguish. Takes precedence over carriers — when both are supplied, carriers is ignored; services still applies on top. A filter matching nothing returns an empty data array.

Keep only rates from these carriers. Matching ignores case and punctuation, so USPS, usps and U.S.P.S. are equivalent. Ignored when carrier_account_ids is supplied. A filter matching nothing returns an empty data array — it never falls back to the unfiltered set.

Keep only these services. Matching ignores case and punctuation and accepts any of: the full service name ("USPS Ground Advantage"), the name without its carrier prefix ("Ground Advantage"), or the code-style token ("usps_ground_advantage"). Combines with carriers as AND.

Optional accessorials. signature_confirmation (boolean) requires a signature on delivery — there are no signature levels, only true/false. The signature fee is already included in the returned rate, and requesting it returns FEWER options, because carriers that cannot guarantee a signature are excluded rather than shipping your parcel unsigned. saturday_delivery (boolean) behaves the same way. insurance_amount (number) declares a value for insurance.

Ship date, YYYY-MM-DD or an ISO 8601 timestamp with offset. Rates that depend on the day of the week are priced against it. Send the same value to POST /v1/labels.

Skip destination address validation. Use only after the caller has confirmed a suggested address — skipping it on an unverified address ships to whatever was typed.