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-KeyguidYour partner API key. This will be provided upon approval as an Intuitive Shipping partner.
Intuitive-Account-Api-KeyguidThe account API key is located on the Partners page within the Intuitive Shipping console.

Optional Header Parameters

Intuitive-Test-StatusboolSet 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-LimitintLeaky-bucket capacity.
Intuitive-Api-Call-Leak-RateintLeaky-bucket leak rate per second.
Intuitive-Request-IdguidMatches 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 !stringISO-2 digit country code.
province !stringISO-2 digit province/state code.
postal_code !string
citystring|null
address1string|null
address2string|null
typestringresidential,commercial,unknown
company_namestring|null
Destination

The shipment destination where the products will be shipped to.

country !stringISO-2 digit country code.
province !stringISO-2 digit province/state code.
postal_code !string
citystring|null
address1string|null
address2string|null
typestringresidential,commercial,unknown
company_namestring|null
Customer

Customer details. Used by our conditions engine.

namestring|nullConcat customer name.
tagsarray
telephonestring|null
faxstring|null
emailstring|null
lifetime_order_countintegerCount of previous orders.
lifetime_order_valuefloatTotal value of previous orders.
Delivery

Delivery details. Used by our conditions engine.

datedate|nullDate format: yyyy-mm-dd
timetime|nullTime format: hh:mm
typestringshipping,delivery,pickup
Products

An array of product details.

titlestring|null
skustring|null
quantity !integer
pricefloat
lengthfloat
widthfloat
heightfloat
weightfloat
length_unitstringmm,cm,m,in
weight_unitstringg,kg,lb,oz
vendorstring|null
requires_shippingboolean
fulfillment_servicestring|null
propertiesarrayArray of key:pair values.
tagsarray
product_id !integerPlatform product guid.
variant_id !integerPlatform product variant guid.
Additional parameters

Additional request details.

currency !stringISO-3 digit currency code.
localestring|nullNot currently supported.
sourcestringcheckout,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.

titlestring|null
codestring|null
descriptionstring|null
carrierstring|nullInternal carrier guid.
shipping_idintegerInternal shipping method guid.
costfloat
currencystringISO-3 digit currency code.
min_delivery_daysinteger|null
max_delivery_daysinteger|null
packagesarrayA list of packages.
Packages

An array of packages used to calculate the shipping cost.

idintegerInternal package guid.
titlestring|null
codestringcustom
typestringbox,softpack
lengthfloat
widthfloat
heightfloat
weightfloat
length_unitstringmm,cm,m,in
weight_unitstringg,kg,lb,oz
contentsarrayA list of package contents.
Package Contents

An array of products that were packed into this package.

titlestring|null
quantityinteger
product_idintegerPlatform product guid.
variant_idintegerPlatform product variant guid.
Errors

An array of error messages associated with the request.

codestring|nullError code
messagestring|nullError 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.
Updated on January 24, 2024

Was this article helpful?

Related Articles

Need Support?
Can't find the answer you're looking for?
Contact Support