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, phone, email (optional)
company (string, optional) — printed on the label with the name. UPS has no separate company field: when both are sent it prints the company as the name line and name as an attention line, each truncated to 35 characters. Every other carrier prints them as two separate lines.
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.

Multi-piece shipment — one shipment, several boxes, one tender. Each element has the same shape as parcel. Use this instead of parcel, never alongside it: sending both returns 400 VALIDATION_ERROR. Maximum 20 boxes.

The quote returned is the price of the WHOLE shipment, not of one box. The carrier prices the boxes together and issues a tracking number and a label for each of them, which is what makes this different from creating several single-box labels.

Availability is per service, not per carrier. Currently only UPS Ground can be bought as a multi-piece shipment. A multi-piece request on any other service returns an empty rate list rather than an error — a service is listed here only after a real purchase has shown it returns a distinct tracking number and a printable label for every box.

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.