Get Shipping Rates

POST

/shipping-addresses/{shipping_address_id}/rate

Retrieves available shipping rates for shipping the given pieces to a shipping address. Rates are fetched in real time from shipping providers.

Pass the id of the chosen rate as rate_id to createShipment before the rate’s expired_at. The pieces, insurance and customs details used for the shipment are taken from the rate request, so request the rate with the same options you want to ship with.

International shipments need customs information: either custom_items (each with a description and declared value, plus an hs_tariff_code when the shipping address has requires_hs_tariff_codes), or a customs_description and declared_value_in_cents.

Authorizations

Send your API key in the x-api-key header. See Authentication.

Parameters

Path Parameters

shipping_address_id

required

string

Request Body ^required

object

items

required

The pieces to ship. Required, at least one.

Array<object>

>= 1 items

object

piece_id

required

ID of the piece to ship.

integer

>= 1

declared_value_in_cents

Declared value of this piece, in cents. Rounded to whole cents.

number | null

customs_description

Description of this piece for customs.

string

has_complete_scan

boolean

custom_items

Customs line items describing the contents, for international shipments.

Array<object>

object

declared_value_in_cents

required

Declared value of the item, in cents. Rounded to whole cents.

number

description

required

Description of the item for customs.

string

hs_tariff_code

Harmonized System tariff code. Required when the shipping address has requires_hs_tariff_codes, unless contents_type is Documents.

string

signature_on_delivery

Require a signature on delivery.

boolean

is_insured

Insure the shipment. Set declared_value_in_cents to the insured value.

boolean

declared_value_in_cents

Total declared value of the shipment, in cents. Used for insurance, and for customs when custom_items is not given. Rounded to whole cents.

number | null

customs_description

Description of the contents for customs, for international shipments without custom_items.

string

Examples

{
  "items": [
    {
      "piece_id": 1234000
    },
    {
      "piece_id": 1234001
    }
  ]
}

{
  "items": [
    {
      "piece_id": 123456789
    }
  ],
  "is_insured": true,
  "declared_value_in_cents": 100000
}

{
  "items": [
    {
      "piece_id": 120000
    }
  ],
  "custom_items": [
    {
      "description": "men's cotton trousers",
      "declared_value_in_cents": 20000,
      "hs_tariff_code": "620520"
    }
  ]
}

Responses

200

Success

object

rates

Array<object>

object

id

string | null

a1b2c3d4-e5f6-7890-abcd-ef1234567890

carrier_type

string

USPS - Express

carrier_service

string

Express

price_in_cents

integer

5335

created_at

string format: date-time

expired_at

string format: date-time

tracking_available

boolean

true

insurance

object

total_insured_value_in_cents

integer

price_in_cents

integer

error

string

Example

{
  "rates": [
    {
      "carrier_service": "Express",
      "carrier_type": "USPS - Express",
      "created_at": "2020-05-10T10:00:00Z",
      "expired_at": "2020-05-13T10:00:00Z",
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "price_in_cents": 5335,
      "tracking_available": true
    },
    {
      "carrier_service": "Priority",
      "carrier_type": "USPS - Priority",
      "created_at": "2020-05-10T10:00:00Z",
      "expired_at": "2020-05-13T10:00:00Z",
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "price_in_cents": 1695,
      "tracking_available": true
    },
    {
      "carrier_service": "GroundAdvantage",
      "carrier_type": "USPS - Ground Advantage",
      "created_at": "2020-05-10T10:00:00Z",
      "expired_at": "2020-05-13T10:00:00Z",
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "price_in_cents": 945,
      "tracking_available": true
    }
  ]
}

401

The x-api-key header is missing or the key is not valid, or the caller can’t access an ID in the request. IDs that don’t exist return the same response as IDs the caller can’t access.

Error envelope returned with 4xx and 5xx responses.

object

error

object

code

Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500.

integer

401

message

Human-readable description of the error.

string

type

The kind of error, for example Authorization or REST.

string

REST

fields

Returned only with 422 responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input.

object

key

additional properties

Array<string>

Examples

{
  "error": {
    "code": 401,
    "message": "The request does not include a valid access token. Please provide a valid access token.",
    "type": "Authorization"
  }
}

{
  "error": {
    "code": 401,
    "message": "x-api-key: x-api-key is invalid",
    "type": "REST"
  }
}

{
  "error": {
    "code": 401,
    "message": "User does not have access to requested resource.",
    "type": "Authorization"
  }
}

404

The referenced resource is accessible, but the requested item does not exist, for example a pending operation. IDs the caller can’t access, or that don’t exist at all, return 401 instead.

Error envelope returned with 4xx and 5xx responses.

object

error

object

code

Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500.

integer

401

message

Human-readable description of the error.

string

type

The kind of error, for example Authorization or REST.

string

REST

fields

Returned only with 422 responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input.

object

key

additional properties

Array<string>

Example

{
  "error": {
    "code": 404,
    "message": "piece_id: Piece with ID 14460059 does not have outstanding Operation of type Recycle.",
    "type": "REST"
  }
}

422

The request body failed validation. The message names the invalid field.

Error envelope returned with 4xx and 5xx responses.

object

error

object

code

Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500.

integer

401

message

Human-readable description of the error.

string

type

The kind of error, for example Authorization or REST.

string

REST

fields

Returned only with 422 responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input.

object

key

additional properties

Array<string>

Example

{
  "error": {
    "code": 422,
    "message": "label: must have a value",
    "type": "REST",
    "fields": {}
  }
}