Rate Shop

Beta

POST/v1/operations/shipments/actions/rate-shop

Idempotent with Idempotency-Key header. Learn more

Compares shipping rates across all of the account's carriers and service levels for the given addresses and parcels.

Returns options sorted by rate ascending, after applying the account's freight rules: freight-exempt product lines or customers and free-freight shipping terms return no options, a flat-rate shipping term replaces carrier rates with the flat rate, and a met free-shipping minimum order value zeroes the rate on eligible options.

Live carrier rates require the Shippo integration. Carriers that are not linked to a live-rating account are returned at a rate of 0, while carriers that are linked but whose rates cannot be fetched are left out of the results entirely. Customer portal callers only see carriers and service levels that have been enabled for the portal.

Permissions requiredValues:shipments:readcustomers:readsuppliers:read

The role behind your API key or agent must grant every one of these permissions.

product_line_idsoptional array of string

Product lines of the items being shipped, used to apply freight exemptions.

If any listed product line is freight exempt, no options are returned and exemption_type is freight_exempt.

customer_idoptional string

ID of the customer the shipment is for, used to apply the customer's freight policy and default shipping term.

A customer that is freight exempt through its own policy or through one of its groups, or whose shipping term is free freight, returns no options with exemption_type set to freight_exempt; a flat-rate shipping term replaces carrier rates with the flat rate. Omitting the customer skips all of these rules and returns plain carrier rates.

from_addressoptional object

Origin address.

When omitted, the account's configured ship-from origin is used, which is how customer portal callers rate shop without knowing the seller's address.

namestring

Display name of the address.

phoneoptional string

Phone number associated with the address.

emailoptional string

Email address associated with the address.

typeoptional stringenumValues:standarddrop_ship

How the address is used. Defaults to standard.

standard: a normal shipping or billing address.
drop_ship: an address an order is shipped to directly, typically a third party or end customer rather than the account itself.

street_line_1optional string

First line of the street address.

street_line_2optional string

Second line of the street address.

localityoptional string

City or locality.

stateoptional string

State or administrative area.

postal_codeoptional string

Postal or ZIP code.

countrystring

Two-letter ISO 3166-1 country code, such as US.

to_addressobject

Destination address.

namestring

Display name of the address.

phoneoptional string

Phone number associated with the address.

emailoptional string

Email address associated with the address.

typeoptional stringenumValues:standarddrop_ship

How the address is used. Defaults to standard.

standard: a normal shipping or billing address.
drop_ship: an address an order is shipped to directly, typically a third party or end customer rather than the account itself.

street_line_1optional string

First line of the street address.

street_line_2optional string

Second line of the street address.

localityoptional string

City or locality.

stateoptional string

State or administrative area.

postal_codeoptional string

Postal or ZIP code.

countrystring

Two-letter ISO 3166-1 country code, such as US.

parcelsarray of object

Parcels to rate shop.

weightnumber

Parcel weight in pounds.

lengthnumber

Parcel length in inches.

widthnumber

Parcel width in inches.

heightnumber

Parcel height in inches.

order_totaloptional number

Total value of the order, used to evaluate the free-shipping minimum order value on the customer's shipping term.

Free shipping applies only when the total is strictly above the threshold, and only for the service levels the shipping term allows.

objectstringenumValues:rate_shop_result

Resource type identifier.

optionslistnullable

Available rate options, sorted by rate ascending.

Empty when freight is exempt for the order.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of rate_shop_option

Resources in this page.

objectstringenumValues:rate_shop_option

Resource type identifier.

carriercarriernullable

The carrier that would handle the shipment.

idstring

Carrier ID.

objectstringenumValues:carrier

Resource type identifier.

namestring

Human-readable name for the carrier, unique among the carriers visible to your account.

codestringnullableenumValues:fedexupsusps

Well-known carrier identifier, set only for recognized carriers and absent for custom ones.

