Partner API

The partner API is only available to approved partners.

Interested in joining our partner program? Please go here and fill out the ‘Care to connect’ form at the bottom of the page.

The partner API allows third-party applications to call Intuitive Shipping directly.

Request Headers

The request headers are used to authenticate the incoming request.

curl -X POST \ https://intuitiveshipping.io/ \
  -H 'Content-Type: application/json; charset=UTF-8' \
  -H 'Intuitive-Partner-Api-Key: 225fd46f-2eb0-4b6d-bd27-a57c6b04b8a8'\
  -H 'Intuitive-Account-Api-Key: 387d195e-9359-4518-a52c-831a8e6186de' \

Header Parameters

Intuitive-Partner-Api-Key	guid	Your partner API key. This will be provided upon approval as an Intuitive Shipping partner.
Intuitive-Account-Api-Key	guid	The account API key is located on the Partners page within the Intuitive Shipping console.

Optional Header Parameters

Intuitive-Test-Status

bool

Set to true to not generate an activity record within the Intuitive Shipping console.

Response Headers

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Intuitive-Api-Call-Limit: 40
Intuitive-Api-Call-Leak-Rate: 1
Intuitive-Request-Id: 3d545cbb-413e-4b49-9071-a09c03844040

Response Header Parameters

Intuitive-Api-Call-Limit	int	Leaky-bucket capacity.
Intuitive-Api-Call-Leak-Rate	int	Leaky-bucket leak rate per second.
Intuitive-Request-Id	guid	Matches the activity record generated in Intuitive Shipping.

Rating

Retrieves a list of shipping services with costs.

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 /rating
{
  "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 /rating
{
  "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 Responses for Invalid Requests

Below are examples of responses generated by invalid requests.

400 Invalid Request

This response type will return for invalid request methods. The rating endpoint only accepts a POST method.

HTTP/1.1 400 Invalid request
{
  "error": {
    "code": "invalid.request.method",
    "message": "Invalid request method. This resource only accepts POST."
  }
}

401 Unauthorized Access

This response type will return due to an invalid partner key or API key.

HTTP/1.1 401 Unauthorized Access
{
  "error": {
    "code": "unauthorized.access",
    "message": "Unauthorized access."
  }
}

429 Too Many Requests

This response type will return when the maximum capacity of the leaky-bucket has been exceeded. If you require an increase in your bucket capacity, please contact us.

HTTP/1.1 429 Too Many Requests
{
  "error": {
    "code": "rate.limit",
    "message": "Too many requests."
  }
}

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

Support

If you have any questions, please contact us for assistance.

Changelog

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.