/rates

Request

Example Request

The example request below contains all available parameters. It is recommended to provide as much data as possible to take full advantage of Intuitive Shipping’s rating and conditions engine.

POST /rates
{
  "origin": {
    "country": "CA",
    "province": "ON",
    "postal_code": "K2P1L4",
    "city": "Ottawa",
    "address1": "150 Elgin St.",
    "address2": null,
    "type": "commercial",
    "company_name": "Jamie D's Emporium"
  },
  "destination": {
    "country": "CA",
    "province": "ON",
    "postal_code": "K1M1M4",
    "city": "Ottawa",
    "address1": "24 Sussex Dr.",
    "address2": null,
    "type": "residential",
    "company_name": null
  },
  "customer": {
    "name": "John Smith",
    "tags": [],
    "telephone": null,
    "fax": null,
    "email": null,
    "lifetime_order_count": 0,
    "lifetime_order_value": 199.99,
  },
  "delivery": {
    "date": 2022-01-01,
    "time": 12:00,
    "type": "shipping"
  },
  "products": [{
    "title": "Short Sleeve T-Shirt",
    "sku": null,
    "quantity": 1,
    "price": 29.99,
    "length": 24.00,
    "width": 10.00,
    "height": 10.00,
    "weight": 1000.00,
    "length_unit": "cm",
    "weight_unit": "g",
    "vendor": "Jamie D's Emporium",
    "requires_shipping": true,
    "fulfillment_service": "manual",
    "properties": [],
    "tags": [],
    "product_id": 48447225880,
    "variant_id": 258644705304
   }],
  "currency": "USD",
  "locale": "en"
  "source": "checkout"
}

Example Request

In some cases, you may only have a limited data set. The example request below contains only the required parameters for Intuitive Shipping to return rates in most cases.

POST /rates
{
  "origin": {
    "country": "CA",
    "province": "ON",
    "postal_code": "K2P1L4"
  },
  "destination": {
    "country": "CA",
    "province": "ON",
    "postal_code": "K1M1M4"
  },
  "products": [{
    "quantity": 1,
    "product_id": 48447225880,
    "variant_id": 258644705304
  }],
  "currency": "USD"
}

Request Parameters

Parameters marked ! are required.

Origin

The shipment origin where the products will be shipped from.

country !	string	ISO-2 digit country code.
province !	string	ISO-2 digit province/state code.
postal_code !	string
city	string|null
address1	string|null
address2	string|null
type	string	residential,commercial,unknown
company_name	string|null

Destination

The shipment destination where the products will be shipped to.

country !	string	ISO-2 digit country code.
province !	string	ISO-2 digit province/state code.
postal_code !	string
city	string|null
address1	string|null
address2	string|null
type	string	residential,commercial,unknown
company_name	string|null

Customer

Customer details. Used by our conditions engine.

name	string|null	Concat customer name.
tags	array
telephone	string|null
fax	string|null
email	string|null
lifetime_order_count	integer	Count of previous orders.
lifetime_order_value	float	Total value of previous orders.

Delivery

Delivery details. Used by our conditions engine.

date	date|null	Date format: yyyy-mm-dd
time	time|null	Time format: hh:mm
type	string	shipping,delivery,pickup

Products

An array of product details.

title	string|null
sku	string|null
quantity !	integer
price	float
length	float
width	float
height	float
weight	float
length_unit	string	mm,cm,m,in
weight_unit	string	g,kg,lb,oz
vendor	string|null
requires_shipping	boolean
fulfillment_service	string|null
properties	array	Array of key:pair values.
tags	array
product_id !	integer	Platform product guid.
variant_id !	integer	Platform product variant guid.

Additional parameters

Additional request details.

currency !	string	ISO-3 digit currency code.
locale	string|null	Not currently supported.
source	string	checkout,draft_order

Response

Example response

HTTP/1.1 200 OK
{
  "services": [{
    "title": "Regular Parcel",
    "code": "REGULAR_PARCEL",
    "description": "This is the fastest option by far",
    "carrier": "canada_post",
    "shipping_id": 483,
    "cost": 12.95,
    "currency": "USD",
    "min_delivery_days": 5,
    "max_delivery_days": 7,
    "packages": [{
      "id": 345,
      "title": "Small box",
      "code": "custom",
      "type": "box",
      "length": 24.00,
      "width": 12.00,
      "height": 12.00,
      "weight": 1000,
      "length_unit": "cm",
      "weight_unit": "g",
      "contents": [{
        "title": "Short Sleeve T-Shirt",
        "quantity": 1,
        "product_id": 48447225880,
        "variant_id": 258644705304
      }]
    }]
  }],
    "errors": [{
    "code": "authentication",
    "message": "An error ocurred."
  }]
}

Response Parameters

Services

An array of service details.

title	string|null
code	string|null
description	string|null
carrier	string|null	Internal carrier guid.
shipping_id	integer	Internal shipping method guid.
cost	float
currency	string	ISO-3 digit currency code.
min_delivery_days	integer|null
max_delivery_days	integer|null
packages	array	A list of packages.

Packages

An array of packages used to calculate the shipping cost.

id	integer	Internal package guid.
title	string|null
code	string	custom
type	string	box,softpack
length	float
width	float
height	float
weight	float
length_unit	string	mm,cm,m,in
weight_unit	string	g,kg,lb,oz
contents	array	A list of package contents.

Package Contents

An array of products that were packed into this package.

title	string|null
quantity	integer
product_id	integer	Platform product guid.
variant_id	integer	Platform product variant guid.

Errors

An array of error messages associated with the request.

code	string|null	Error code
message	string|null	Error message

Changelog

2025-04-15
Replaced /rating endpoint with /rates.

2023-09-01
Changed origin and destination payload key address_type to type.

2023-01-01
Removed Intuitive-Account-Id from the HTTP request header.

2020-07-21
Updated the HTTP request and response headers.