fedex, ups, usps: integrated carriers managed through Shippo (live rating and labels).
will_call: customer picks the order up; no carrier shipment.
delivery: delivered by your own vehicles/drivers.
ltl, ltl1: less-than-truckload freight carriers.
freight_collect: freight billed to and arranged by the receiver.

account_numberstringnullable

Your account number with this carrier.

UPS and USPS carrier accounts are connected to Shippo using this number; FedEx carriers authorize through OAuth instead, so their account number is not used to connect them.

customer_portal_visibilitystringenumValues:visiblehidden

Whether customers can see and select this carrier at checkout in the customer portal.

ownerownernullable

Provenance of this carrier.

System-owned carriers are platform-provided defaults shared across all accounts and cannot be updated or deleted; account-owned carriers are custom to your account.

objectstringenumValues:owner

Resource type identifier.

typestringenumValues:systemaccount

Where this resource came from.

system: a platform-provided default shared across all accounts; not editable.
account: created and owned by a specific account; the account field identifies which.

accountaccountnullable

The account that owns this resource.

Present only when type is account; system-owned resources have no owning account.

idstring

Account ID.

objectstringenumValues:account

Resource type identifier.

namestring

The account's display name.

default_billing_addressaddressnullable

The address billed by default on orders for this account.

default_shipping_addressaddressnullable

The address shipped to by default on orders for this account.

brandingaccount_brandingnullable

Customer-facing branding for the account, such as the logo, support contacts, and social links.

portalaccount_portalnullable

The account's customer portal settings, including the portal URL slug.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

service_levelslistnullable

Shipping service levels offered by this carrier (e.g. ground, overnight).

At most 10 service levels are returned inline; use the carrier's service levels endpoint to page through the full set.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of service_level

Resources in this page.

idstring

Service level ID.

objectstringenumValues:service_level

Resource type identifier.

namestring

Human-readable name for the service level, shown to customers at checkout when the service level is visible.

service_level_tokenstring

Carrier-specific code identifying this service level (e.g. fedex_ground, ups_next_day_air).

For service levels synced from a connected carrier this is the carrier's own token, which is what rate shopping and label purchase are keyed on; for service levels you create yourself it is the code you supplied.

customer_portal_visibilitystringenumValues:visiblehidden

Whether customers can see and select this service level at checkout in the customer portal.

is_defaultboolean

Whether this is the carrier's default service level, pre-selected when the carrier is chosen.

Each carrier has at most one default; setting a new default clears the previous one. A default service level cannot be deleted until another service level takes its place or the flag is cleared.

ownerownernullable

Provenance of this service level.

System-owned service levels are platform-provided defaults that cannot be updated or deleted; account-owned service levels are custom to your account.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

deleted_atstring (date-time)nullable

Soft-delete timestamp.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

service_levelservice_levelnullable

The carrier's service level, such as ground or overnight.

idstring

Service level ID.

objectstringenumValues:service_level

Resource type identifier.

namestring

Human-readable name for the service level, shown to customers at checkout when the service level is visible.

service_level_tokenstring

Carrier-specific code identifying this service level (e.g. fedex_ground, ups_next_day_air).

customer_portal_visibilitystringenumValues:visiblehidden

Whether customers can see and select this service level at checkout in the customer portal.

is_defaultboolean

Whether this is the carrier's default service level, pre-selected when the carrier is chosen.

Each carrier has at most one default; setting a new default clears the previous one. A default service level cannot be deleted until another service level takes its place or the flag is cleared.

ownerownernullable

Provenance of this service level.

System-owned service levels are platform-provided defaults that cannot be updated or deleted; account-owned service levels are custom to your account.

objectstringenumValues:owner

Resource type identifier.

typestringenumValues:systemaccount

Where this resource came from.

system: a platform-provided default shared across all accounts; not editable.
account: created and owned by a specific account; the account field identifies which.

accountaccountnullable

The account that owns this resource.

Present only when type is account; system-owned resources have no owning account.

idstring

Account ID.

objectstringenumValues:account

