Skip to content
English
Contact us
  • There are no suggestions because the search field is empty.

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.