Resource type identifier.

namestring

The account's display name.

default_billing_addressaddressnullable

The address billed by default on orders for this account.

default_shipping_addressaddressnullable

The address shipped to by default on orders for this account.

brandingaccount_brandingnullable

Customer-facing branding for the account, such as the logo, support contacts, and social links.

portalaccount_portalnullable

The account's customer portal settings, including the portal URL slug.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

ratenumber

Quoted shipping rate for this carrier and service level.

0 when the carrier is not linked to a live-rating account, or when the shipping term's free-shipping minimum order value has been met and this option qualifies for free shipping. When the customer's shipping term applies a flat rate, that amount replaces the rate on every option that is not already free.

estimated_daysintegernullable

Estimated number of days until delivery, when the carrier provides an estimate.

exemption_typestringnullable

Why a special freight outcome was applied to these options, if any.

freight_exempt: the order is exempt from freight; no options are returned.
minimum_order_met: the customer's shipping term sets a free-shipping minimum order value and the order total exceeded it, so options are rated at zero. If the shipping term restricts free shipping to specific service levels, only those options are zeroed and the rest keep their carrier or flat rate.
flat_rate: the customer's shipping term applies a flat shipping rate, which replaced every option's carrier rate.
none: standard carrier rates apply with no exemption.

flat_ratenumbernullable

Flat shipping amount applied to the options.

Set when the customer's shipping term applies a flat rate, including when a met free-shipping minimum has already rated some options at zero.

Responses

200

Successful response for Rate Shop

Rate Shop

import Augno from '@augno/sdk';

const client = new Augno({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const rateShopResult = await client.operations.shipments.actions.rateShop({
  parcels: [
    {
      weight: 5,
      length: 12,
      width: 8,
      height: 6,
    },
  ],
  to_address: {
    name: 'Destination',
    street_line_1: '456 Oak Avenue',
    locality: 'Los Angeles',
    state: 'CA',
    postal_code: '90001',
    country: 'US',
  },
  from_address: {
    name: 'Origin Warehouse',
    street_line_1: '123 Main Street',
    locality: 'San Francisco',
    state: 'CA',
    postal_code: '94105',
    country: 'US',
  },
});

console.log(rateShopResult.exemption_type);

import Augno from '@augno/sdk';

const client = new Augno({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const rateShopResult = await client.operations.shipments.actions.rateShop({
  parcels: [
    {
      weight: 5,
      length: 12,
      width: 8,
      height: 6,
    },
  ],
  to_address: {
    name: 'Destination',
    street_line_1: '456 Oak Avenue',
    locality: 'Los Angeles',
    state: 'CA',
    postal_code: '90001',
    country: 'US',
  },
  from_address: {
    name: 'Origin Warehouse',
    street_line_1: '123 Main Street',
    locality: 'San Francisco',
    state: 'CA',
    postal_code: '94105',
    country: 'US',
  },
});

console.log(rateShopResult.exemption_type);

200 example

{
  "object": "rate_shop_result",
  "options": {
    "object": "list",
    "page_info": {
      "next_page_url": null,
      "previous_page_url": null,
      "has_next_page": false,
      "has_prev_page": false
    },
    "data": [
      {
        "object": "rate_shop_option",
        "carrier": null,
        "service_level": null,
        "rate": 12.34,
        "estimated_days": 3
      }
    ]
  },
  "exemption_type": "none",
  "flat_rate": null
}

{
  "object": "rate_shop_result",
  "options": {
    "object": "list",
    "page_info": {
      "next_page_url": null,
      "previous_page_url": null,
      "has_next_page": false,
      "has_prev_page": false
    },
    "data": [
      {
        "object": "rate_shop_option",
        "carrier": null,
        "service_level": null,
        "rate": 12.34,
        "estimated_days": 3
      }
    ]
  },
  "exemption_type": "none",
  "flat_rate": null
}

Rate Shop

Authorization

Request Body

Returns

Responses