API

The JSON API that will allow you to get your rates...everywhere.

Getting Started

Need Help? We're here.

If you have any questions at any step of the integration process, let us know, we're here to help! Send us an email at developers@flagshipcompany.com

Authentication

You will need to create a TOKEN from the SmartShip Authentication Gateway. Your regular FlagShip credentials can be used on this page to generate an app-specific TOKEN.

NOTE:

The Token is one way encrypted. If you lose it, there is no way to get it back - you'll need to get a new one.

The API is stateless and requires authentication for every request.

HTTPS only

HTTPS is required to connect to the API and furthermore it is rate-limited to 1 request per second, with bursts of 5 allowed. Exceeding this limit will return a 429 - Too many requests error.

How to create a request

Once you have generated a new token, you need to create a special header for the API to accept the request.

x-smartship-token should contain the TOKEN value obtained when generating the token.

To submit a valid request, your headers should look like this: 

GET /test/ HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCVM0pCgB7QB5cp-DlnIo3TA77xZE_yqWqwnia1pGc
Content-Type: application/json
The Token header must be present for all requests.

FlagShip REST PHP Client Library

One quick way to integrate FlagShip API into your PHP App.
To get started with FlagShip API SDK: learn more.

NOTE:

This library is fully compatible to all entry-points specified in this document.

Responses

The response HTTP codes are important. They follow the REST principles, notably:

  • 200 OK
  • 201 Created - The request created the ressource on our server.
  • 204 No Content - Means the query executed successfuly but we have no content in the body.
  • 206 Partial Content - Used for partial quotes, e.g: UPS failed but we have an answer for Purolator and FedEx.
  • 400 Bad Request - This means there is a problem with the request you submitted. Usually the explaination is in the body.
  • 401 Unauthorized - There is a problem with the identification.
  • 403 Forbidden - Means you are identified properly but have no access to the ressource.
  • 409 Conflict - Means you cannot do this operation at this time for this request.
  • 412 Precondition Failed - Means that while the request is valid, your account lacks sufficient funds to proceed with this shipment.
  • 500 Internal Server Error - Means FlagShip API crashed. A error message should accompany this code.
  • 502 Bad Gateway - Means one of our partners' API returned an error response.
  • 503 Service Unavailable - Means we temporarily down for maintenance.

Errors

For 4xx and 5xx you will receive different errors type. In case of a 400 the error will show where the problem occurs, e.g : 

{
    "content": null,
    "errors": {
        "from": {
            "country": ["This value is not valid."]
        }
    },
    "notices": null
}
In this case for example, the "country" field in the "from" section of your request has an error.

In the case of a courier errors (502) it will show which courier, with an array of all the errors returned by the courier.: 
{
    "content": null,
    "errors": {
        "ups": ["The maximum per package weight for the selected service from the selected country is 150.00 pounds."],
        "fedex": ["There are no valid services available. "],
        "purolator": ["The weight of an individual piece cannot exceed 150 lb"]
    },
    "notices": null
}

NOTE:

In the examples both in requests and responses, arrays are truncated with the following: 

"..."
These are to keep the documentation succinct and are of course not part of them.

Shipping

This resource allows to shop rates, confirm, list and cancel shipments

Create a Quote

This will allow to get rates for packages, courier packs or courier letters going from Canada to anywhere in the world.

Action

[POST] /ship/rates

Request

POST /ship/rates HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "from": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "123",
        "department": "Reception",
        "is_commercial": true
    },
    "to": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "123",
        "department": "Reception",
        "is_commercial": true
    },
    "packages": {
        "items": [
            {
                "width": 22,
                "height": 22,
                "length": 22,
                "weight": 22,
                "description": "Item description"
            },
            "..."
        ],
        "units": "imperial",
        "type": "package",
        "content": "goods"
    },
    "payment": {
        "payer": "F"
    },
    "options": {
        "insurance": {
            "value": 123.45,
            "description": "Children books"
        },
        "cod": {
            "method": "check",
            "payable_to": "Bob",
            "receiver_phone": "18663208383",
            "amount": 123.45,
            "currency": "CAD"
        },
        "signature_required": false,
        "saturday_delivery": false,
        "shipping_date": "2015-12-11",
        "reference": "123 test",
        "driver_instructions": "Doorbell broken, knock on door",
        "address_correction": false,
        "return_documents_as": "url",
        "shipment_tracking_emails": "jbeans@company.com;shipping1@company.com"
    }
}

Details

Name Example Value
from (Address)
Where the shipment is originating from
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
a valid canadian province 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
to (Address)
Where the shipment is going
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
packages (Packages)
What are you shipping?
Name Example Value
items (array)
Array of all the packages for that shipment
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
type (string)
package for your own boxes, letter for a courier letter or pack for the 3lbs courier pack. 		package
content (string)
Default value: goods - If the type is letter, then document can be specified if only documents with no commercial value are being shipped 		goods
payment (enum-objects)
Who is paying for this shipment?
Flagship Payment
Name Example Value
payer (string)
F - your Flagship Account, the most likely. 		F
Collect Payment
Name Example Value
payer (string)
C - Collect; the shipment will be billed on the receiver's account. 		C
payer_account (string)
The account of the payer with the selected courier. 		123456
Third Party Payment
Name Example Value
payer (string)
T - A Third Party will be charged for the shipment. 		T
payer_account (string)
The account of the payer with the selected courier. 		123456
payer_tp_address (Address)
The address of the third party payer
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
options (Options)
The options for this shipment. None of the options are required.
Name Example Value
insurance (Insurance Option)
Would you like to add insurance for the shipment? Not set by default
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
description (integer)
What is to be insured? 		Children books
cod (COD Option)
Cash on delivery. Request an amount to be paid for the driver to release the package.
Name Example Value
method (enum)
How to pay the requested amount 		check|cert_check|money_order
payable_to (string)
To who the payment must be addressed to 		Bob
receiver_phone (string)
Phone of the person that will receive payment 		18663208383
amount (decimal)
The amount requested to be paid on delivery 		123.45
currency (enum)
Currency of the amount 		CAD|USD
signature_required (boolean)
Is the signatured required upon delivery? false by default
It will be forced to true if shipment is insured and it is going to a residential address 		false
saturday_delivery (boolean)
Is the saturday delivery requested? false by default. Note that couriers only offer Saturday delivery for shipments with selected services shipping on selected weekdays and going to selected destinations. 		false
shipping_date (date)
When should the shipment be sent? today is the date by default. 		2015-12-11
reference (string)
Your reference for that shipment. Max: 30 chars 		123 test
driver_instructions (string)
Prints instructions on the label for the driver to see. Max: 30 chars 		Doorbell broken, knock on door
address_correction (boolean)
Should Flagship attempt to correct the receiver's address? false by default 		false
return_documents_as (enum)
How you want the labels to be returned. url or base64. Defaults to url 		url|base64
shipment_tracking_emails (string)
Semicolon-separated list of email addresses that will receive shipment tracking emails 		jbeans@company.com;shipping1@company.com

Response

200 OK 

{
    "content": [
        {
            "price": {
                "charges": {
                    "freight": 123.45,
                    "signature_required": 123.45,
                    "insurance": 123.45,
                    "multipiece": 123.45
                },
                "adjustments": null,
                "subtotal": 123.45,
                "total": 123.45,
                "taxes": {
                    "gst": 123.45,
                    "qst": 123.45,
                    "pst": 123.45,
                    "hst": 123.45
                }
            },
            "service": {
                "flagship_code": "expressEarlyAm",
                "courier_code": "FIRST_OVERNIGHT",
                "courier_desc": "First Overnight",
                "courier_name": "FedEx",
                "transit_time": 1,
                "estimated_delivery_date": "2015-12-03 23:30:00"
            }
        },
        "..."
    ],
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (array)
Name Example Value
price (Price Structure)
Price breakdown of the service
Name Example Value
charges (Shipment Charges)
List of charges relating to the shipment
Name Example Value
freight (decimal)
The freight cost 		123.45
signature_required (decimal)
Cost for a required signature 		123.45
insurance (decimal)
Cost of the insurance for the shipment 		123.45
multipiece (decimal)
Cost of too many boxes for the shipment 		123.45
adjustments (null)
Adjustments charged in addition to the original charges by the courier
subtotal (decimal)
Total before taxes 		123.45
total (decimal)
Total after taxes 		123.45
taxes (Shipment Taxes)
Breakdown of taxes on the shipment
Name Example Value
gst (decimal)
123.45
qst (decimal)
123.45
pst (decimal)
123.45
hst (decimal)
123.45
service (Service)
The type of Courier service available
Name Example Value
flagship_code (string)
The internal flagship code for that courier's service 		expressEarlyAm
courier_code (string)
The internal courier code for that service. You will need it to confirm the shipment 		FIRST_OVERNIGHT
courier_desc (string)
The nice name of the service 		First Overnight
courier_name (string)
Name of the courier 		FedEx
transit_time (integer)
The time in transit the shipment will take, in business days. Can be null if not provided by the courier, but it will be present in the response. 		1
estimated_delivery_date (string)
Local date time of when the shipment will be delivered by. Usually is present if transit_time is null. Can be also null 		2015-12-03 23:30:00
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Domestic Confirmation

Confirmation request that is domestic.

Action

[POST] /ship/confirm

Request

POST /ship/confirm HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "from": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "123",
        "department": "Reception",
        "is_commercial": true
    },
    "to": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "123",
        "department": "Reception",
        "is_commercial": true
    },
    "packages": {
        "items": [
            {
                "width": 22,
                "height": 22,
                "length": 22,
                "weight": 22,
                "description": "Item description"
            },
            "..."
        ],
        "units": "imperial",
        "type": "package",
        "content": "goods"
    },
    "payment": {
        "payer": "F"
    },
    "service": {
        "courier_name": "fedex",
        "courier_code": "FIRST_OVERNIGHT"
    },
    "options": {
        "insurance": {
            "value": 123.45,
            "description": "Children books"
        },
        "cod": {
            "method": "check",
            "payable_to": "Bob",
            "receiver_phone": "18663208383",
            "amount": 123.45,
            "currency": "CAD"
        },
        "signature_required": false,
        "saturday_delivery": false,
        "shipping_date": "2015-12-11",
        "reference": "123 test",
        "driver_instructions": "Doorbell broken, knock on door",
        "address_correction": false,
        "return_documents_as": "url",
        "shipment_tracking_emails": "jbeans@company.com;shipping1@company.com"
    }
}

Details

Name Example Value
from (Address)
Where the shipment is originating from
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
a valid canadian province 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
to (Address)
Where the shipment is going
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
packages (Packages)
What are you shipping?
Name Example Value
items (array)
Array of all the packages for that shipment
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
type (string)
package for your own boxes, letter for a courier letter or pack for the 3lbs courier pack. 		package
content (string)
Default value: goods - If the type is letter, then document can be specified if only documents with no commercial value are being shipped 		goods
payment (enum-objects)
Who is paying for this shipment?
Flagship Payment
Name Example Value
payer (string)
F - your Flagship Account, the most likely. 		F
Collect Payment
Name Example Value
payer (string)
C - Collect; the shipment will be billed on the receiver's account. 		C
payer_account (string)
The account of the payer with the selected courier. 		123456
Third Party Payment
Name Example Value
payer (string)
T - A Third Party will be charged for the shipment. 		T
payer_account (string)
The account of the payer with the selected courier. 		123456
payer_tp_address (Address)
The address of the third party payer
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
service (Service)
What courier and courier service are we using?
Name Example Value
courier_name (string)
The courier requested for the dispatch 		fedex
courier_code (string)
The requested service for the dispatch. 		FIRST_OVERNIGHT
options (Options)
The options for this shipment. None of the options are required.
Name Example Value
insurance (Insurance Option)
Would you like to add insurance for the shipment? Not set by default
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
description (integer)
What is to be insured? 		Children books
cod (COD Option)
Cash on delivery. Request an amount to be paid for the driver to release the package.
Name Example Value
method (enum)
How to pay the requested amount 		check|cert_check|money_order
payable_to (string)
To who the payment must be addressed to 		Bob
receiver_phone (string)
Phone of the person that will receive payment 		18663208383
amount (decimal)
The amount requested to be paid on delivery 		123.45
currency (enum)
Currency of the amount 		CAD|USD
signature_required (boolean)
Is the signatured required upon delivery? false by default
It will be forced to true if shipment is insured and it is going to a residential address 		false
saturday_delivery (boolean)
Is the saturday delivery requested? false by default. Note that couriers only offer Saturday delivery for shipments with selected services shipping on selected weekdays and going to selected destinations. 		false
shipping_date (date)
When should the shipment be sent? today is the date by default. 		2015-12-11
reference (string)
Your reference for that shipment. Max: 30 chars 		123 test
driver_instructions (string)
Prints instructions on the label for the driver to see. Max: 30 chars 		Doorbell broken, knock on door
address_correction (boolean)
Should Flagship attempt to correct the receiver's address? false by default 		false
return_documents_as (enum)
How you want the labels to be returned. url or base64. Defaults to url 		url|base64
shipment_tracking_emails (string)
Semicolon-separated list of email addresses that will receive shipment tracking emails 		jbeans@company.com;shipping1@company.com

Response

201 CREATED 

{
    "content": {
        "shipment_id": "201012221",
        "tracking_number": "329018797020",
        "price": {
            "charges": {
                "freight": 123.45,
                "signature_required": 123.45,
                "insurance": 123.45,
                "multipiece": 123.45
            },
            "adjustments": null,
            "subtotal": 123.45,
            "total": 123.45,
            "taxes": {
                "gst": 123.45,
                "qst": 123.45,
                "pst": 123.45,
                "hst": 123.45
            }
        },
        "service": {
            "flagship_code": "expressEarlyAm",
            "courier_code": "FIRST_OVERNIGHT",
            "courier_desc": "First Overnight",
            "courier_name": "FedEx",
            "transit_time": 1,
            "estimated_delivery_date": "2015-12-03 23:30:00"
        },
        "labels": {
            "regular": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=reg",
            "thermal": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=therm"
        },
        "packages": [
            {
                "width": 22,
                "height": 22,
                "length": 22,
                "weight": 22,
                "description": "Item description",
                "pin": "72909513411"
            },
            "..."
        ]
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Shipment)
Name Example Value
shipment_id (number)
The shipment id as it appears in the Flagship API 		201012221
tracking_number (string)
The tracking number associated with your shipment. This is a courier generated value 		329018797020
price (Price Structure)
A price breakdown for the requested service
Name Example Value
charges (Shipment Charges)
List of charges relating to the shipment
Name Example Value
freight (decimal)
The freight cost 		123.45
signature_required (decimal)
Cost for a required signature 		123.45
insurance (decimal)
Cost of the insurance for the shipment 		123.45
multipiece (decimal)
Cost of too many boxes for the shipment 		123.45
adjustments (null)
Adjustments charged in addition to the original charges by the courier
subtotal (decimal)
Total before taxes 		123.45
total (decimal)
Total after taxes 		123.45
taxes (Shipment Taxes)
Breakdown of taxes on the shipment
Name Example Value
gst (decimal)
123.45
qst (decimal)
123.45
pst (decimal)
123.45
hst (decimal)
123.45
service (Service)
Details about the service selected
Name Example Value
flagship_code (string)
The internal flagship code for that courier's service 		expressEarlyAm
courier_code (string)
The internal courier code for that service. You will need it to confirm the shipment 		FIRST_OVERNIGHT
courier_desc (string)
The nice name of the service 		First Overnight
courier_name (string)
Name of the courier 		FedEx
transit_time (integer)
The time in transit the shipment will take, in business days. Can be null if not provided by the courier, but it will be present in the response. 		1
estimated_delivery_date (string)
Local date time of when the shipment will be delivered by. Usually is present if transit_time is null. Can be also null 		2015-12-03 23:30:00
labels (Labels)
The shipping labels provided from the courier
Name Example Value
regular (url)
The URL for the regular sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=reg
thermal (url)
The URL for the thermal sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=therm
packages (array)
List of the packages in the shipment, along with the courier-assigned PIN numbers
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
pin (string)
The pin associated to the package. 		72909513411
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

International Confirmation

Confirmation request that is being sent internationally.

Action

[POST] /ship/confirm

Request

POST /ship/confirm HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "from": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "123",
        "department": "Reception",
        "is_commercial": true
    },
    "to": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "123",
        "department": "Reception",
        "is_commercial": true
    },
    "packages": {
        "items": [
            {
                "width": 22,
                "height": 22,
                "length": 22,
                "weight": 22,
                "description": "Item description"
            },
            "..."
        ],
        "units": "imperial",
        "type": "package",
        "content": "goods"
    },
    "payment": {
        "payer": "F"
    },
    "service": {
        "courier_name": "fedex",
        "courier_code": "FIRST_OVERNIGHT"
    },
    "options": {
        "insurance": {
            "value": 123.45,
            "description": "Children books"
        },
        "cod": {
            "method": "check",
            "payable_to": "Bob",
            "receiver_phone": "18663208383",
            "amount": 123.45,
            "currency": "CAD"
        },
        "signature_required": false,
        "saturday_delivery": false,
        "shipping_date": "2015-12-11",
        "reference": "123 test",
        "driver_instructions": "Doorbell broken, knock on door",
        "address_correction": false,
        "return_documents_as": "url",
        "shipment_tracking_emails": "jbeans@company.com;shipping1@company.com"
    },
    "sold_to": {
        "sold_to_address": {
            "name": "ACME inc.",
            "attn": "Bob",
            "address": "123 Main Street",
            "suite": "227",
            "city": "Montreal",
            "country": "CA",
            "state": "QC",
            "postal_code": "A1A1A1",
            "phone": "18663208383",
            "ext": "123",
            "department": "Reception",
            "is_commercial": true
        },
        "duties_payer": "F",
        "duties_payer_account": "1231234",
        "reason_for_export": "P",
        "is_nafta": true
    },
    "inquiry": {
        "company": "ACME inc.",
        "name": "Bob",
        "broker_id": "1",
        "sender_tax_id": "",
        "receiver_tax_id": "",
        "inquiry_phone": "18663208383",
        "inquiry_phone_ext": ""
    },
    "declared_items": {
        "currency": "CAD",
        "ci_items": [
            {
                "product_name": "Cologne",
                "description": "1 bottle of Cologne",
                "HS_code": "",
                "country_of_origin": "CA",
                "quantity": "2",
                "unit_price": "20",
                "unit_weight": "22.50",
                "unit_of_measurement": "kilograms"
            },
            "..."
        ]
    }
}

Details

Name Example Value
from (Address)
Where the shipment is originating from
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
a valid canadian province 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
to (Address)
Where the shipment is going
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
Can go anywhere except Iran, Syria and North Korea 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
packages (Packages)
What are you shipping?
Name Example Value
items (array)
Array of all the packages for that shipment
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
type (string)
package for your own boxes, letter for a courier letter or pack for the 3lbs courier pack. 		package
content (string)
Default value: goods - If the type is letter, then document can be specified if only documents with no commercial value are being shipped 		goods
payment (enum-objects)
Who is paying for this shipment?
Flagship Payment
Name Example Value
payer (string)
F - your Flagship Account, the most likely. 		F
Collect Payment
Name Example Value
payer (string)
C - Collect; the shipment will be billed on the receiver's account. 		C
payer_account (string)
The account of the payer with the selected courier. 		123456
Third Party Payment
Name Example Value
payer (string)
T - A Third Party will be charged for the shipment. 		T
payer_account (string)
The account of the payer with the selected courier. 		123456
payer_tp_address (Address)
The address of the third party payer
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
service (Service)
What courier and courier service are we using?
Name Example Value
courier_name (string)
The courier requested for the dispatch 		fedex
courier_code (string)
The requested service for the dispatch. 		FIRST_OVERNIGHT
options (Options)
The options for this shipment. None of the options are required.
Name Example Value
insurance (Insurance Option)
Would you like to add insurance for the shipment? Not set by default
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
description (integer)
What is to be insured? 		Children books
cod (COD Option)
Cash on delivery. Request an amount to be paid for the driver to release the package.
Name Example Value
method (enum)
How to pay the requested amount 		check|cert_check|money_order
payable_to (string)
To who the payment must be addressed to 		Bob
receiver_phone (string)
Phone of the person that will receive payment 		18663208383
amount (decimal)
The amount requested to be paid on delivery 		123.45
currency (enum)
Currency of the amount 		CAD|USD
signature_required (boolean)
Is the signatured required upon delivery? false by default
It will be forced to true if shipment is insured and it is going to a residential address 		false
saturday_delivery (boolean)
Is the saturday delivery requested? false by default. Note that couriers only offer Saturday delivery for shipments with selected services shipping on selected weekdays and going to selected destinations. 		false
shipping_date (date)
When should the shipment be sent? today is the date by default. 		2015-12-11
reference (string)
Your reference for that shipment. Max: 30 chars 		123 test
driver_instructions (string)
Prints instructions on the label for the driver to see. Max: 30 chars 		Doorbell broken, knock on door
address_correction (boolean)
Should Flagship attempt to correct the receiver's address? false by default 		false
return_documents_as (enum)
How you want the labels to be returned. url or base64. Defaults to url 		url|base64
shipment_tracking_emails (string)
Semicolon-separated list of email addresses that will receive shipment tracking emails 		jbeans@company.com;shipping1@company.com
sold_to (Sold To)
Information about buyer.
Name Example Value
sold_to_address (Address)
Buyer's contact information
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
duties_payer (enum)
Who is paying duties: F (Flagship Account), C (Collect) or T (Third Party) 		F|C|T
duties_payer_account (string)
The duties payer account number. Only applicable if the duties_payer field is set to T 		1231234
reason_for_export (enum)
Reason for export: P (Permanent), T (Temporary), R (Return), G (Gift), S (Sample) 		P|T|R|G|S
is_nafta (boolean)
Whether the shipped goods are NAFTA compliant 		1
inquiry (Inquiry)
Inquiry contact and broker information
Name Example Value
company (string)
ACME inc.
name (string)
Bob
broker_id (number)
Broker ID as assigned by the Flagship API. Refer to the list of brokers that are available 		1
sender_tax_id (string)
The tax ID/business number for your business
receiver_tax_id (string)
The tax ID/business number of the receiver
inquiry_phone (number)
18663208383
inquiry_phone_ext (number)
declared_items (Declared Items)
Details about package contents
Name Example Value
currency (enum)
The currency at which items were valued at 		CAD|USD
ci_items (array)
Detailed description of package contents
Name Example Value
product_name (string)
Cologne
description (string)
1 bottle of Cologne
HS_code (string)
The HS code associated with the product. You can find a list of HS codes or search for them here
country_of_origin (string)
ISO 3166-1 alpha-2 two letter country code 		CA
quantity (number)
The number of said product contained in the shipment 		2
unit_price (float)
The unit value of the product 		20
unit_weight (float)
The unit weight of the product 		22.50
unit_of_measurement (string)
The unit of measurement used for the weight of the product 		kilograms

Response

201 CREATED 

{
    "content": {
        "shipment_id": "201012221",
        "tracking_number": "329018797020",
        "price": {
            "charges": {
                "freight": 123.45,
                "signature_required": 123.45,
                "insurance": 123.45,
                "multipiece": 123.45
            },
            "adjustments": null,
            "subtotal": 123.45,
            "total": 123.45,
            "taxes": {
                "gst": 123.45,
                "qst": 123.45,
                "pst": 123.45,
                "hst": 123.45
            }
        },
        "service": {
            "flagship_code": "expressEarlyAm",
            "courier_code": "FIRST_OVERNIGHT",
            "courier_desc": "First Overnight",
            "courier_name": "FedEx",
            "transit_time": 1,
            "estimated_delivery_date": "2015-12-03 23:30:00"
        },
        "labels": {
            "regular": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=reg",
            "thermal": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=therm"
        },
        "packages": [
            {
                "width": 22,
                "height": 22,
                "length": 22,
                "weight": 22,
                "description": "Item description",
                "pin": "72909513411"
            },
            "..."
        ],
        "documents_only": false,
        "commercial_invoice": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=statement",
        "nafta_form_url": "https:\/\/www.cbp.gov\/sites\/default\/files\/documents\/CBP%20Form%20434_3.pdf"
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Shipment)
Name Example Value
shipment_id (number)
The shipment id as it appears in the Flagship API 		201012221
tracking_number (string)
The tracking number associated with your shipment. This is a courier generated value 		329018797020
price (Price Structure)
A price breakdown for the requested service
Name Example Value
charges (Shipment Charges)
List of charges relating to the shipment
Name Example Value
freight (decimal)
The freight cost 		123.45
signature_required (decimal)
Cost for a required signature 		123.45
insurance (decimal)
Cost of the insurance for the shipment 		123.45
multipiece (decimal)
Cost of too many boxes for the shipment 		123.45
adjustments (null)
Adjustments charged in addition to the original charges by the courier
subtotal (decimal)
Total before taxes 		123.45
total (decimal)
Total after taxes 		123.45
taxes (Shipment Taxes)
Breakdown of taxes on the shipment
Name Example Value
gst (decimal)
123.45
qst (decimal)
123.45
pst (decimal)
123.45
hst (decimal)
123.45
service (Service)
Details about the service selected
Name Example Value
flagship_code (string)
The internal flagship code for that courier's service 		expressEarlyAm
courier_code (string)
The internal courier code for that service. You will need it to confirm the shipment 		FIRST_OVERNIGHT
courier_desc (string)
The nice name of the service 		First Overnight
courier_name (string)
Name of the courier 		FedEx
transit_time (integer)
The time in transit the shipment will take, in business days. Can be null if not provided by the courier, but it will be present in the response. 		1
estimated_delivery_date (string)
Local date time of when the shipment will be delivered by. Usually is present if transit_time is null. Can be also null 		2015-12-03 23:30:00
labels (Labels)
The shipping labels provided from the courier
Name Example Value
regular (url)
The URL for the regular sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=reg
thermal (url)
The URL for the thermal sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=therm
packages (array)
List of the packages in the shipment, along with the courier-assigned PIN numbers
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
pin (string)
The pin associated to the package. 		72909513411
documents_only (boolean)
Is this shipment containing documents only? 		false
commercial_invoice (url)
URL for the Flagship generated commercial invoice required for an international shipment 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=statement
nafta_form_url (url)
URL for NAFTA form (Only appears when the field is_nafta of sold_to in the request is true) 		https://www.cbp.gov/sites/default/files/documents/CBP%20Form%20434_3.pdf
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Create Record

Creates a record for the shipment in the database, in a "prequoted" status. Can subsequently be used to be confirmed with "Confirm By id" function.

Action

[POST] ship/prepare

Request

POST ship/prepare HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "from": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "123",
        "department": "Reception",
        "is_commercial": true
    },
    "to": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "123",
        "department": "Reception",
        "is_commercial": true
    },
    "packages": {
        "items": [
            {
                "width": 22,
                "height": 22,
                "length": 22,
                "weight": 22,
                "description": "Item description"
            },
            "..."
        ],
        "units": "imperial",
        "type": "package",
        "content": "goods"
    },
    "payment": {
        "payer": "F"
    },
    "options": {
        "insurance": {
            "value": 123.45,
            "description": "Children books"
        },
        "cod": {
            "method": "check",
            "payable_to": "Bob",
            "receiver_phone": "18663208383",
            "amount": 123.45,
            "currency": "CAD"
        },
        "signature_required": false,
        "saturday_delivery": false,
        "shipping_date": "2015-12-11",
        "reference": "123 test",
        "driver_instructions": "Doorbell broken, knock on door",
        "address_correction": false,
        "return_documents_as": "url",
        "shipment_tracking_emails": "jbeans@company.com;shipping1@company.com"
    }
}

Details

Name Example Value
from (Address)
Where the shipment is originating from
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
a valid canadian province 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
to (Address)
Where the shipment is going
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
packages (Packages)
What are you shipping?
Name Example Value
items (array)
Array of all the packages for that shipment
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
type (string)
package for your own boxes, letter for a courier letter or pack for the 3lbs courier pack. 		package
content (string)
Default value: goods - If the type is letter, then document can be specified if only documents with no commercial value are being shipped 		goods
payment (enum-objects)
Who is paying for this shipment?
Flagship Payment
Name Example Value
payer (string)
F - your Flagship Account, the most likely. 		F
Collect Payment
Name Example Value
payer (string)
C - Collect; the shipment will be billed on the receiver's account. 		C
payer_account (string)
The account of the payer with the selected courier. 		123456
Third Party Payment
Name Example Value
payer (string)
T - A Third Party will be charged for the shipment. 		T
payer_account (string)
The account of the payer with the selected courier. 		123456
payer_tp_address (Address)
The address of the third party payer
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
options (Options)
The options for this shipment. None of the options are required.
Name Example Value
insurance (Insurance Option)
Would you like to add insurance for the shipment? Not set by default
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
description (integer)
What is to be insured? 		Children books
cod (COD Option)
Cash on delivery. Request an amount to be paid for the driver to release the package.
Name Example Value
method (enum)
How to pay the requested amount 		check|cert_check|money_order
payable_to (string)
To who the payment must be addressed to 		Bob
receiver_phone (string)
Phone of the person that will receive payment 		18663208383
amount (decimal)
The amount requested to be paid on delivery 		123.45
currency (enum)
Currency of the amount 		CAD|USD
signature_required (boolean)
Is the signatured required upon delivery? false by default
It will be forced to true if shipment is insured and it is going to a residential address 		false
saturday_delivery (boolean)
Is the saturday delivery requested? false by default. Note that couriers only offer Saturday delivery for shipments with selected services shipping on selected weekdays and going to selected destinations. 		false
shipping_date (date)
When should the shipment be sent? today is the date by default. 		2015-12-11
reference (string)
Your reference for that shipment. Max: 30 chars 		123 test
driver_instructions (string)
Prints instructions on the label for the driver to see. Max: 30 chars 		Doorbell broken, knock on door
address_correction (boolean)
Should Flagship attempt to correct the receiver's address? false by default 		false
return_documents_as (enum)
How you want the labels to be returned. url or base64. Defaults to url 		url|base64
shipment_tracking_emails (string)
Semicolon-separated list of email addresses that will receive shipment tracking emails 		jbeans@company.com;shipping1@company.com

Response

200 OK 

{
    "content": {
        "id": 1122341,
        "tracking_number": "1P0075H07633636542",
        "pickup_id": 1122342,
        "status": "prequoted",
        "from": {
            "name": "ACME inc.",
            "attn": "Bob",
            "address": "123 Main Street",
            "suite": "227",
            "city": "Montreal",
            "country": "CA",
            "state": "QC",
            "postal_code": "A1A1A1",
            "phone": "18663208383",
            "ext": "123",
            "department": "Reception",
            "is_commercial": true
        },
        "to": {
            "name": "ACME inc.",
            "attn": "Bob",
            "address": "123 Main Street",
            "suite": "227",
            "city": "Montreal",
            "country": "CA",
            "state": "QC",
            "postal_code": "A1A1A1",
            "phone": "18663208383",
            "ext": "123",
            "department": "Reception",
            "is_commercial": true
        },
        "options": {
            "insurance": {
                "value": 123.45,
                "description": "Children books"
            },
            "cod": {
                "method": "check",
                "payable_to": "Bob",
                "receiver_phone": "18663208383",
                "amount": 123.45,
                "currency": "CAD"
            },
            "signature_required": false,
            "saturday_delivery": false,
            "shipping_date": "2015-12-11",
            "reference": "123 test",
            "driver_instructions": "Doorbell broken, knock on door",
            "address_correction": false,
            "return_documents_as": "url",
            "shipment_tracking_emails": "jbeans@company.com;shipping1@company.com"
        },
        "pickup_details": {
            "confirmation": "2929602E9CP",
            "address": {
                "name": "ACME inc.",
                "attn": "Bob",
                "address": "123 Main Street",
                "suite": "227",
                "city": "Montreal",
                "country": "CA",
                "state": "QC",
                "postal_code": "A1A1A1",
                "phone": "18663208383",
                "ext": "11",
                "is_commercial": false
            },
            "boxes": 4,
            "weight": 6,
            "units": "imperial",
            "date": "2015-12-31",
            "from": "09:00:00",
            "until": "17:00:00",
            "location": "Reception",
            "instruction": "contain glass product, etc.",
            "is_cancelled": false
        },
        "service": {
            "courier_name": "fedex",
            "courier_code": "FIRST_OVERNIGHT"
        },
        "packages": {
            "items": [
                {
                    "width": 22,
                    "height": 22,
                    "length": 22,
                    "weight": 22,
                    "description": "Item description"
                },
                "..."
            ],
            "units": "imperial",
            "type": "package",
            "content": "goods"
        },
        "price": {
            "charges": {
                "freight": 123.45,
                "signature_required": 123.45,
                "insurance": 123.45,
                "multipiece": 123.45
            },
            "adjustments": {
                "fuel_surchage": 123.45
            },
            "subtotal": 123.45,
            "total": 123.45,
            "taxes": {
                "gst": 123.45,
                "qst": 123.45,
                "pst": 123.45,
                "hst": 123.45
            }
        },
        "brokerage_details": {
            "description": "Chocolate covered gift box",
            "items": [
                {
                    "country_of_origin": "CA",
                    "description": "Sweet Biscuits",
                    "duty_value": 3074.67,
                    "class_number": "1905312900",
                    "duty": 0,
                    "excise_tax_rate": 0,
                    "excise_tax_amount": 0,
                    "gst_hst_rate": 0,
                    "gst_hst_amount": 0,
                    "tax_value": 0,
                    "sima_assess": 0,
                    "total_customs": 0
                },
                "..."
            ],
            "total_duty": 3074.67,
            "currency": "CAD",
            "billed_weight": 6,
            "weight_units": "imperial",
            "package_count": 4,
            "invoice_number": "1234567"
        },
        "documents": {
            "regular": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=reg",
            "thermal": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=therm"
        },
        "nafta_form_url": "https:\/\/www.cbp.gov\/sites\/default\/files\/documents\/CBP%20Form%20434_3.pdf",
        "transit_details": [
            {
                "last_update": "2017-06-09 23:00:00",
                "status": "D",
                "message": "Shipment delivered to YALE via GUELPH, ON depot"
            },
            "..."
        ]
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Shipment)
Name Example Value
id (integer)
The shipment id 		1122341
tracking_number (string)
The tracking number 		1P0075H07633636542
pickup_id (integer)
The pickup id is associated to the shipment 		1122342
status (enum)
The shipment status 		prequoted|quoted|predispatched|dispatched|manifested|cancelled
from (Address)
The from address
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
to (Address)
The to address
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
options (Options)
Name Example Value
insurance (Insurance Option)
Would you like to add insurance for the shipment? Not set by default
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
description (integer)
What is to be insured? 		Children books
cod (COD Option)
Cash on delivery. Request an amount to be paid for the driver to release the package.
Name Example Value
method (enum)
How to pay the requested amount 		check|cert_check|money_order
payable_to (string)
To who the payment must be addressed to 		Bob
receiver_phone (string)
Phone of the person that will receive payment 		18663208383
amount (decimal)
The amount requested to be paid on delivery 		123.45
currency (enum)
Currency of the amount 		CAD|USD
signature_required (boolean)
Is the signatured required upon delivery? false by default
It will be forced to true if shipment is insured and it is going to a residential address 		false
saturday_delivery (boolean)
Is the saturday delivery requested? false by default. Note that couriers only offer Saturday delivery for shipments with selected services shipping on selected weekdays and going to selected destinations. 		false
shipping_date (date)
When should the shipment be sent? today is the date by default. 		2015-12-11
reference (string)
Your reference for that shipment. Max: 30 chars 		123 test
driver_instructions (string)
Prints instructions on the label for the driver to see. Max: 30 chars 		Doorbell broken, knock on door
address_correction (boolean)
Should Flagship attempt to correct the receiver's address? false by default 		false
return_documents_as (enum)
How you want the labels to be returned. url or base64. Defaults to url 		url|base64
shipment_tracking_emails (string)
Semicolon-separated list of email addresses that will receive shipment tracking emails 		jbeans@company.com;shipping1@company.com
pickup_details (Pickup Details)
The Pickup information
Name Example Value
confirmation (string)
confirmation number 		2929602E9CP
address (address)
The pickup information for that shipment
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
telephone extension number 		11
is_commercial (boolean)
can be 0|1 		false
boxes (integer)
number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
units (string)
The shipment unit (imperia|metric) 		imperial
date (date)
can be YYYY-MM-DD 		2015-12-31
from (timestamp)
can be hour and minute in 24h format, hh:mm:ss 		09:00:00
until (timestamp)
can be hour and minute in 24h format, hh:mm:ss 		17:00:00
location (string)
Where the pick-up location is 		Reception
instruction (string)
special attention for delivery 		contain glass product, etc.
is_cancelled (boolean)
can be 0|1 		false
service (Service)
The service
Name Example Value
courier_name (string)
The courier requested for the dispatch 		fedex
courier_code (string)
The requested service for the dispatch. 		FIRST_OVERNIGHT
packages (Packages)
The packages contained in the shipment
Name Example Value
items (array)
Array of all the packages for that shipment
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
type (string)
package for your own boxes, letter for a courier letter or pack for the 3lbs courier pack. 		package
content (string)
Default value: goods - If the type is letter, then document can be specified if only documents with no commercial value are being shipped 		goods
price (Invoiced Price Structure)
The list of charges for the shipment
Name Example Value
charges (Shipment Charges)
List of charges relating to the shipment
Name Example Value
freight (decimal)
The freight cost 		123.45
signature_required (decimal)
Cost for a required signature 		123.45
insurance (decimal)
Cost of the insurance for the shipment 		123.45
multipiece (decimal)
Cost of too many boxes for the shipment 		123.45
adjustments (Shipment Adjustments)
Adjustments charged in addition to the original charges by the courier
Name Example Value
fuel_surchage (decimal)
Cost of fuel 		123.45
subtotal (decimal)
Total before taxes 		123.45
total (decimal)
Total after taxes 		123.45
taxes (Shipment Taxes)
Breakdown of taxes on the shipment
Name Example Value
gst (decimal)
123.45
qst (decimal)
123.45
pst (decimal)
123.45
hst (decimal)
123.45
brokerage_details (Brokerage Details)
Brokerage information
Name Example Value
description (string)
Item description 		Chocolate covered gift box
items (array)
Array of all the items for that shipment
Name Example Value
country_of_origin (string)
ISO 3166-1 alpha-2 two letter country code 		CA
description (string)
description of the item 		Sweet Biscuits
duty_value (decimal)
Duty value 		3074.67
class_number (string)
Class number 		1905312900
duty (decimal)
Duty amount 		0
excise_tax_rate (integer)
Excise tax rate 		0
excise_tax_amount (decimal)
Excise tax amount 		0
gst_hst_rate (integer)
GST HST rate 		0
gst_hst_amount (decimal)
GST HST amount 		0
tax_value (decimal)
Tax value 		0
sima_assess (integer)
Antidumping and countervailing duties are assessed against subject goods that originate in, or are exported from a specific country 		0
total_customs (decimal)
Total customs 		0
total_duty (decimal)
Total duty 		3074.67
currency (enum)
The currency at which items were valued at 		CAD|USD
billed_weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
weight_units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
package_count (integer)
Package counts 		4
invoice_number (string)
The invoice number 		1234567
documents (Labels)
The shipping labels provided by the courier and commercial invoice, if applicable
Name Example Value
regular (url)
The URL for the regular sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=reg
thermal (url)
The URL for the thermal sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=therm
nafta_form_url (url)
URL for NAFTA form (Only applicable to shipments destined to NAFTA countries with goods that for the reduced or eliminated duties allowed under NAFTA) 		https://www.cbp.gov/sites/default/files/documents/CBP%20Form%20434_3.pdf
transit_details (array)
The transit details for shipment
Name Example Value
last_update (string)
Courier update for shipment. 		2017-06-09 23:00:00
status (string)
The shipment status (M: Manifested, P: Picked up, T: In transit, D: Delivered, U: Unknown, X: Exception) 		D
message (string)
Status description for the shipment. 		Shipment delivered to YALE via GUELPH, ON depot
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Find by id

Get a shipment's details by id.

Action

[GET] /ship/shipments/{shipmentId}

Request

GET /ship/shipments/{shipmentId} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK 

{
    "content": {
        "id": 1122341,
        "tracking_number": "1P0075H07633636542",
        "pickup_id": 1122342,
        "status": "prequoted",
        "from": {
            "name": "ACME inc.",
            "attn": "Bob",
            "address": "123 Main Street",
            "suite": "227",
            "city": "Montreal",
            "country": "CA",
            "state": "QC",
            "postal_code": "A1A1A1",
            "phone": "18663208383",
            "ext": "123",
            "department": "Reception",
            "is_commercial": true
        },
        "to": {
            "name": "ACME inc.",
            "attn": "Bob",
            "address": "123 Main Street",
            "suite": "227",
            "city": "Montreal",
            "country": "CA",
            "state": "QC",
            "postal_code": "A1A1A1",
            "phone": "18663208383",
            "ext": "123",
            "department": "Reception",
            "is_commercial": true
        },
        "options": {
            "insurance": {
                "value": 123.45,
                "description": "Children books"
            },
            "cod": {
                "method": "check",
                "payable_to": "Bob",
                "receiver_phone": "18663208383",
                "amount": 123.45,
                "currency": "CAD"
            },
            "signature_required": false,
            "saturday_delivery": false,
            "shipping_date": "2015-12-11",
            "reference": "123 test",
            "driver_instructions": "Doorbell broken, knock on door",
            "address_correction": false,
            "return_documents_as": "url",
            "shipment_tracking_emails": "jbeans@company.com;shipping1@company.com"
        },
        "pickup_details": {
            "confirmation": "2929602E9CP",
            "address": {
                "name": "ACME inc.",
                "attn": "Bob",
                "address": "123 Main Street",
                "suite": "227",
                "city": "Montreal",
                "country": "CA",
                "state": "QC",
                "postal_code": "A1A1A1",
                "phone": "18663208383",
                "ext": "11",
                "is_commercial": false
            },
            "boxes": 4,
            "weight": 6,
            "units": "imperial",
            "date": "2015-12-31",
            "from": "09:00:00",
            "until": "17:00:00",
            "location": "Reception",
            "instruction": "contain glass product, etc.",
            "is_cancelled": false
        },
        "service": {
            "courier_name": "fedex",
            "courier_code": "FIRST_OVERNIGHT"
        },
        "packages": {
            "items": [
                {
                    "width": 22,
                    "height": 22,
                    "length": 22,
                    "weight": 22,
                    "description": "Item description"
                },
                "..."
            ],
            "units": "imperial",
            "type": "package",
            "content": "goods"
        },
        "price": {
            "charges": {
                "freight": 123.45,
                "signature_required": 123.45,
                "insurance": 123.45,
                "multipiece": 123.45
            },
            "adjustments": {
                "fuel_surchage": 123.45
            },
            "subtotal": 123.45,
            "total": 123.45,
            "taxes": {
                "gst": 123.45,
                "qst": 123.45,
                "pst": 123.45,
                "hst": 123.45
            }
        },
        "brokerage_details": {
            "description": "Chocolate covered gift box",
            "items": [
                {
                    "country_of_origin": "CA",
                    "description": "Sweet Biscuits",
                    "duty_value": 3074.67,
                    "class_number": "1905312900",
                    "duty": 0,
                    "excise_tax_rate": 0,
                    "excise_tax_amount": 0,
                    "gst_hst_rate": 0,
                    "gst_hst_amount": 0,
                    "tax_value": 0,
                    "sima_assess": 0,
                    "total_customs": 0
                },
                "..."
            ],
            "total_duty": 3074.67,
            "currency": "CAD",
            "billed_weight": 6,
            "weight_units": "imperial",
            "package_count": 4,
            "invoice_number": "1234567"
        },
        "documents": {
            "regular": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=reg",
            "thermal": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=therm"
        },
        "nafta_form_url": "https:\/\/www.cbp.gov\/sites\/default\/files\/documents\/CBP%20Form%20434_3.pdf",
        "transit_details": [
            {
                "last_update": "2017-06-09 23:00:00",
                "status": "D",
                "message": "Shipment delivered to YALE via GUELPH, ON depot"
            },
            "..."
        ],
        "invoice_details": {
            "201712-52": {
                "cycle_id": "201712-52",
                "invoice_id": "123",
                "originals": {
                    "freight": {
                        "reason": "special handling",
                        "amount": 123.45
                    },
                    "0": "..."
                },
                "adjustements": {
                    "freight": {
                        "reason": "special handling",
                        "amount": 123.45
                    },
                    "0": "..."
                },
                "credits": {
                    "freight": {
                        "reason": "special handling",
                        "amount": 123.45
                    },
                    "0": "..."
                },
                "payments": {
                    "freight": {
                        "reason": "special handling",
                        "amount": 123.45
                    },
                    "0": "..."
                }
            },
            "0": "..."
        }
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Shipment)
Name Example Value
id (integer)
The shipment id 		1122341
tracking_number (string)
The tracking number 		1P0075H07633636542
pickup_id (integer)
The pickup id is associated to the shipment 		1122342
status (enum)
The shipment status 		prequoted|quoted|predispatched|dispatched|manifested|cancelled
from (Address)
The from address
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
to (Address)
The to address
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
options (Options)
Name Example Value
insurance (Insurance Option)
Would you like to add insurance for the shipment? Not set by default
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
description (integer)
What is to be insured? 		Children books
cod (COD Option)
Cash on delivery. Request an amount to be paid for the driver to release the package.
Name Example Value
method (enum)
How to pay the requested amount 		check|cert_check|money_order
payable_to (string)
To who the payment must be addressed to 		Bob
receiver_phone (string)
Phone of the person that will receive payment 		18663208383
amount (decimal)
The amount requested to be paid on delivery 		123.45
currency (enum)
Currency of the amount 		CAD|USD
signature_required (boolean)
Is the signatured required upon delivery? false by default
It will be forced to true if shipment is insured and it is going to a residential address 		false
saturday_delivery (boolean)
Is the saturday delivery requested? false by default. Note that couriers only offer Saturday delivery for shipments with selected services shipping on selected weekdays and going to selected destinations. 		false
shipping_date (date)
When should the shipment be sent? today is the date by default. 		2015-12-11
reference (string)
Your reference for that shipment. Max: 30 chars 		123 test
driver_instructions (string)
Prints instructions on the label for the driver to see. Max: 30 chars 		Doorbell broken, knock on door
address_correction (boolean)
Should Flagship attempt to correct the receiver's address? false by default 		false
return_documents_as (enum)
How you want the labels to be returned. url or base64. Defaults to url 		url|base64
shipment_tracking_emails (string)
Semicolon-separated list of email addresses that will receive shipment tracking emails 		jbeans@company.com;shipping1@company.com
pickup_details (Pickup Details)
The Pickup information
Name Example Value
confirmation (string)
confirmation number 		2929602E9CP
address (address)
The pickup information for that shipment
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
telephone extension number 		11
is_commercial (boolean)
can be 0|1 		false
boxes (integer)
number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
units (string)
The shipment unit (imperia|metric) 		imperial
date (date)
can be YYYY-MM-DD 		2015-12-31
from (timestamp)
can be hour and minute in 24h format, hh:mm:ss 		09:00:00
until (timestamp)
can be hour and minute in 24h format, hh:mm:ss 		17:00:00
location (string)
Where the pick-up location is 		Reception
instruction (string)
special attention for delivery 		contain glass product, etc.
is_cancelled (boolean)
can be 0|1 		false
service (Service)
The service
Name Example Value
courier_name (string)
The courier requested for the dispatch 		fedex
courier_code (string)
The requested service for the dispatch. 		FIRST_OVERNIGHT
packages (Packages)
The packages contained in the shipment
Name Example Value
items (array)
Array of all the packages for that shipment
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
type (string)
package for your own boxes, letter for a courier letter or pack for the 3lbs courier pack. 		package
content (string)
Default value: goods - If the type is letter, then document can be specified if only documents with no commercial value are being shipped 		goods
price (Invoiced Price Structure)
The list of charges for the shipment
Name Example Value
charges (Shipment Charges)
List of charges relating to the shipment
Name Example Value
freight (decimal)
The freight cost 		123.45
signature_required (decimal)
Cost for a required signature 		123.45
insurance (decimal)
Cost of the insurance for the shipment 		123.45
multipiece (decimal)
Cost of too many boxes for the shipment 		123.45
adjustments (Shipment Adjustments)
Adjustments charged in addition to the original charges by the courier
Name Example Value
fuel_surchage (decimal)
Cost of fuel 		123.45
subtotal (decimal)
Total before taxes 		123.45
total (decimal)
Total after taxes 		123.45
taxes (Shipment Taxes)
Breakdown of taxes on the shipment
Name Example Value
gst (decimal)
123.45
qst (decimal)
123.45
pst (decimal)
123.45
hst (decimal)
123.45
brokerage_details (Brokerage Details)
Brokerage information
Name Example Value
description (string)
Item description 		Chocolate covered gift box
items (array)
Array of all the items for that shipment
Name Example Value
country_of_origin (string)
ISO 3166-1 alpha-2 two letter country code 		CA
description (string)
description of the item 		Sweet Biscuits
duty_value (decimal)
Duty value 		3074.67
class_number (string)
Class number 		1905312900
duty (decimal)
Duty amount 		0
excise_tax_rate (integer)
Excise tax rate 		0
excise_tax_amount (decimal)
Excise tax amount 		0
gst_hst_rate (integer)
GST HST rate 		0
gst_hst_amount (decimal)
GST HST amount 		0
tax_value (decimal)
Tax value 		0
sima_assess (integer)
Antidumping and countervailing duties are assessed against subject goods that originate in, or are exported from a specific country 		0
total_customs (decimal)
Total customs 		0
total_duty (decimal)
Total duty 		3074.67
currency (enum)
The currency at which items were valued at 		CAD|USD
billed_weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
weight_units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
package_count (integer)
Package counts 		4
invoice_number (string)
The invoice number 		1234567
documents (Labels)
The shipping labels provided by the courier and commercial invoice, if applicable
Name Example Value
regular (url)
The URL for the regular sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=reg
thermal (url)
The URL for the thermal sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=therm
nafta_form_url (url)
URL for NAFTA form (Only applicable to shipments destined to NAFTA countries with goods that for the reduced or eliminated duties allowed under NAFTA) 		https://www.cbp.gov/sites/default/files/documents/CBP%20Form%20434_3.pdf
transit_details (array)
The transit details for shipment
Name Example Value
last_update (string)
Courier update for shipment. 		2017-06-09 23:00:00
status (string)
The shipment status (M: Manifested, P: Picked up, T: In transit, D: Delivered, U: Unknown, X: Exception) 		D
message (string)
Status description for the shipment. 		Shipment delivered to YALE via GUELPH, ON depot
invoice_details (multi-object)
The breakdown of all invoiced charges for this shipment
Name Example Value
cycle_id (string)
The cycle id for where the charges have been invoiced 		201712-52
invoice_id (integer)
The invoice id for where the charges have been invoiced 		123
originals (multi-object)
The breakdown of charges for when the shipment was confirmed. Includes freight charges and any additional surcharges.
Name Example Value
reason (string)
The reason of that charge 		special handling
amount (decimal)
The total amount for that charge 		123.45
adjustements (multi-object)
The breakdown of adjustements this shipment was charged for when it was invoiced.
Name Example Value
reason (string)
The reason of that charge 		special handling
amount (decimal)
The total amount for that charge 		123.45
credits (multi-object)
Any credits on existing charges.
Name Example Value
reason (string)
The reason of that charge 		special handling
amount (decimal)
The total amount for that charge 		123.45
payments (multi-object)
Any payments or refunds applied to the shipment.
Name Example Value
reason (string)
The reason of that charge 		special handling
amount (decimal)
The total amount for that charge 		123.45
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Modify

Update the shipment identified by id field from the request uri

Action

[PUT] ship/shipments/{id}

Request

PUT ship/shipments/{id} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "from": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "123",
        "department": "Reception",
        "is_commercial": true
    },
    "to": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "123",
        "department": "Reception",
        "is_commercial": true
    },
    "packages": {
        "items": [
            {
                "width": 22,
                "height": 22,
                "length": 22,
                "weight": 22,
                "description": "Item description"
            },
            "..."
        ],
        "units": "imperial",
        "type": "package",
        "content": "goods"
    },
    "payment": {
        "payer": "F"
    },
    "service": {
        "courier_name": "fedex",
        "courier_code": "FIRST_OVERNIGHT"
    },
    "options": {
        "insurance": {
            "value": 123.45,
            "description": "Children books"
        },
        "cod": {
            "method": "check",
            "payable_to": "Bob",
            "receiver_phone": "18663208383",
            "amount": 123.45,
            "currency": "CAD"
        },
        "signature_required": false,
        "saturday_delivery": false,
        "shipping_date": "2015-12-11",
        "reference": "123 test",
        "driver_instructions": "Doorbell broken, knock on door",
        "address_correction": false,
        "return_documents_as": "url",
        "shipment_tracking_emails": "jbeans@company.com;shipping1@company.com"
    }
}

Details

Name Example Value
from (Address)
Where the shipment is originating from
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
a valid canadian province 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
to (Address)
Where the shipment is going
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
packages (Packages)
What are you shipping?
Name Example Value
items (array)
Array of all the packages for that shipment
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
type (string)
package for your own boxes, letter for a courier letter or pack for the 3lbs courier pack. 		package
content (string)
Default value: goods - If the type is letter, then document can be specified if only documents with no commercial value are being shipped 		goods
payment (enum-objects)
Who is paying for this shipment?
Flagship Payment
Name Example Value
payer (string)
F - your Flagship Account, the most likely. 		F
Collect Payment
Name Example Value
payer (string)
C - Collect; the shipment will be billed on the receiver's account. 		C
payer_account (string)
The account of the payer with the selected courier. 		123456
Third Party Payment
Name Example Value
payer (string)
T - A Third Party will be charged for the shipment. 		T
payer_account (string)
The account of the payer with the selected courier. 		123456
payer_tp_address (Address)
The address of the third party payer
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
service (Service)
What courier and courier service are we using?
Name Example Value
courier_name (string)
The courier requested for the dispatch 		fedex
courier_code (string)
The requested service for the dispatch. 		FIRST_OVERNIGHT
options (Options)
The options for this shipment. None of the options are required.
Name Example Value
insurance (Insurance Option)
Would you like to add insurance for the shipment? Not set by default
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
description (integer)
What is to be insured? 		Children books
cod (COD Option)
Cash on delivery. Request an amount to be paid for the driver to release the package.
Name Example Value
method (enum)
How to pay the requested amount 		check|cert_check|money_order
payable_to (string)
To who the payment must be addressed to 		Bob
receiver_phone (string)
Phone of the person that will receive payment 		18663208383
amount (decimal)
The amount requested to be paid on delivery 		123.45
currency (enum)
Currency of the amount 		CAD|USD
signature_required (boolean)
Is the signatured required upon delivery? false by default
It will be forced to true if shipment is insured and it is going to a residential address 		false
saturday_delivery (boolean)
Is the saturday delivery requested? false by default. Note that couriers only offer Saturday delivery for shipments with selected services shipping on selected weekdays and going to selected destinations. 		false
shipping_date (date)
When should the shipment be sent? today is the date by default. 		2015-12-11
reference (string)
Your reference for that shipment. Max: 30 chars 		123 test
driver_instructions (string)
Prints instructions on the label for the driver to see. Max: 30 chars 		Doorbell broken, knock on door
address_correction (boolean)
Should Flagship attempt to correct the receiver's address? false by default 		false
return_documents_as (enum)
How you want the labels to be returned. url or base64. Defaults to url 		url|base64
shipment_tracking_emails (string)
Semicolon-separated list of email addresses that will receive shipment tracking emails 		jbeans@company.com;shipping1@company.com

Response

200 OK 

{
    "content": {
        "id": 1122341,
        "tracking_number": "1P0075H07633636542",
        "pickup_id": 1122342,
        "status": "prequoted",
        "from": {
            "name": "ACME inc.",
            "attn": "Bob",
            "address": "123 Main Street",
            "suite": "227",
            "city": "Montreal",
            "country": "CA",
            "state": "QC",
            "postal_code": "A1A1A1",
            "phone": "18663208383",
            "ext": "123",
            "department": "Reception",
            "is_commercial": true
        },
        "to": {
            "name": "ACME inc.",
            "attn": "Bob",
            "address": "123 Main Street",
            "suite": "227",
            "city": "Montreal",
            "country": "CA",
            "state": "QC",
            "postal_code": "A1A1A1",
            "phone": "18663208383",
            "ext": "123",
            "department": "Reception",
            "is_commercial": true
        },
        "options": {
            "insurance": {
                "value": 123.45,
                "description": "Children books"
            },
            "cod": {
                "method": "check",
                "payable_to": "Bob",
                "receiver_phone": "18663208383",
                "amount": 123.45,
                "currency": "CAD"
            },
            "signature_required": false,
            "saturday_delivery": false,
            "shipping_date": "2015-12-11",
            "reference": "123 test",
            "driver_instructions": "Doorbell broken, knock on door",
            "address_correction": false,
            "return_documents_as": "url",
            "shipment_tracking_emails": "jbeans@company.com;shipping1@company.com"
        },
        "pickup_details": {
            "confirmation": "2929602E9CP",
            "address": {
                "name": "ACME inc.",
                "attn": "Bob",
                "address": "123 Main Street",
                "suite": "227",
                "city": "Montreal",
                "country": "CA",
                "state": "QC",
                "postal_code": "A1A1A1",
                "phone": "18663208383",
                "ext": "11",
                "is_commercial": false
            },
            "boxes": 4,
            "weight": 6,
            "units": "imperial",
            "date": "2015-12-31",
            "from": "09:00:00",
            "until": "17:00:00",
            "location": "Reception",
            "instruction": "contain glass product, etc.",
            "is_cancelled": false
        },
        "service": {
            "courier_name": "fedex",
            "courier_code": "FIRST_OVERNIGHT"
        },
        "packages": {
            "items": [
                {
                    "width": 22,
                    "height": 22,
                    "length": 22,
                    "weight": 22,
                    "description": "Item description"
                },
                "..."
            ],
            "units": "imperial",
            "type": "package",
            "content": "goods"
        },
        "price": {
            "charges": {
                "freight": 123.45,
                "signature_required": 123.45,
                "insurance": 123.45,
                "multipiece": 123.45
            },
            "adjustments": {
                "fuel_surchage": 123.45
            },
            "subtotal": 123.45,
            "total": 123.45,
            "taxes": {
                "gst": 123.45,
                "qst": 123.45,
                "pst": 123.45,
                "hst": 123.45
            }
        },
        "brokerage_details": {
            "description": "Chocolate covered gift box",
            "items": [
                {
                    "country_of_origin": "CA",
                    "description": "Sweet Biscuits",
                    "duty_value": 3074.67,
                    "class_number": "1905312900",
                    "duty": 0,
                    "excise_tax_rate": 0,
                    "excise_tax_amount": 0,
                    "gst_hst_rate": 0,
                    "gst_hst_amount": 0,
                    "tax_value": 0,
                    "sima_assess": 0,
                    "total_customs": 0
                },
                "..."
            ],
            "total_duty": 3074.67,
            "currency": "CAD",
            "billed_weight": 6,
            "weight_units": "imperial",
            "package_count": 4,
            "invoice_number": "1234567"
        },
        "documents": {
            "regular": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=reg",
            "thermal": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=therm"
        },
        "nafta_form_url": "https:\/\/www.cbp.gov\/sites\/default\/files\/documents\/CBP%20Form%20434_3.pdf",
        "transit_details": [
            {
                "last_update": "2017-06-09 23:00:00",
                "status": "D",
                "message": "Shipment delivered to YALE via GUELPH, ON depot"
            },
            "..."
        ]
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Shipment)
Name Example Value
id (integer)
The shipment id 		1122341
tracking_number (string)
The tracking number 		1P0075H07633636542
pickup_id (integer)
The pickup id is associated to the shipment 		1122342
status (enum)
The shipment status 		prequoted|quoted|predispatched|dispatched|manifested|cancelled
from (Address)
The from address
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
to (Address)
The to address
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
options (Options)
Name Example Value
insurance (Insurance Option)
Would you like to add insurance for the shipment? Not set by default
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
description (integer)
What is to be insured? 		Children books
cod (COD Option)
Cash on delivery. Request an amount to be paid for the driver to release the package.
Name Example Value
method (enum)
How to pay the requested amount 		check|cert_check|money_order
payable_to (string)
To who the payment must be addressed to 		Bob
receiver_phone (string)
Phone of the person that will receive payment 		18663208383
amount (decimal)
The amount requested to be paid on delivery 		123.45
currency (enum)
Currency of the amount 		CAD|USD
signature_required (boolean)
Is the signatured required upon delivery? false by default
It will be forced to true if shipment is insured and it is going to a residential address 		false
saturday_delivery (boolean)
Is the saturday delivery requested? false by default. Note that couriers only offer Saturday delivery for shipments with selected services shipping on selected weekdays and going to selected destinations. 		false
shipping_date (date)
When should the shipment be sent? today is the date by default. 		2015-12-11
reference (string)
Your reference for that shipment. Max: 30 chars 		123 test
driver_instructions (string)
Prints instructions on the label for the driver to see. Max: 30 chars 		Doorbell broken, knock on door
address_correction (boolean)
Should Flagship attempt to correct the receiver's address? false by default 		false
return_documents_as (enum)
How you want the labels to be returned. url or base64. Defaults to url 		url|base64
shipment_tracking_emails (string)
Semicolon-separated list of email addresses that will receive shipment tracking emails 		jbeans@company.com;shipping1@company.com
pickup_details (Pickup Details)
The Pickup information
Name Example Value
confirmation (string)
confirmation number 		2929602E9CP
address (address)
The pickup information for that shipment
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
telephone extension number 		11
is_commercial (boolean)
can be 0|1 		false
boxes (integer)
number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
units (string)
The shipment unit (imperia|metric) 		imperial
date (date)
can be YYYY-MM-DD 		2015-12-31
from (timestamp)
can be hour and minute in 24h format, hh:mm:ss 		09:00:00
until (timestamp)
can be hour and minute in 24h format, hh:mm:ss 		17:00:00
location (string)
Where the pick-up location is 		Reception
instruction (string)
special attention for delivery 		contain glass product, etc.
is_cancelled (boolean)
can be 0|1 		false
service (Service)
The service
Name Example Value
courier_name (string)
The courier requested for the dispatch 		fedex
courier_code (string)
The requested service for the dispatch. 		FIRST_OVERNIGHT
packages (Packages)
The packages contained in the shipment
Name Example Value
items (array)
Array of all the packages for that shipment
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
type (string)
package for your own boxes, letter for a courier letter or pack for the 3lbs courier pack. 		package
content (string)
Default value: goods - If the type is letter, then document can be specified if only documents with no commercial value are being shipped 		goods
price (Invoiced Price Structure)
The list of charges for the shipment
Name Example Value
charges (Shipment Charges)
List of charges relating to the shipment
Name Example Value
freight (decimal)
The freight cost 		123.45
signature_required (decimal)
Cost for a required signature 		123.45
insurance (decimal)
Cost of the insurance for the shipment 		123.45
multipiece (decimal)
Cost of too many boxes for the shipment 		123.45
adjustments (Shipment Adjustments)
Adjustments charged in addition to the original charges by the courier
Name Example Value
fuel_surchage (decimal)
Cost of fuel 		123.45
subtotal (decimal)
Total before taxes 		123.45
total (decimal)
Total after taxes 		123.45
taxes (Shipment Taxes)
Breakdown of taxes on the shipment
Name Example Value
gst (decimal)
123.45
qst (decimal)
123.45
pst (decimal)
123.45
hst (decimal)
123.45
brokerage_details (Brokerage Details)
Brokerage information
Name Example Value
description (string)
Item description 		Chocolate covered gift box
items (array)
Array of all the items for that shipment
Name Example Value
country_of_origin (string)
ISO 3166-1 alpha-2 two letter country code 		CA
description (string)
description of the item 		Sweet Biscuits
duty_value (decimal)
Duty value 		3074.67
class_number (string)
Class number 		1905312900
duty (decimal)
Duty amount 		0
excise_tax_rate (integer)
Excise tax rate 		0
excise_tax_amount (decimal)
Excise tax amount 		0
gst_hst_rate (integer)
GST HST rate 		0
gst_hst_amount (decimal)
GST HST amount 		0
tax_value (decimal)
Tax value 		0
sima_assess (integer)
Antidumping and countervailing duties are assessed against subject goods that originate in, or are exported from a specific country 		0
total_customs (decimal)
Total customs 		0
total_duty (decimal)
Total duty 		3074.67
currency (enum)
The currency at which items were valued at 		CAD|USD
billed_weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
weight_units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
package_count (integer)
Package counts 		4
invoice_number (string)
The invoice number 		1234567
documents (Labels)
The shipping labels provided by the courier and commercial invoice, if applicable
Name Example Value
regular (url)
The URL for the regular sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=reg
thermal (url)
The URL for the thermal sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=therm
nafta_form_url (url)
URL for NAFTA form (Only applicable to shipments destined to NAFTA countries with goods that for the reduced or eliminated duties allowed under NAFTA) 		https://www.cbp.gov/sites/default/files/documents/CBP%20Form%20434_3.pdf
transit_details (array)
The transit details for shipment
Name Example Value
last_update (string)
Courier update for shipment. 		2017-06-09 23:00:00
status (string)
The shipment status (M: Manifested, P: Picked up, T: In transit, D: Delivered, U: Unknown, X: Exception) 		D
message (string)
Status description for the shipment. 		Shipment delivered to YALE via GUELPH, ON depot
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Confirm by id

Confirms the shipment identified by id field from the request uri

Action

[PUT] /ship/{Id}/confirm

Request

PUT /ship/{Id}/confirm HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json

Response

200 OK 

{
    "content": {
        "shipment_id": "201012221",
        "tracking_number": "329018797020",
        "price": {
            "charges": {
                "freight": 123.45,
                "signature_required": 123.45,
                "insurance": 123.45,
                "multipiece": 123.45
            },
            "adjustments": null,
            "subtotal": 123.45,
            "total": 123.45,
            "taxes": {
                "gst": 123.45,
                "qst": 123.45,
                "pst": 123.45,
                "hst": 123.45
            }
        },
        "service": {
            "flagship_code": "expressEarlyAm",
            "courier_code": "FIRST_OVERNIGHT",
            "courier_desc": "First Overnight",
            "courier_name": "FedEx",
            "transit_time": 1,
            "estimated_delivery_date": "2015-12-03 23:30:00"
        },
        "labels": {
            "regular": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=reg",
            "thermal": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=therm"
        },
        "packages": [
            {
                "width": 22,
                "height": 22,
                "length": 22,
                "weight": 22,
                "description": "Item description",
                "pin": "72909513411"
            },
            "..."
        ],
        "documents_only": false,
        "commercial_invoice": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=statement",
        "nafta_form_url": "https:\/\/www.cbp.gov\/sites\/default\/files\/documents\/CBP%20Form%20434_3.pdf"
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Shipment)
Name Example Value
shipment_id (number)
The shipment id as it appears in the Flagship API 		201012221
tracking_number (string)
The tracking number associated with your shipment. This is a courier generated value 		329018797020
price (Price Structure)
A price breakdown for the requested service
Name Example Value
charges (Shipment Charges)
List of charges relating to the shipment
Name Example Value
freight (decimal)
The freight cost 		123.45
signature_required (decimal)
Cost for a required signature 		123.45
insurance (decimal)
Cost of the insurance for the shipment 		123.45
multipiece (decimal)
Cost of too many boxes for the shipment 		123.45
adjustments (null)
Adjustments charged in addition to the original charges by the courier
subtotal (decimal)
Total before taxes 		123.45
total (decimal)
Total after taxes 		123.45
taxes (Shipment Taxes)
Breakdown of taxes on the shipment
Name Example Value
gst (decimal)
123.45
qst (decimal)
123.45
pst (decimal)
123.45
hst (decimal)
123.45
service (Service)
Details about the service selected
Name Example Value
flagship_code (string)
The internal flagship code for that courier's service 		expressEarlyAm
courier_code (string)
The internal courier code for that service. You will need it to confirm the shipment 		FIRST_OVERNIGHT
courier_desc (string)
The nice name of the service 		First Overnight
courier_name (string)
Name of the courier 		FedEx
transit_time (integer)
The time in transit the shipment will take, in business days. Can be null if not provided by the courier, but it will be present in the response. 		1
estimated_delivery_date (string)
Local date time of when the shipment will be delivered by. Usually is present if transit_time is null. Can be also null 		2015-12-03 23:30:00
labels (Labels)
The shipping labels provided from the courier
Name Example Value
regular (url)
The URL for the regular sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=reg
thermal (url)
The URL for the thermal sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=therm
packages (array)
List of the packages in the shipment, along with the courier-assigned PIN numbers
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
pin (string)
The pin associated to the package. 		72909513411
documents_only (boolean)
Is this shipment containing documents only? 		false
commercial_invoice (url)
URL for the Flagship generated commercial invoice required for an international shipment 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=statement
nafta_form_url (url)
URL for NAFTA form (Only appears when the field is_nafta of sold_to in the request is true) 		https://www.cbp.gov/sites/default/files/documents/CBP%20Form%20434_3.pdf
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Cancel

Cancel the shipment identified by its shipment id field from the request uri

Action

[DELETE] /ship/shipments/{id}

Request

DELETE /ship/shipments/{id} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json

Response

204 NO CONTENT

List

Get the list of shipments

Action

[GET] /ship/shipments

URI Parameters

Parameter Value Description
courier ups Filter by the courier. Options are ups|dhl|fedex|purolator|canpar|dicom
status dispatched Filter by the shipment status. Options are prequoted|quoted|predispatched|dispatched|manifested|cancelled
reference Some reference Filter by the shipment reference
tracking_number 1234321445 The shipment's tracking number.
package_pin 112234 A shipment's package pin
page 2 The page wanted in the list of results
limit 23 The number of results wanted per page. Maximum 50.

Request

GET /ship/shipments HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK 

{
    "content": {
        "records": [
            {
                "id": 1122341,
                "tracking_number": "1P0075H07633636542",
                "pickup_id": 1122342,
                "status": "prequoted",
                "from": {
                    "name": "ACME inc.",
                    "attn": "Bob",
                    "address": "123 Main Street",
                    "suite": "227",
                    "city": "Montreal",
                    "country": "CA",
                    "state": "QC",
                    "postal_code": "A1A1A1",
                    "phone": "18663208383",
                    "ext": "123",
                    "department": "Reception",
                    "is_commercial": true
                },
                "to": {
                    "name": "ACME inc.",
                    "attn": "Bob",
                    "address": "123 Main Street",
                    "suite": "227",
                    "city": "Montreal",
                    "country": "CA",
                    "state": "QC",
                    "postal_code": "A1A1A1",
                    "phone": "18663208383",
                    "ext": "123",
                    "department": "Reception",
                    "is_commercial": true
                },
                "options": {
                    "insurance": {
                        "value": 123.45,
                        "description": "Children books"
                    },
                    "cod": {
                        "method": "check",
                        "payable_to": "Bob",
                        "receiver_phone": "18663208383",
                        "amount": 123.45,
                        "currency": "CAD"
                    },
                    "signature_required": false,
                    "saturday_delivery": false,
                    "shipping_date": "2015-12-11",
                    "reference": "123 test",
                    "driver_instructions": "Doorbell broken, knock on door",
                    "address_correction": false,
                    "return_documents_as": "url",
                    "shipment_tracking_emails": "jbeans@company.com;shipping1@company.com"
                },
                "pickup_details": {
                    "confirmation": "2929602E9CP",
                    "address": {
                        "name": "ACME inc.",
                        "attn": "Bob",
                        "address": "123 Main Street",
                        "suite": "227",
                        "city": "Montreal",
                        "country": "CA",
                        "state": "QC",
                        "postal_code": "A1A1A1",
                        "phone": "18663208383",
                        "ext": "11",
                        "is_commercial": false
                    },
                    "boxes": 4,
                    "weight": 6,
                    "units": "imperial",
                    "date": "2015-12-31",
                    "from": "09:00:00",
                    "until": "17:00:00",
                    "location": "Reception",
                    "instruction": "contain glass product, etc.",
                    "is_cancelled": false
                },
                "service": {
                    "courier_name": "fedex",
                    "courier_code": "FIRST_OVERNIGHT"
                },
                "packages": {
                    "items": [
                        {
                            "width": 22,
                            "height": 22,
                            "length": 22,
                            "weight": 22,
                            "description": "Item description"
                        },
                        "..."
                    ],
                    "units": "imperial",
                    "type": "package",
                    "content": "goods"
                },
                "price": {
                    "charges": {
                        "freight": 123.45,
                        "signature_required": 123.45,
                        "insurance": 123.45,
                        "multipiece": 123.45
                    },
                    "adjustments": {
                        "fuel_surchage": 123.45
                    },
                    "subtotal": 123.45,
                    "total": 123.45,
                    "taxes": {
                        "gst": 123.45,
                        "qst": 123.45,
                        "pst": 123.45,
                        "hst": 123.45
                    }
                },
                "brokerage_details": {
                    "description": "Chocolate covered gift box",
                    "items": [
                        {
                            "country_of_origin": "CA",
                            "description": "Sweet Biscuits",
                            "duty_value": 3074.67,
                            "class_number": "1905312900",
                            "duty": 0,
                            "excise_tax_rate": 0,
                            "excise_tax_amount": 0,
                            "gst_hst_rate": 0,
                            "gst_hst_amount": 0,
                            "tax_value": 0,
                            "sima_assess": 0,
                            "total_customs": 0
                        },
                        "..."
                    ],
                    "total_duty": 3074.67,
                    "currency": "CAD",
                    "billed_weight": 6,
                    "weight_units": "imperial",
                    "package_count": 4,
                    "invoice_number": "1234567"
                },
                "documents": {
                    "regular": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=reg",
                    "thermal": "https:\/\/api.smartship.io\/ship\/201012221\/labels\/102xae1e80cddb\/?document=therm"
                },
                "nafta_form_url": "https:\/\/www.cbp.gov\/sites\/default\/files\/documents\/CBP%20Form%20434_3.pdf",
                "transit_details": [
                    {
                        "last_update": "2017-06-09 23:00:00",
                        "status": "D",
                        "message": "Shipment delivered to YALE via GUELPH, ON depot"
                    },
                    "..."
                ]
            },
            "..."
        ],
        "current_page": 2,
        "max_per_page": 20,
        "nb_of_pages": 7,
        "nb_of_records": 131
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Shipment List)
Name Example Value
records (array)
Array with the shipments belonging to the requested page
Name Example Value
id (integer)
The shipment id 		1122341
tracking_number (string)
The tracking number 		1P0075H07633636542
pickup_id (integer)
The pickup id is associated to the shipment 		1122342
status (enum)
The shipment status 		prequoted|quoted|predispatched|dispatched|manifested|cancelled
from (Address)
The from address
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
to (Address)
The to address
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
123
department (string)
Reception
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
options (Options)
Name Example Value
insurance (Insurance Option)
Would you like to add insurance for the shipment? Not set by default
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
description (integer)
What is to be insured? 		Children books
cod (COD Option)
Cash on delivery. Request an amount to be paid for the driver to release the package.
Name Example Value
method (enum)
How to pay the requested amount 		check|cert_check|money_order
payable_to (string)
To who the payment must be addressed to 		Bob
receiver_phone (string)
Phone of the person that will receive payment 		18663208383
amount (decimal)
The amount requested to be paid on delivery 		123.45
currency (enum)
Currency of the amount 		CAD|USD
signature_required (boolean)
Is the signatured required upon delivery? false by default
It will be forced to true if shipment is insured and it is going to a residential address 		false
saturday_delivery (boolean)
Is the saturday delivery requested? false by default. Note that couriers only offer Saturday delivery for shipments with selected services shipping on selected weekdays and going to selected destinations. 		false
shipping_date (date)
When should the shipment be sent? today is the date by default. 		2015-12-11
reference (string)
Your reference for that shipment. Max: 30 chars 		123 test
driver_instructions (string)
Prints instructions on the label for the driver to see. Max: 30 chars 		Doorbell broken, knock on door
address_correction (boolean)
Should Flagship attempt to correct the receiver's address? false by default 		false
return_documents_as (enum)
How you want the labels to be returned. url or base64. Defaults to url 		url|base64
shipment_tracking_emails (string)
Semicolon-separated list of email addresses that will receive shipment tracking emails 		jbeans@company.com;shipping1@company.com
pickup_details (Pickup Details)
The Pickup information
Name Example Value
confirmation (string)
confirmation number 		2929602E9CP
address (address)
The pickup information for that shipment
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
telephone extension number 		11
is_commercial (boolean)
can be 0|1 		false
boxes (integer)
number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
units (string)
The shipment unit (imperia|metric) 		imperial
date (date)
can be YYYY-MM-DD 		2015-12-31
from (timestamp)
can be hour and minute in 24h format, hh:mm:ss 		09:00:00
until (timestamp)
can be hour and minute in 24h format, hh:mm:ss 		17:00:00
location (string)
Where the pick-up location is 		Reception
instruction (string)
special attention for delivery 		contain glass product, etc.
is_cancelled (boolean)
can be 0|1 		false
service (Service)
The service
Name Example Value
courier_name (string)
The courier requested for the dispatch 		fedex
courier_code (string)
The requested service for the dispatch. 		FIRST_OVERNIGHT
packages (Packages)
The packages contained in the shipment
Name Example Value
items (array)
Array of all the packages for that shipment
Name Example Value
width (integer)
width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
height (integer)
height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
length (integer)
length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
weight (integer)
weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		22
description (string)
What the package contains. Required for international shipments 		Item description
units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
type (string)
package for your own boxes, letter for a courier letter or pack for the 3lbs courier pack. 		package
content (string)
Default value: goods - If the type is letter, then document can be specified if only documents with no commercial value are being shipped 		goods
price (Invoiced Price Structure)
The list of charges for the shipment
Name Example Value
charges (Shipment Charges)
List of charges relating to the shipment
Name Example Value
freight (decimal)
The freight cost 		123.45
signature_required (decimal)
Cost for a required signature 		123.45
insurance (decimal)
Cost of the insurance for the shipment 		123.45
multipiece (decimal)
Cost of too many boxes for the shipment 		123.45
adjustments (Shipment Adjustments)
Adjustments charged in addition to the original charges by the courier
Name Example Value
fuel_surchage (decimal)
Cost of fuel 		123.45
subtotal (decimal)
Total before taxes 		123.45
total (decimal)
Total after taxes 		123.45
taxes (Shipment Taxes)
Breakdown of taxes on the shipment
Name Example Value
gst (decimal)
123.45
qst (decimal)
123.45
pst (decimal)
123.45
hst (decimal)
123.45
brokerage_details (Brokerage Details)
Brokerage information
Name Example Value
description (string)
Item description 		Chocolate covered gift box
items (array)
Array of all the items for that shipment
Name Example Value
country_of_origin (string)
ISO 3166-1 alpha-2 two letter country code 		CA
description (string)
description of the item 		Sweet Biscuits
duty_value (decimal)
Duty value 		3074.67
class_number (string)
Class number 		1905312900
duty (decimal)
Duty amount 		0
excise_tax_rate (integer)
Excise tax rate 		0
excise_tax_amount (decimal)
Excise tax amount 		0
gst_hst_rate (integer)
GST HST rate 		0
gst_hst_amount (decimal)
GST HST amount 		0
tax_value (decimal)
Tax value 		0
sima_assess (integer)
Antidumping and countervailing duties are assessed against subject goods that originate in, or are exported from a specific country 		0
total_customs (decimal)
Total customs 		0
total_duty (decimal)
Total duty 		3074.67
currency (enum)
The currency at which items were valued at 		CAD|USD
billed_weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
weight_units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial
package_count (integer)
Package counts 		4
invoice_number (string)
The invoice number 		1234567
documents (Labels)
The shipping labels provided by the courier and commercial invoice, if applicable
Name Example Value
regular (url)
The URL for the regular sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=reg
thermal (url)
The URL for the thermal sized label 		https://api.smartship.io/ship/201012221/labels/102xae1e80cddb/?document=therm
nafta_form_url (url)
URL for NAFTA form (Only applicable to shipments destined to NAFTA countries with goods that for the reduced or eliminated duties allowed under NAFTA) 		https://www.cbp.gov/sites/default/files/documents/CBP%20Form%20434_3.pdf
transit_details (array)
The transit details for shipment
Name Example Value
last_update (string)
Courier update for shipment. 		2017-06-09 23:00:00
status (string)
The shipment status (M: Manifested, P: Picked up, T: In transit, D: Delivered, U: Unknown, X: Exception) 		D
message (string)
Status description for the shipment. 		Shipment delivered to YALE via GUELPH, ON depot
current_page (integer)
The page the returned records belong to 		2
max_per_page (integer)
The results per page 		20
nb_of_pages (integer)
The number of pages necessary to show all the list elements 		7
nb_of_records (integer)
The total number of records found 		131
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Packing

This will find out how package items can be fitted into the available boxes (Items are assumed to be shipped flat)

Action

[POST] /ship/packing

Request

POST /ship/packing HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "items": [
        {
            "length": 22,
            "width": 22,
            "height": 10,
            "weight": 10,
            "description": "computer screen"
        },
        "..."
    ],
    "boxes": [
        {
            "box_model": "S4319",
            "length": 52,
            "inner_length": 51,
            "width": 52,
            "inner_width": 51,
            "height": 30,
            "inner_height": 29,
            "weight": 1,
            "max_weight": 50
        },
        "..."
    ],
    "units": "imperial"
}

Details

Name Example Value
items (array)
Array of all the items
Name Example Value
length (decimal)
length of the item 		22
width (decimal)
width of the item 		22
height (decimal)
height of the item 		10
weight (decimal)
weight of the item 		10
description (string)
name of the item 		computer screen
boxes (array)
Array of all the available boxes (the models of boxes based on size)
Name Example Value
box_model (string)
A name given to a model of boxes for easier identification 		S4319
length (decimal)
Length of the box(outer size) 		52
inner_length (decimal)
Interior length of the box 		51
width (decimal)
Width of the box(outer size) 		52
inner_width (decimal)
Interior width of the box 		51
height (decimal)
height of the box(outer size) 		30
inner_height (decimal)
Interior height of the box 		29
weight (decimal)
weight of the box 		1
max_weight (decimal)
maximum weight the box can hold 		50
units (string)
imperial (inch, lb) or metric (cm, Kg) 		imperial

Response

200 OK 

{
    "content": {
        "packages": [
            {
                "box_model": "S-4319",
                "length": 52,
                "width": 52,
                "height": 30,
                "weight": 32,
                "items": [
                    "computer screen",
                    "computer screen",
                    "album"
                ]
            },
            "..."
        ],
        "units": "imperial"
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Packing Result)
Name Example Value
packages (array)
The boxes with items filled inside
Name Example Value
box_model (string)
The name of the box model given in the request 		S-4319
length (decimal)
length of the packed box(outer size) 		52
width (decimal)
width of the packed box(outer size) 		52
height (decimal)
height of the packed box(outer size) 		30
weight (decimal)
weight of the packed box (including the box itself and all the items inside) 		32
items (Item Descriptions)
A list of the descriptions of the items inside the packed box
Name Example Value
0 (string)
Item 1 		computer screen
1 (string)
Item 2 		computer screen
2 (string)
Item 3 		album
units (string)
imperial or metric 		imperial
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Available courier services

This will return a list of all available courier services

Action

[GET] /ship/available_services

URI Parameters

Parameter Value Description
courier_code ups Filter by the courier. Options are ups|dhl|fedex|purolator|canpar|dicom

Request

GET /ship/available_services HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK 

{
    "content": {
        "ups": [
            {
                "flagship_code": "expressAm",
                "courier_code": "PRIORITY_OVERNIGHT",
                "courier_description": "Priority Overnight"
            },
            "..."
        ],
        "fedex": [
            {
                "flagship_code": "expressAm",
                "courier_code": "PRIORITY_OVERNIGHT",
                "courier_description": "Priority Overnight"
            },
            "..."
        ],
        "purolator": [
            {
                "flagship_code": "expressAm",
                "courier_code": "PRIORITY_OVERNIGHT",
                "courier_description": "Priority Overnight"
            },
            "..."
        ]
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Available Services)
List of couriers with their services
Name Example Value
ups (array)
Available services from UPS
Name Example Value
flagship_code (string)
The service code given by Flagship 		expressAm
courier_code (string)
The service code given by courier 		PRIORITY_OVERNIGHT
courier_description (string)
The description of service by courier 		Priority Overnight
fedex (array)
Available services from FedEx
Name Example Value
flagship_code (string)
The service code given by Flagship 		expressAm
courier_code (string)
The service code given by courier 		PRIORITY_OVERNIGHT
courier_description (string)
The description of service by courier 		Priority Overnight
purolator (array)
Available services from Purolator
Name Example Value
flagship_code (string)
The service code given by Flagship 		expressAm
courier_code (string)
The service code given by courier 		PRIORITY_OVERNIGHT
courier_description (string)
The description of service by courier 		Priority Overnight
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Label

This will allow you to generate labels.

Get label by id

Get a label by shipment id.

Action

[GET] /ship/{shipmentId}/labels

URI Parameters

Parameter Value Description
document reg Get different types of labels ref|therm|statement|watch_info

Request

GET /ship/{shipmentId}/labels HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK 

[Binary Data]

Pickup

This will allow to get one(many), modify, and create pick-up for shipment.

Find by id

Get the pickup identified by id field from the request uri

Action

[GET] /pickups/{id}

Request

GET /pickups/{id} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK 

{
    "content": {
        "id": 48979792,
        "confirmation": "2929602E9CP",
        "address": {
            "name": "ACME inc.",
            "attn": "Bob",
            "address": "123 Main Street",
            "suite": "227",
            "city": "Montreal",
            "country": "CA",
            "state": "QC",
            "postal_code": "A1A1A1",
            "phone": "18663208383",
            "ext": "11",
            "is_commercial": false
        },
        "courier": "ups",
        "boxes": 4,
        "weight": 6,
        "date": "2015-12-31",
        "from": "09:00",
        "until": "17:00",
        "location": "BackDoor, Basement, BetweenDoors, Counter, Desk, FrontDesk, FrontDoor, FrontPorch, Garage, GateHouse, Kiosk, Lab, LoadingDock, Lobby, Mailbox, MailRoom, Office, OutsideDoor, PartsDepartment, Pharmacy, ProShop, Receiving, Reception, Security, ServiceCounter, Shipping, SideDoor, Switchboard, Vault, Warehouse",
        "instruction": "contain glass product, etc.",
        "cancelled": "0",
        "units": "imperial",
        "shipments": [
            "integer",
            "..."
        ]
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Pickup)
Name Example Value
id (integer)
The id of pickup 		48979792
confirmation (string)
confirmation number 		2929602E9CP
address (address)
The pickup information for that shipment
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
telephone extension number 		11
is_commercial (boolean)
can be 0|1 		false
courier (enum)
Courier service provider 		ups|dhl|fedex|purolator|canpar|dicom
boxes (integer)
number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
date (date)
can be YYYY-MM-DD 		2015-12-31
from (timestamp)
can be hour and minute in 24h format, hh:mm 		09:00
until (timestamp)
can be hour and minute in 24h format, hh:mm 		17:00
location (string)
Where the pick-up location is 		BackDoor, Basement, BetweenDoors, Counter, Desk, FrontDesk, FrontDoor, FrontPorch, Garage, GateHouse, Kiosk, Lab, LoadingDock, Lobby, Mailbox, MailRoom, Office, OutsideDoor, PartsDepartment, Pharmacy, ProShop, Receiving, Reception, Security, ServiceCounter, Shipping, SideDoor, Switchboard, Vault, Warehouse
instruction (string)
special attention for delivery 		contain glass product, etc.
cancelled (boolean)
can be 0|1 		0
units (enum)
Units of measurement 		imperial|metric
shipments (array)
Shipment ids associated to the pickup.
[]
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Create

Create a pickup without shipment ids.

Action

[POST] /pickups

Request

POST /pickups HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "address": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "211",
        "is_commercial": true
    },
    "courier": "ups",
    "boxes": 4,
    "weight": 6,
    "units": "imperial",
    "date": "2015-12-31",
    "from": "09:00",
    "until": "17:00",
    "location": "BackDoor, Basement, BetweenDoors, Counter, Desk, FrontDesk, FrontDoor, FrontPorch, Garage, GateHouse, Kiosk, Lab, LoadingDock, Lobby, Mailbox, MailRoom, Office, OutsideDoor, PartsDepartment, Pharmacy, ProShop, Receiving, Reception, Security, ServiceCounter, Shipping, SideDoor, Switchboard, Vault, Warehouse",
    "to_country": "CA",
    "is_ground": false,
    "instruction": "contain glass product, etc."
}

Details

Name Example Value
address (Address)
Pickup address
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
a valid canadian province 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
Telephone extension 		211
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
courier (enum)
Courier service provider 		ups|dhl|fedex|purolator|canpar|dicom
boxes (integer)
Number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
Weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
units (enum)
Units of measurement 		imperial|metric
date (date)
Can be YYYY-MM-DD. The default is the current date. 		2015-12-31
from (timestamp)
Can be hour and minute in 24h format, hh:mm 		09:00
until (timestamp)
Can be hour and minute in 24h format, hh:mm 		17:00
location (string)
Where the pick-up location is. The default is "Reception". 		BackDoor, Basement, BetweenDoors, Counter, Desk, FrontDesk, FrontDoor, FrontPorch, Garage, GateHouse, Kiosk, Lab, LoadingDock, Lobby, Mailbox, MailRoom, Office, OutsideDoor, PartsDepartment, Pharmacy, ProShop, Receiving, Reception, Security, ServiceCounter, Shipping, SideDoor, Switchboard, Vault, Warehouse
to_country (string)
Destination country code in ISO 3166-1 alpha-2 two letter country code format 		CA
is_ground (boolean)
It has to be true for Fedex Ground pickup. 		false
instruction (string)
Special attention for delivery 		contain glass product, etc.

Response

201 CREATED 

{
    "content": {
        "id": 48979792,
        "confirmation": "2929602E9CP",
        "address": {
            "name": "ACME inc.",
            "attn": "Bob",
            "address": "123 Main Street",
            "suite": "227",
            "city": "Montreal",
            "country": "CA",
            "state": "QC",
            "postal_code": "A1A1A1",
            "phone": "18663208383",
            "ext": "11",
            "is_commercial": false
        },
        "courier": "ups",
        "boxes": 4,
        "weight": 6,
        "date": "2015-12-31",
        "from": "09:00",
        "until": "17:00",
        "location": "BackDoor, Basement, BetweenDoors, Counter, Desk, FrontDesk, FrontDoor, FrontPorch, Garage, GateHouse, Kiosk, Lab, LoadingDock, Lobby, Mailbox, MailRoom, Office, OutsideDoor, PartsDepartment, Pharmacy, ProShop, Receiving, Reception, Security, ServiceCounter, Shipping, SideDoor, Switchboard, Vault, Warehouse",
        "instruction": "contain glass product, etc.",
        "cancelled": "0",
        "units": "imperial",
        "shipments": [
            "integer",
            "..."
        ]
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Pickup)
Name Example Value
id (integer)
The id of pickup 		48979792
confirmation (string)
confirmation number 		2929602E9CP
address (address)
The pickup information for that shipment
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
telephone extension number 		11
is_commercial (boolean)
can be 0|1 		false
courier (enum)
Courier service provider 		ups|dhl|fedex|purolator|canpar|dicom
boxes (integer)
number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
date (date)
can be YYYY-MM-DD 		2015-12-31
from (timestamp)
can be hour and minute in 24h format, hh:mm 		09:00
until (timestamp)
can be hour and minute in 24h format, hh:mm 		17:00
location (string)
Where the pick-up location is 		BackDoor, Basement, BetweenDoors, Counter, Desk, FrontDesk, FrontDoor, FrontPorch, Garage, GateHouse, Kiosk, Lab, LoadingDock, Lobby, Mailbox, MailRoom, Office, OutsideDoor, PartsDepartment, Pharmacy, ProShop, Receiving, Reception, Security, ServiceCounter, Shipping, SideDoor, Switchboard, Vault, Warehouse
instruction (string)
special attention for delivery 		contain glass product, etc.
cancelled (boolean)
can be 0|1 		0
units (enum)
Units of measurement 		imperial|metric
shipments (array)
Shipment ids associated to the pickup.
[]
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Create with shipments

Create a list of pickups for confirmed shipments. One pickup will be created for shipments that have the same courier, postal code, street number, and suite number (if applicable). (Note: Fedex Ground and other Fedex services are treated seperately for pickups).

Action

[POST] /pickups

Request

POST /pickups HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "address": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "211",
        "is_commercial": true
    },
    "date": "2015-12-31",
    "from": "09:00",
    "until": "17:00",
    "location": "BackDoor, Basement, BetweenDoors, Counter, Desk, FrontDesk, FrontDoor, FrontPorch, Garage, GateHouse, Kiosk, Lab, LoadingDock, Lobby, Mailbox, MailRoom, Office, OutsideDoor, PartsDepartment, Pharmacy, ProShop, Receiving, Reception, Security, ServiceCounter, Shipping, SideDoor, Switchboard, Vault, Warehouse",
    "instruction": "contain glass product, etc.",
    "shipments": [
        "integer",
        "..."
    ]
}

Details

Name Example Value
address (Address)
If the address is provided, it will override the addresses of all the associated shipments as the pickup address for all the shipments.
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
a valid canadian province 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
Telephone extension 		211
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
date (date)
Can be YYYY-MM-DD. The default is the current date. 		2015-12-31
from (timestamp)
Can be hour and minute in 24h format, hh:mm 		09:00
until (timestamp)
Can be hour and minute in 24h format, hh:mm 		17:00
location (string)
Where the pick-up location is. The default is "Reception". 		BackDoor, Basement, BetweenDoors, Counter, Desk, FrontDesk, FrontDoor, FrontPorch, Garage, GateHouse, Kiosk, Lab, LoadingDock, Lobby, Mailbox, MailRoom, Office, OutsideDoor, PartsDepartment, Pharmacy, ProShop, Receiving, Reception, Security, ServiceCounter, Shipping, SideDoor, Switchboard, Vault, Warehouse
instruction (string)
Special attention for delivery 		contain glass product, etc.
shipments (array)
Shipment Ids (e.g., 123456, 234567,)
[]

Response

201 CREATED 

{
    "content": [
        {
            "id": 48979792,
            "confirmation": "2929602E9CP",
            "address": {
                "name": "ACME inc.",
                "attn": "Bob",
                "address": "123 Main Street",
                "suite": "227",
                "city": "Montreal",
                "country": "CA",
                "state": "QC",
                "postal_code": "A1A1A1",
                "phone": "18663208383",
                "ext": "11",
                "is_commercial": false
            },
            "courier": "ups",
            "boxes": 4,
            "weight": 6,
            "date": "2015-12-31",
            "from": "09:00",
            "until": "17:00",
            "location": "BackDoor, Basement, BetweenDoors, Counter, Desk, FrontDesk, FrontDoor, FrontPorch, Garage, GateHouse, Kiosk, Lab, LoadingDock, Lobby, Mailbox, MailRoom, Office, OutsideDoor, PartsDepartment, Pharmacy, ProShop, Receiving, Reception, Security, ServiceCounter, Shipping, SideDoor, Switchboard, Vault, Warehouse",
            "instruction": "contain glass product, etc.",
            "cancelled": "0",
            "units": "imperial",
            "shipments": [
                "integer",
                "..."
            ]
        },
        "..."
    ],
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (array)
Name Example Value
id (integer)
The id of pickup 		48979792
confirmation (string)
confirmation number 		2929602E9CP
address (address)
The pickup information for that shipment
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
telephone extension number 		11
is_commercial (boolean)
can be 0|1 		false
courier (enum)
Courier service provider 		ups|dhl|fedex|purolator|canpar|dicom
boxes (integer)
number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
date (date)
can be YYYY-MM-DD 		2015-12-31
from (timestamp)
can be hour and minute in 24h format, hh:mm 		09:00
until (timestamp)
can be hour and minute in 24h format, hh:mm 		17:00
location (string)
Where the pick-up location is 		BackDoor, Basement, BetweenDoors, Counter, Desk, FrontDesk, FrontDoor, FrontPorch, Garage, GateHouse, Kiosk, Lab, LoadingDock, Lobby, Mailbox, MailRoom, Office, OutsideDoor, PartsDepartment, Pharmacy, ProShop, Receiving, Reception, Security, ServiceCounter, Shipping, SideDoor, Switchboard, Vault, Warehouse
instruction (string)
special attention for delivery 		contain glass product, etc.
cancelled (boolean)
can be 0|1 		0
units (enum)
Units of measurement 		imperial|metric
shipments (array)
Shipment ids associated to the created pickup.
[]
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

206 PARTIAL CONTENT 

{
    "content": [
        {
            "id": 48979792,
            "confirmation": "2929602E9CP",
            "address": {
                "name": "ACME inc.",
                "attn": "Bob",
                "address": "123 Main Street",
                "suite": "227",
                "city": "Montreal",
                "country": "CA",
                "state": "QC",
                "postal_code": "A1A1A1",
                "phone": "18663208383",
                "ext": "11",
                "is_commercial": false
            },
            "courier": "ups",
            "boxes": 4,
            "weight": 6,
            "date": "2015-12-31",
            "from": "09:00",
            "until": "17:00",
            "location": "BackDoor, Basement, BetweenDoors, Counter, Desk, FrontDesk, FrontDoor, FrontPorch, Garage, GateHouse, Kiosk, Lab, LoadingDock, Lobby, Mailbox, MailRoom, Office, OutsideDoor, PartsDepartment, Pharmacy, ProShop, Receiving, Reception, Security, ServiceCounter, Shipping, SideDoor, Switchboard, Vault, Warehouse",
            "instruction": "contain glass product, etc.",
            "cancelled": "0",
            "units": "imperial",
            "shipments": [
                "integer",
                "..."
            ]
        },
        "..."
    ],
    "errors": {
        "fedex": {
            "message": "Service is not available to this location",
            "shipments": "12345,123232"
        }
    },
    "notices": []
}

Details

Name Example Value
content (array)
Name Example Value
id (integer)
The id of pickup 		48979792
confirmation (string)
confirmation number 		2929602E9CP
address (address)
The pickup information for that shipment
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
telephone extension number 		11
is_commercial (boolean)
can be 0|1 		false
courier (enum)
Courier service provider 		ups|dhl|fedex|purolator|canpar|dicom
boxes (integer)
number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
date (date)
can be YYYY-MM-DD 		2015-12-31
from (timestamp)
can be hour and minute in 24h format, hh:mm 		09:00
until (timestamp)
can be hour and minute in 24h format, hh:mm 		17:00
location (string)
Where the pick-up location is 		BackDoor, Basement, BetweenDoors, Counter, Desk, FrontDesk, FrontDoor, FrontPorch, Garage, GateHouse, Kiosk, Lab, LoadingDock, Lobby, Mailbox, MailRoom, Office, OutsideDoor, PartsDepartment, Pharmacy, ProShop, Receiving, Reception, Security, ServiceCounter, Shipping, SideDoor, Switchboard, Vault, Warehouse
instruction (string)
special attention for delivery 		contain glass product, etc.
cancelled (boolean)
can be 0|1 		0
units (enum)
Units of measurement 		imperial|metric
shipments (array)
Shipment ids associated to the created pickup.
[]
errors (object)
Messages that AFFECT the outcome of the request will be shown here
Name Example Value
fedex (object)
Shows error returning from courier
Name Example Value
message (string)
Service is not available to this location
shipments (string)
12345,123232
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Modify

Update the pickup identified by id field from the request uri

Action

[PUT] /pickups/{id}

Request

PUT /pickups/{id} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "address": {
        "name": "ACME inc.",
        "attn": "Bob",
        "address": "123 Main Street",
        "suite": "227",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "18663208383",
        "ext": "211",
        "is_commercial": true
    },
    "courier": "ups",
    "boxes": 4,
    "weight": 6,
    "units": "imperial",
    "date": "2015-12-31",
    "from": "09:00",
    "until": "17:00",
    "location": "BackDoor, Basement, BetweenDoors, Counter, Desk, FrontDesk, FrontDoor, FrontPorch, Garage, GateHouse, Kiosk, Lab, LoadingDock, Lobby, Mailbox, MailRoom, Office, OutsideDoor, PartsDepartment, Pharmacy, ProShop, Receiving, Reception, Security, ServiceCounter, Shipping, SideDoor, Switchboard, Vault, Warehouse",
    "to_country": "CA",
    "is_ground": false,
    "instruction": "contain glass product, etc."
}

Details

Name Example Value
address (Address)
Pickup address
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
a valid canadian province 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
Telephone extension 		211
is_commercial (boolean)
Is the address entered a commercial address? true by default 		1
courier (enum)
Courier service provider 		ups|dhl|fedex|purolator|canpar|dicom
boxes (integer)
Number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
Weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
units (enum)
Units of measurement 		imperial|metric
date (date)
Can be YYYY-MM-DD. The default is the current date. 		2015-12-31
from (timestamp)
Can be hour and minute in 24h format, hh:mm 		09:00
until (timestamp)
Can be hour and minute in 24h format, hh:mm 		17:00
location (string)
Where the pick-up location is. The default is "Reception". 		BackDoor, Basement, BetweenDoors, Counter, Desk, FrontDesk, FrontDoor, FrontPorch, Garage, GateHouse, Kiosk, Lab, LoadingDock, Lobby, Mailbox, MailRoom, Office, OutsideDoor, PartsDepartment, Pharmacy, ProShop, Receiving, Reception, Security, ServiceCounter, Shipping, SideDoor, Switchboard, Vault, Warehouse
to_country (string)
Destination country code in ISO 3166-1 alpha-2 two letter country code format 		CA
is_ground (boolean)
It has to be true for Fedex Ground pickup. 		false
instruction (string)
Special attention for delivery 		contain glass product, etc.

Response

200 OK 

{
    "content": {
        "id": 48979792,
        "confirmation": "2929602E9CP",
        "address": {
            "name": "ACME inc.",
            "attn": "Bob",
            "address": "123 Main Street",
            "suite": "227",
            "city": "Montreal",
            "country": "CA",
            "state": "QC",
            "postal_code": "A1A1A1",
            "phone": "18663208383",
            "ext": "11",
            "is_commercial": false
        },
        "courier": "ups",
        "boxes": 4,
        "weight": 6,
        "date": "2015-12-31",
        "from": "09:00",
        "until": "17:00",
        "location": "BackDoor, Basement, BetweenDoors, Counter, Desk, FrontDesk, FrontDoor, FrontPorch, Garage, GateHouse, Kiosk, Lab, LoadingDock, Lobby, Mailbox, MailRoom, Office, OutsideDoor, PartsDepartment, Pharmacy, ProShop, Receiving, Reception, Security, ServiceCounter, Shipping, SideDoor, Switchboard, Vault, Warehouse",
        "instruction": "contain glass product, etc.",
        "cancelled": "0",
        "units": "imperial",
        "shipments": [
            "integer",
            "..."
        ]
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Pickup)
Name Example Value
id (integer)
The id of pickup 		48979792
confirmation (string)
confirmation number 		2929602E9CP
address (address)
The pickup information for that shipment
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
telephone extension number 		11
is_commercial (boolean)
can be 0|1 		false
courier (enum)
Courier service provider 		ups|dhl|fedex|purolator|canpar|dicom
boxes (integer)
number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
date (date)
can be YYYY-MM-DD 		2015-12-31
from (timestamp)
can be hour and minute in 24h format, hh:mm 		09:00
until (timestamp)
can be hour and minute in 24h format, hh:mm 		17:00
location (string)
Where the pick-up location is 		BackDoor, Basement, BetweenDoors, Counter, Desk, FrontDesk, FrontDoor, FrontPorch, Garage, GateHouse, Kiosk, Lab, LoadingDock, Lobby, Mailbox, MailRoom, Office, OutsideDoor, PartsDepartment, Pharmacy, ProShop, Receiving, Reception, Security, ServiceCounter, Shipping, SideDoor, Switchboard, Vault, Warehouse
instruction (string)
special attention for delivery 		contain glass product, etc.
cancelled (boolean)
can be 0|1 		0
units (enum)
Units of measurement 		imperial|metric
shipments (array)
Shipment ids associated to the pickup.
[]
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Cancel

Cancel the pickup identified by id field from the request uri

Action

[DELETE] /pickups/{id}

Request

DELETE /pickups/{id} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json

Response

204 NO CONTENT

List

List pick-ups filter by parameters

Action

[GET] /pickups

URI Parameters

Parameter Value Description
courier ups Courier service provider
date 2015-12-31 Can be YYYY-MM-DD
page 2 The page wanted in the list of results
limit 23 The number of results wanted per page. Maximum 50.

Request

GET /pickups HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK 

{
    "content": {
        "records": [
            {
                "id": 48979792,
                "confirmation": "2929602E9CP",
                "address": {
                    "name": "ACME inc.",
                    "attn": "Bob",
                    "address": "123 Main Street",
                    "suite": "227",
                    "city": "Montreal",
                    "country": "CA",
                    "state": "QC",
                    "postal_code": "A1A1A1",
                    "phone": "18663208383",
                    "ext": "11",
                    "is_commercial": false
                },
                "courier": "ups",
                "boxes": 4,
                "weight": 6,
                "date": "2015-12-31",
                "from": "09:00",
                "until": "17:00",
                "location": "BackDoor, Basement, BetweenDoors, Counter, Desk, FrontDesk, FrontDoor, FrontPorch, Garage, GateHouse, Kiosk, Lab, LoadingDock, Lobby, Mailbox, MailRoom, Office, OutsideDoor, PartsDepartment, Pharmacy, ProShop, Receiving, Reception, Security, ServiceCounter, Shipping, SideDoor, Switchboard, Vault, Warehouse",
                "instruction": "contain glass product, etc.",
                "cancelled": "0",
                "units": "imperial",
                "shipments": [
                    "integer",
                    "..."
                ]
            },
            "..."
        ],
        "current_page": 2,
        "max_per_page": 20,
        "nb_of_pages": 7,
        "nb_of_records": 131
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Pickup List)
Name Example Value
records (array)
Array with the pickups belonging to the requested page
Name Example Value
id (integer)
The id of pickup 		48979792
confirmation (string)
confirmation number 		2929602E9CP
address (address)
The pickup information for that shipment
Name Example Value
name (string)
ACME inc.
attn (string)
Bob
address (string)
123 Main Street
suite (string)
227
city (string)
Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1A1A1
phone (number)
18663208383
ext (number)
telephone extension number 		11
is_commercial (boolean)
can be 0|1 		false
courier (enum)
Courier service provider 		ups|dhl|fedex|purolator|canpar|dicom
boxes (integer)
number of boxes ceiled up to the nearest integer. eg: 3.2 = 4 		4
weight (integer)
weight ceiled up to the nearest integer. eg: 5.7 = 6 		6
date (date)
can be YYYY-MM-DD 		2015-12-31
from (timestamp)
can be hour and minute in 24h format, hh:mm 		09:00
until (timestamp)
can be hour and minute in 24h format, hh:mm 		17:00
location (string)
Where the pick-up location is 		BackDoor, Basement, BetweenDoors, Counter, Desk, FrontDesk, FrontDoor, FrontPorch, Garage, GateHouse, Kiosk, Lab, LoadingDock, Lobby, Mailbox, MailRoom, Office, OutsideDoor, PartsDepartment, Pharmacy, ProShop, Receiving, Reception, Security, ServiceCounter, Shipping, SideDoor, Switchboard, Vault, Warehouse
instruction (string)
special attention for delivery 		contain glass product, etc.
cancelled (boolean)
can be 0|1 		0
units (enum)
Units of measurement 		imperial|metric
shipments (array)
Shipment ids associated to the pickup.
[]
current_page (integer)
The page the returned records belong to 		2
max_per_page (integer)
The results per page 		20
nb_of_pages (integer)
The number of pages necessary to show all the list elements 		7
nb_of_records (integer)
The total number of records found 		131
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Broker

This will allow to get a list of custom brokers

List

Returns a list of all the available custom brokers

Action

[GET] /brokers

Request

GET /brokers HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK 

{
    "content": [
        {
            "id": 12,
            "code": "555",
            "name": "TCARATAC Inc",
            "street_lines": "2094 Grand Island Blvd.",
            "city": "Grand Island",
            "state_province_code": "NY",
            "postal_code": "14072",
            "country_code": "US",
            "phone": "716-773-9207"
        },
        "..."
    ],
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (array)
Name Example Value
id (integer)
The broker id that you will use in your confirmation request 		12
code (string)
The code associated to the broker 		555
name (string)
The broker name 		TCARATAC Inc
street_lines (string)
The broker address 		2094 Grand Island Blvd.
city (string)
The broker address's city 		Grand Island
state_province_code (string)
The broker address's state or province 		NY
postal_code (string)
The broker address's postal code 		14072
country_code (string)
The broker address's country code 		US
phone (string)
The broker phone number 		716-773-9207
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Tracking

This allows to get tracking information about shipments that you processed through FlagShip

Track shipment

Returns the tracking information related to a specific shipment

Action

[GET] /ship/track

URI Parameters

Parameter Value Description
shipment_id 1234567 The shipment id. Required if tracking_number is not specified.
tracking_number 1234567 The shipment's tracking number. Required if shipment_id is not specified.

Request

GET /ship/track HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK 

{
    "content": {
        "current_status": "D",
        "courier_update": "2015-10-01 16:43:00",
        "status_desc": "Description: Shipment delivered to K BONCI via BURNABY, BC depot",
        "shipment_id": "1406346"
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Tracking)
Name Example Value
current_status (string)
'M'-Manifested | 'P'-Pickup | 'T'-In transit | 'D'-Delivered | 'U'-Unknown | 'X'-Exception 		D
courier_update (string)
When the tracking data was last updated 		2015-10-01 16:43:00
status_desc (string)
Description of the shiment status provided by the courier 		Description: Shipment delivered to K BONCI via BURNABY, BC depot
shipment_id (string)
The shipment's id 		1406346
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Address Group

This allows to list, create, modify, and delete address groups.

Find an address group by id

Get an address group's details by id.

Action

[GET] /addresses/groups/{groupId}

Request

GET /addresses/groups/{groupId} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK 

{
    "content": {
        "id": 1122341,
        "name": "Your company addresses",
        "number_of_addresses": 10,
        "deletable": false,
        "type": "company_addresses"
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Address Group)
Name Example Value
id (integer)
The group id 		1122341
name (string)
Name of the address group 		Your company addresses
number_of_addresses (integer)
The total number of addresses in the address group 		10
deletable (boolean)
Indicates whether this address group can be deleted (Note: groups that contain system addresses (headquarter, pickup, billing) of a company cannot be deleted 		false
type (string)
Type of the address group (company_addresses|shipping_addresses|pickup_addresses|other_addresses) 		company_addresses
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

List

Get the list of address groups

Action

[GET] /addresses/groups

URI Parameters

Parameter Value Description
name Your company addresses Filter by group name
group_type company_addresses Filter by the type of address group. Options are company_addresses|shipping_addresses|pickup_addresses|other_addresses
contains_address_name John Doe Find address groups that contain at least one address with the provided recipient name

Request

GET /addresses/groups HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK 

{
    "content": {
        "records": [
            {
                "id": 1122341,
                "name": "Your company addresses",
                "number_of_addresses": 10,
                "deletable": false,
                "type": "company_addresses"
            },
            "..."
        ],
        "current_page": 2,
        "max_per_page": 20,
        "nb_of_pages": 7,
        "nb_of_records": 131
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Address Group List)
Name Example Value
records (array)
Array with address groups that satisfy the search criteria
Name Example Value
id (integer)
The group id 		1122341
name (string)
Name of the address group 		Your company addresses
number_of_addresses (integer)
The total number of addresses in the address group 		10
deletable (boolean)
Indicates whether this address group can be deleted (Note: groups that contain system addresses (headquarter, pickup, billing) of a company cannot be deleted 		false
type (string)
Type of the address group (company_addresses|shipping_addresses|pickup_addresses|other_addresses) 		company_addresses
current_page (integer)
The page the returned records belong to 		2
max_per_page (integer)
The results per page 		20
nb_of_pages (integer)
The number of pages necessary to show all the list elements 		7
nb_of_records (integer)
The total number of records found 		131
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Create

Create an address group.

Action

[POST] /addresses/groups

Request

POST /addresses/groups HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "name": "Your company addresses",
    "type": "company_addresses"
}

Details

Name Example Value
name (string)
Name of the address group 		Your company addresses
type (string)
Type of the address group (company_addresses|shipping_addresses|pickup_addresses|other_addresses). Default: other_addresses. 		company_addresses

Response

200 OK 

{
    "content": {
        "id": 1122341,
        "name": "Your company addresses",
        "type": "company_addresses"
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Address Group)
Name Example Value
id (integer)
The group id 		1122341
name (string)
Name of the address group 		Your company addresses
type (string)
Type of the address group (company_addresses|shipping_addresses|pickup_addresses|other_addresses) 		company_addresses
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Modify

Update the address group identified by id field from the request uri.

Action

[PUT] /addresses/groups/{id}

Request

PUT /addresses/groups/{id} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "name": "Your company addresses",
    "type": "company_addresses"
}

Details

Name Example Value
name (string)
Name of the address group 		Your company addresses
type (string)
Type of the address group (company_addresses|shipping_addresses|pickup_addresses|other_addresses). Default: other_addresses. 		company_addresses

Response

200 OK 

{
    "content": {
        "id": 1122341,
        "name": "Your company addresses",
        "type": "company_addresses"
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Address Group)
Name Example Value
id (integer)
The group id 		1122341
name (string)
Name of the address group 		Your company addresses
type (string)
Type of the address group (company_addresses|shipping_addresses|pickup_addresses|other_addresses) 		company_addresses
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Delete

Delete the address group identified by id field from the request uri (Note: groups that contain transaction addresses of a company cannot be deleted).

Action

[DELETE] /addresses/groups/{id}

Request

DELETE /addresses/groups/{id} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json

Response

204 NO CONTENT

Location

This resource allows to get information about access points

List

Get list of locations

Action

[GET] /locations

URI Parameters

Parameter Value Description
courier ups Filter by the courier. Options are ups|fedex
limit 5 Filter by number of locations
distance 6.48 Filter by radius. Units : KM
address Yobain 14 The address for nearby locations
city Mexico City City for above mentioned address
postal_code 14200 Postal code for the address
state CDMX State or province for the address
country MX Country for the address

Request

GET /locations HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK 

{
    "content": {
        "content": [
            {
                "courier": "ups",
                "location_id": "151160",
                "location_number": "U33773754",
                "latitude": "19.29207038",
                "longitude": "-99.2164306",
                "name": "MASPC MX",
                "address": "PICACHO AJUSCO 508\\n\\nPADIERNA",
                "postal_code": "14200",
                "city": "CDMX",
                "state": "CIUDAD DE MEXICO",
                "country": "MX",
                "phone": "N\/A",
                "distance": "0.9",
                "opening_hours": {
                    "Monday": [
                        {
                            "day": "Monday",
                            "hours": "09:00-16:00"
                        },
                        "..."
                    ]
                }
            },
            "..."
        ]
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Location List)
Name Example Value
content (array)
Array with the requested locations
Name Example Value
courier (string)
Courier 		ups
location_id (string)
Id of the location 		151160
location_number (string)
Loctation number 		U33773754
latitude (string)
Latitude of the location 		19.29207038
longitude (string)
Longitude of the location 		-99.2164306
name (string)
Location Name 		MASPC MX
address (string)
Location address 		PICACHO AJUSCO 508\n\nPADIERNA
postal_code (string)
Postal code of location 		14200
city (string)
City 		CDMX
state (string)
State/Province 		CIUDAD DE MEXICO
country (string)
Country 		MX
phone (string)
Location phone number 		N/A
distance (string)
Location distance from provided address in KM 		0.9
opening_hours (Location Opening Hours)
Location opening hours
Name Example Value
Monday (array)
Day of Week
Name Example Value
day (string)
Day of week 		Monday
hours (string)
Opening hours 		09:00-16:00
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Logistics

This resource allows to create, modify and confirm an order, search carriers rates for the specified order or quote

Read an order

Read the order identified by id field from the request uri

Action

[GET] /v2/logistics/orders/{order_id}

URI Parameters

Parameter Value Description
order_id 1234567 The order ID

Request

GET /v2/logistics/orders/{order_id} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK 

{
    "content": {
        "id": 1234567,
        "company_id": 7654321,
        "status": "arrived at destination terminal",
        "purchase_order": "ABC-EFGH-12-34",
        "quote_options": {
            "insurance": {
                "value": 123.45,
                "toggle": "false",
                "commodity": "Wire decking"
            },
            "limited_access": {
                "pickup_toggle": "true",
                "pickup_message": "",
                "delivery_toggle": "true",
                "delivery_message": ""
            },
            "dangerous_goods": {
                "un": "UN3480",
                "class": 8,
                "toggle": "false",
                "commodity": "Sodium Hydroxide Solution",
                "packaging_group": "II"
            },
            "appointment_delivery": "false",
            "blind_pickup": "false",
            "blind_delivery": "false",
            "heated_service": "false",
            "inside_pickup": "false",
            "inside_delivery": "true",
            "tailgate_pickup": "false",
            "tailgate_delivery": "true",
            "residential_pickup": "true",
            "residential_delivery": "false",
            "small_truck_pickup": "false",
            "small_truck_delivery": "true",
            "show_freight": "false",
            "storage_facility_pickup": "true",
            "storage_facility_delivery": "true",
            "team_drivers": "false",
            "weekend_pickup": "false",
            "weekend_delivery": "false"
        },
        "stops": [
            {
                "id": 1234567,
                "type": "pickup",
                "pickup_date": "2023-11-01",
                "pickup_from_time": "09:00",
                "pickup_until_time": "16:00",
                "delivery_date": "2023-11-17",
                "delivery_from_time": "08:00",
                "delivery_until_time": "17:00",
                "name": "ACME inc.",
                "attn": "Bob",
                "address": "123 Main Street",
                "suite": "227",
                "department": "Reception",
                "city": "Montreal",
                "country": "CA",
                "state": "QC",
                "postal_code": "A1B2C3",
                "phone": "866-320-8383",
                "phone_ext": "123",
                "is_commercial": "true",
                "address_id": 123457,
                "instruction": "Residential Delivery. Appointment Delivery. Tailgate",
                "freight_description": "Pallet of paper",
                "items": [
                    {
                        "id": 1234567,
                        "stop_id": 1234567,
                        "type": "Bags",
                        "width": 48,
                        "height": 48,
                        "length": 48,
                        "weight": 2,
                        "units": "imperial",
                        "quantity": 2
                    },
                    "..."
                ]
            },
            "..."
        ],
        "carriers": [
            {
                "id": 1234567,
                "carrier_id": 7654321,
                "has_insurance": "false"
            },
            "..."
        ],
        "charges": [
            {
                "type": "service",
                "amount": "5.00"
            },
            "..."
        ]
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Order)
The Order
Name Example Value
id (integer)
order ID 		1234567
company_id (integer)
Company ID 		7654321
status (enum)
Order status. Options are arrived at destination terminal|cancelled|claim|delayed|delivered|in bond|in storage|in transit|invoiced|no charge|on hold|out for delivery|picked up|preordered|quoted|rate discrepancy|ready to invoice|rfq|scheduled for delivery|scheduled for pickup|tbd quoted|tbd|user-confirmed|warehousing 		arrived at destination terminal|cancelled|claim|delayed|delivered|in bond|in storage|in transit|invoiced|no charge|on hold|out for delivery|picked up|preordered|quoted|rate discrepancy|ready to invoice|rfq|scheduled for delivery|scheduled for pickup|tbd quoted|tbd|user-confirmed|warehousing
purchase_order (string)
Purchase Order Number 		ABC-EFGH-12-34
quote_options (Quote Options)
Quote Options
Name Example Value
insurance (Insurance Option)
Insurance
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
toggle (boolean)
Whether the insurance option is toggled 		false
commodity (string)
Insurance commodity 		Wire decking
limited_access (Limited Access Option)
Limited Access
Name Example Value
pickup_toggle (boolean)
Whether Limited Access pickup option is toggled 		true
pickup_message (string)
Pickup Limited Access note or message
delivery_toggle (boolean)
Whether Limited Access delivery option is toggled 		true
delivery_message (string)
Delivery Limited Access note or message
dangerous_goods (Dangerous Goods Option)
Dangerous Goods
Name Example Value
un (string)
The UN number or United Nations number that identifies the good. 		UN3480
class (number)
The Dangerous Goods class number. 		8
toggle (boolean)
Whether Dangerous Goods option is toggled 		false
commodity (string)
The good being shipped 		Sodium Hydroxide Solution
packaging_group (string)
The Packaging Group. Options are I|II|III which stands for High danger, Medium danger or Low danger. 		II
appointment_delivery (boolean)
Appointment Delivery 		false
blind_pickup (boolean)
Blind Pickup 		false
blind_delivery (boolean)
Blind Delivery 		false
heated_service (boolean)
Heated service 		false
inside_pickup (boolean)
Inside Pickup 		false
inside_delivery (boolean)
Inside Delivery 		true
tailgate_pickup (boolean)
Tailgate Pickup 		false
tailgate_delivery (boolean)
Tailgate Delivery 		true
residential_pickup (boolean)
Residential Pickup 		true
residential_delivery (boolean)
Residential Delivery 		false
small_truck_pickup (boolean)
Small Truck Pickup 		false
small_truck_delivery (boolean)
Small Truck Delivery 		true
show_freight (boolean)
Show Freight 		false
storage_facility_pickup (boolean)
Public Storage Facility Pickup 		true
storage_facility_delivery (boolean)
Public Storage Facility Delivery 		true
team_drivers (boolean)
Driver Assist 		false
weekend_pickup (boolean)
Weekend Pickup 		false
weekend_delivery (boolean)
Weekend Delivery 		false
stops (array)
Pickup and Delivery
Name Example Value
id (integer)
The Order Address ID 		1234567
type (enum)
The stop type. Options are pickup|switch|delivery 		pickup|switch|delivery
pickup_date (date)
Pickup date 		2023-11-01
pickup_from_time (time)
Time from when the pickup should be done 		09:00
pickup_until_time (time)
Time until when the pickup should be done 		16:00
delivery_date (date)
Delivery date 		2023-11-17
delivery_from_time (time)
Time from when the delivery should be done 		08:00
delivery_until_time (time)
Time until when the delivery should be done 		17:00
name (string)
Stop name 		ACME inc.
attn (string)
The attn name 		Bob
address (string)
Delivery or Pickup address 		123 Main Street
suite (string)
The unit or office number 		227
department (string)
Company or organization department 		Reception
city (string)
The city 		Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1B2C3
phone (string)
866-320-8383
phone_ext (number)
123
is_commercial (boolean)
Is the address entered a commercial address? true by default 		true
address_id (integer)
The address ID, when taken from the address book 		123457
instruction (string)
Pickup or Delivery instructions 		Residential Delivery. Appointment Delivery. Tailgate
freight_description (string)
Freight Description 		Pallet of paper
items (array)
Items to be picked up or delivered to the current location
Name Example Value
id (integer)
The Item ID 		1234567
stop_id (integer)
The Stop ID 		1234567
type (enum)
The item type. 		Bags|Bales|Barrels|Boxes|Bundles|Cartons|Crates|Drums|Pallets|Pieces|skids|Skids|Totes
width (integer)
Width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
height (integer)
Height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
length (integer)
Length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
weight (integer)
Weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		2
units (enum)
The width, height, length and weight Unit Measurement System. Options are imperial|metric 		imperial|metric
quantity (integer)
The number of items 		2
carriers (array)
Order carriers
Name Example Value
id (integer)
The transit operation ID 		1234567
carrier_id (integer)
The carrier ID 		7654321
has_insurance (boolean)
True if the carrier has an insurance 		false
charges (array)
Order charges
Name Example Value
type (enum)
Type of charge 		service|...
amount (number)
Charge amount 		5.00
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

List orders

List all orders that match the request of the user.

Action

[GET] /v2/logistics/orders

URI Parameters

Parameter Value Description
id 1234567 order ID
purchase_order 7654321-CBA-321 Purchase order
status delivered Order status. Options are arrived at destination terminal|cancelled|claim|delayed|delivered|in bond|in storage|in transit|invoiced|no charge|on hold|out for delivery|picked up|preordered|quoted|rate discrepancy|ready to invoice|rfq|scheduled for delivery|scheduled for pickup|tbd quoted|tbd|user-confirmed|warehousing
from_name ACME inc. Pickup address name.
from_postal_code A1A1A1 Pickup postal code.
from_state QC Pickup state or province.
to_name ACME inc. Delivery address name.
to_postal_code A1A1A1 Delivery postal code.
to_state QC Delivery state or province.
page 2 Pagination page number
limit 2 Number of orders per page. It should range between 1 and 50

Request

GET /v2/logistics/orders HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc

Response

200 OK 

{
    "content": [
        {
            "records": [
                {
                    "id": 1234567,
                    "company_id": 7654321,
                    "status": "arrived at destination terminal",
                    "purchase_order": "ABC-EFGH-12-34",
                    "quote_options": {
                        "insurance": {
                            "value": 123.45,
                            "toggle": "false",
                            "commodity": "Wire decking"
                        },
                        "limited_access": {
                            "pickup_toggle": "true",
                            "pickup_message": "",
                            "delivery_toggle": "true",
                            "delivery_message": ""
                        },
                        "dangerous_goods": {
                            "un": "UN3480",
                            "class": 8,
                            "toggle": "false",
                            "commodity": "Sodium Hydroxide Solution",
                            "packaging_group": "II"
                        },
                        "appointment_delivery": "false",
                        "blind_pickup": "false",
                        "blind_delivery": "false",
                        "heated_service": "false",
                        "inside_pickup": "false",
                        "inside_delivery": "true",
                        "tailgate_pickup": "false",
                        "tailgate_delivery": "true",
                        "residential_pickup": "true",
                        "residential_delivery": "false",
                        "small_truck_pickup": "false",
                        "small_truck_delivery": "true",
                        "show_freight": "false",
                        "storage_facility_pickup": "true",
                        "storage_facility_delivery": "true",
                        "team_drivers": "false",
                        "weekend_pickup": "false",
                        "weekend_delivery": "false"
                    },
                    "stops": [
                        {
                            "id": 1234567,
                            "type": "pickup",
                            "pickup_date": "2023-11-01",
                            "pickup_from_time": "09:00",
                            "pickup_until_time": "16:00",
                            "delivery_date": "2023-11-17",
                            "delivery_from_time": "08:00",
                            "delivery_until_time": "17:00",
                            "name": "ACME inc.",
                            "attn": "Bob",
                            "address": "123 Main Street",
                            "suite": "227",
                            "department": "Reception",
                            "city": "Montreal",
                            "country": "CA",
                            "state": "QC",
                            "postal_code": "A1B2C3",
                            "phone": "866-320-8383",
                            "phone_ext": "123",
                            "is_commercial": "true",
                            "address_id": 123457,
                            "instruction": "Residential Delivery. Appointment Delivery. Tailgate",
                            "freight_description": "Pallet of paper",
                            "items": [
                                {
                                    "id": 1234567,
                                    "stop_id": 1234567,
                                    "type": "Bags",
                                    "width": 48,
                                    "height": 48,
                                    "length": 48,
                                    "weight": 2,
                                    "units": "imperial",
                                    "quantity": 2
                                },
                                "..."
                            ]
                        },
                        "..."
                    ],
                    "carriers": [
                        {
                            "id": 1234567,
                            "carrier_id": 7654321,
                            "has_insurance": "false"
                        },
                        "..."
                    ],
                    "charges": [
                        {
                            "type": "service",
                            "amount": "5.00"
                        },
                        "..."
                    ]
                },
                "..."
            ],
            "current_page": 2,
            "max_per_page": 20,
            "nb_of_pages": 7,
            "nb_of_records": 131
        },
        "..."
    ],
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (array)
All orders
Name Example Value
records (array)
Array with the orders belonging to the requested page.
Name Example Value
id (integer)
order ID 		1234567
company_id (integer)
Company ID 		7654321
status (enum)
Order status. Options are arrived at destination terminal|cancelled|claim|delayed|delivered|in bond|in storage|in transit|invoiced|no charge|on hold|out for delivery|picked up|preordered|quoted|rate discrepancy|ready to invoice|rfq|scheduled for delivery|scheduled for pickup|tbd quoted|tbd|user-confirmed|warehousing 		arrived at destination terminal|cancelled|claim|delayed|delivered|in bond|in storage|in transit|invoiced|no charge|on hold|out for delivery|picked up|preordered|quoted|rate discrepancy|ready to invoice|rfq|scheduled for delivery|scheduled for pickup|tbd quoted|tbd|user-confirmed|warehousing
purchase_order (string)
Purchase Order Number 		ABC-EFGH-12-34
quote_options (Quote Options)
Quote Options
Name Example Value
insurance (Insurance Option)
Insurance
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
toggle (boolean)
Whether the insurance option is toggled 		false
commodity (string)
Insurance commodity 		Wire decking
limited_access (Limited Access Option)
Limited Access
Name Example Value
pickup_toggle (boolean)
Whether Limited Access pickup option is toggled 		true
pickup_message (string)
Pickup Limited Access note or message
delivery_toggle (boolean)
Whether Limited Access delivery option is toggled 		true
delivery_message (string)
Delivery Limited Access note or message
dangerous_goods (Dangerous Goods Option)
Dangerous Goods
Name Example Value
un (string)
The UN number or United Nations number that identifies the good. 		UN3480
class (number)
The Dangerous Goods class number. 		8
toggle (boolean)
Whether Dangerous Goods option is toggled 		false
commodity (string)
The good being shipped 		Sodium Hydroxide Solution
packaging_group (string)
The Packaging Group. Options are I|II|III which stands for High danger, Medium danger or Low danger. 		II
appointment_delivery (boolean)
Appointment Delivery 		false
blind_pickup (boolean)
Blind Pickup 		false
blind_delivery (boolean)
Blind Delivery 		false
heated_service (boolean)
Heated service 		false
inside_pickup (boolean)
Inside Pickup 		false
inside_delivery (boolean)
Inside Delivery 		true
tailgate_pickup (boolean)
Tailgate Pickup 		false
tailgate_delivery (boolean)
Tailgate Delivery 		true
residential_pickup (boolean)
Residential Pickup 		true
residential_delivery (boolean)
Residential Delivery 		false
small_truck_pickup (boolean)
Small Truck Pickup 		false
small_truck_delivery (boolean)
Small Truck Delivery 		true
show_freight (boolean)
Show Freight 		false
storage_facility_pickup (boolean)
Public Storage Facility Pickup 		true
storage_facility_delivery (boolean)
Public Storage Facility Delivery 		true
team_drivers (boolean)
Driver Assist 		false
weekend_pickup (boolean)
Weekend Pickup 		false
weekend_delivery (boolean)
Weekend Delivery 		false
stops (array)
Pickup and Delivery
Name Example Value
id (integer)
The Order Address ID 		1234567
type (enum)
The stop type. Options are pickup|switch|delivery 		pickup|switch|delivery
pickup_date (date)
Pickup date 		2023-11-01
pickup_from_time (time)
Time from when the pickup should be done 		09:00
pickup_until_time (time)
Time until when the pickup should be done 		16:00
delivery_date (date)
Delivery date 		2023-11-17
delivery_from_time (time)
Time from when the delivery should be done 		08:00
delivery_until_time (time)
Time until when the delivery should be done 		17:00
name (string)
Stop name 		ACME inc.
attn (string)
The attn name 		Bob
address (string)
Delivery or Pickup address 		123 Main Street
suite (string)
The unit or office number 		227
department (string)
Company or organization department 		Reception
city (string)
The city 		Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1B2C3
phone (string)
866-320-8383
phone_ext (number)
123
is_commercial (boolean)
Is the address entered a commercial address? true by default 		true
address_id (integer)
The address ID, when taken from the address book 		123457
instruction (string)
Pickup or Delivery instructions 		Residential Delivery. Appointment Delivery. Tailgate
freight_description (string)
Freight Description 		Pallet of paper
items (array)
Items to be picked up or delivered to the current location
Name Example Value
id (integer)
The Item ID 		1234567
stop_id (integer)
The Stop ID 		1234567
type (enum)
The item type. 		Bags|Bales|Barrels|Boxes|Bundles|Cartons|Crates|Drums|Pallets|Pieces|skids|Skids|Totes
width (integer)
Width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
height (integer)
Height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
length (integer)
Length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
weight (integer)
Weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		2
units (enum)
The width, height, length and weight Unit Measurement System. Options are imperial|metric 		imperial|metric
quantity (integer)
The number of items 		2
carriers (array)
Order carriers
Name Example Value
id (integer)
The transit operation ID 		1234567
carrier_id (integer)
The carrier ID 		7654321
has_insurance (boolean)
True if the carrier has an insurance 		false
charges (array)
Order charges
Name Example Value
type (enum)
Type of charge 		service|...
amount (number)
Charge amount 		5.00
current_page (integer)
The page the returned records belong to 		2
max_per_page (integer)
The results per page 		20
nb_of_pages (integer)
The number of pages necessary to show all the list elements 		7
nb_of_records (integer)
The total number of records found 		131
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Create an Order

Creates a logistics order record in the database, in a "tbd" status. Can subsequently be used to be confirmed with "Confirm By id" function.

Action

[POST] /v2/logistics/orders

Request

POST /v2/logistics/orders HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "purchase_order": "7654321-CBA-321",
    "pickup": {
        "name": "ACME inc.",
        "attn": "Bob",
        "date": "2023-11-01",
        "from_time": "09:00",
        "until_time": "16:00",
        "address": "123 Main Street",
        "suite": "227",
        "department": "Reception",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1B2C3",
        "phone": "866-320-8383",
        "phone_ext": "123",
        "is_commercial": "true",
        "special_instruction": "Residential Pickup. Appointment Delivery. Tailgate",
        "freight_description": "Pallet of paper",
        "items": [
            {
                "quantity": 2,
                "width": 48,
                "height": 48,
                "length": 48,
                "weight": 2,
                "units": "imperial",
                "type": "Bags"
            },
            "..."
        ]
    },
    "delivery": {
        "name": "ACME inc.",
        "attn": "Bob",
        "date": "2023-11-01",
        "from_time": "09:00",
        "until_time": "16:00",
        "address": "123 Main Street",
        "suite": "227",
        "department": "Reception",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "866-320-8383",
        "phone_ext": "123",
        "is_commercial": "true",
        "special_instruction": "Residential Delivery. Appointment Delivery. Tailgate",
        "freight_description": "Pallet of paper",
        "items": [
            {
                "quantity": 2,
                "width": 48,
                "height": 48,
                "length": 48,
                "weight": 2,
                "units": "imperial",
                "type": "Bags"
            },
            "..."
        ]
    },
    "shipment_info": {
        "shipment_type": "LTL",
        "container_type": "20ft",
        "truck_type": "24 foot Straight Truck",
        "truck_details": "Tailgate, Frozen"
    },
    "options": {
        "insurance": {
            "value": 123.45,
            "toggle": "false",
            "commodity": "Wire decking"
        },
        "limited_access": {
            "pickup_toggle": "true",
            "pickup_message": "",
            "delivery_toggle": "true",
            "delivery_message": ""
        },
        "dangerous_goods": {
            "un": "UN3480",
            "class": 8,
            "toggle": "false",
            "commodity": "Sodium Hydroxide Solution",
            "packaging_group": "II"
        },
        "appointment_delivery": "false",
        "blind_pickup": "false",
        "blind_delivery": "false",
        "heated_service": "false",
        "inside_pickup": "false",
        "inside_delivery": "true",
        "tailgate_pickup": "false",
        "tailgate_delivery": "true",
        "residential_pickup": "true",
        "residential_delivery": "false",
        "small_truck_pickup": "false",
        "small_truck_delivery": "true",
        "show_freight": "false",
        "storage_facility_pickup": "true",
        "storage_facility_delivery": "true",
        "team_drivers": "false",
        "weekend_pickup": "false",
        "weekend_delivery": "false"
    }
}

Details

Name Example Value
purchase_order (string)
Purchase order 		7654321-CBA-321
pickup (Order Pickup)
Pickup specification, including pickup address and items to be shipped.
Name Example Value
name (string)
Pickup name 		ACME inc.
attn (string)
Attn name 		Bob
date (date)
Pickup date. Can be YYYY-MM-DD. Should be greater or eqal to the current date and not greater than Delivery Date. 		2023-11-01
from_time (time)
Time from when the pickup should be done. In 24h format hh:mm. 		09:00
until_time (time)
Time until when the pickup should be done. In 24h format hh:mm. 		16:00
address (string)
Pickup address 		123 Main Street
suite (string)
The unit or office number 		227
department (string)
Company or organization department 		Reception
city (string)
Pickup city 		Montreal
country (string)
Pickup country. ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
Pickup state or province. ISO 3166-1 alpha-2 two letter state if applicable in the country. 		QC
postal_code (string)
Pickup postal code. 		A1B2C3
phone (string)
866-320-8383
phone_ext (number)
123
is_commercial (boolean)
Is the address entered a commercial address? true by default 		true
special_instruction (string)
Pickup instructions 		Residential Pickup. Appointment Delivery. Tailgate
freight_description (string)
Freight Description 		Pallet of paper
items (array)
Items to be picked up
Name Example Value
quantity (integer)
The number of items 		2
width (integer)
Width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
height (integer)
Height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
length (integer)
Length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
weight (integer)
Weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		2
units (enum)
Width, height, length and weight Unit System. Options are imperial|metric. 		imperial|metric
type (enum)
The item type 		Bags|Bales|Barrels|Boxes|Bundles|Cartons|Crates|Drums|Pallets|Pieces|skids|Skids|Totes
delivery (Order Delivery)
Delivery specification, including delivery address and items to be shipped.
Name Example Value
name (string)
Delivery name 		ACME inc.
attn (string)
The attn name 		Bob
date (date)
Delivery date. Can be YYYY-MM-DD. Should be greater or eqal to the Pickup Date. 		2023-11-01
from_time (time)
Time from when delivery should be done. In 24h format hh:mm. 		09:00
until_time (time)
Time until when delivery should be done. In 24h format hh:mm. 		16:00
address (string)
Delivery address 		123 Main Street
suite (string)
The unit or office number 		227
department (string)
Company or organization department 		Reception
city (string)
Delivery city 		Montreal
country (string)
Delivery country. ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
Delivery state or province. ISO 3166-1 alpha-2 two letter state if applicable in the country. 		QC
postal_code (string)
Delivery postal code. 		A1A1A1
phone (string)
866-320-8383
phone_ext (number)
123
is_commercial (boolean)
Is the address entered a commercial address? true by default 		true
special_instruction (string)
Delivery instructions 		Residential Delivery. Appointment Delivery. Tailgate
freight_description (string)
Freight Description 		Pallet of paper
items (array)
Items to be delivered
Name Example Value
quantity (integer)
The number of items 		2
width (integer)
Width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
height (integer)
Height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
length (integer)
Length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
weight (integer)
Weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		2
units (enum)
Width, height, length and weight Unit System. Options are imperial|metric. 		imperial|metric
type (enum)
The item type 		Bags|Bales|Barrels|Boxes|Bundles|Cartons|Crates|Drums|Pallets|Pieces|skids|Skids|Totes
shipment_info (Shipment Specification)
Shipment specification, including shipment type, container type, truck type and truck details.
Name Example Value
shipment_type (enum)
Shipment type 		LTL|FTL|CL|LTL
container_type (enum)
Container type 		20ft|40ft
truck_type (enum)
Truck type 		24 foot Straight Truck|53 foot Dry Van|Cargo Van|Cube Truck|Flat Bed|Refrigerated|Sprinter Van
truck_details (string)
Truck details 		Tailgate, Frozen
options (Quote Options)
Quote options. None of the options are required.
Name Example Value
insurance (Insurance Option)
Insurance
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
toggle (boolean)
Whether the insurance option is toggled 		false
commodity (string)
Insurance commodity 		Wire decking
limited_access (Limited Access Option)
Limited Access
Name Example Value
pickup_toggle (boolean)
Whether Limited Access pickup option is toggled 		true
pickup_message (string)
Pickup Limited Access note or message
delivery_toggle (boolean)
Whether Limited Access delivery option is toggled 		true
delivery_message (string)
Delivery Limited Access note or message
dangerous_goods (Dangerous Goods Option)
Dangerous Goods
Name Example Value
un (string)
The UN number or United Nations number that identifies the good. 		UN3480
class (number)
The Dangerous Goods class number. 		8
toggle (boolean)
Whether Dangerous Goods option is toggled 		false
commodity (string)
The good being shipped 		Sodium Hydroxide Solution
packaging_group (string)
The Packaging Group. Options are I|II|III which stands for High danger, Medium danger or Low danger. 		II
appointment_delivery (boolean)
Appointment Delivery 		false
blind_pickup (boolean)
Blind Pickup 		false
blind_delivery (boolean)
Blind Delivery 		false
heated_service (boolean)
Heated service 		false
inside_pickup (boolean)
Inside Pickup 		false
inside_delivery (boolean)
Inside Delivery 		true
tailgate_pickup (boolean)
Tailgate Pickup 		false
tailgate_delivery (boolean)
Tailgate Delivery 		true
residential_pickup (boolean)
Residential Pickup 		true
residential_delivery (boolean)
Residential Delivery 		false
small_truck_pickup (boolean)
Small Truck Pickup 		false
small_truck_delivery (boolean)
Small Truck Delivery 		true
show_freight (boolean)
Show Freight 		false
storage_facility_pickup (boolean)
Public Storage Facility Pickup 		true
storage_facility_delivery (boolean)
Public Storage Facility Delivery 		true
team_drivers (boolean)
Driver Assist 		false
weekend_pickup (boolean)
Weekend Pickup 		false
weekend_delivery (boolean)
Weekend Delivery 		false

Response

200 OK 

{
    "content": {
        "id": 1234567,
        "company_id": 7654321,
        "status": "arrived at destination terminal",
        "purchase_order": "ABC-EFGH-12-34",
        "quote_options": {
            "insurance": {
                "value": 123.45,
                "toggle": "false",
                "commodity": "Wire decking"
            },
            "limited_access": {
                "pickup_toggle": "true",
                "pickup_message": "",
                "delivery_toggle": "true",
                "delivery_message": ""
            },
            "dangerous_goods": {
                "un": "UN3480",
                "class": 8,
                "toggle": "false",
                "commodity": "Sodium Hydroxide Solution",
                "packaging_group": "II"
            },
            "appointment_delivery": "false",
            "blind_pickup": "false",
            "blind_delivery": "false",
            "heated_service": "false",
            "inside_pickup": "false",
            "inside_delivery": "true",
            "tailgate_pickup": "false",
            "tailgate_delivery": "true",
            "residential_pickup": "true",
            "residential_delivery": "false",
            "small_truck_pickup": "false",
            "small_truck_delivery": "true",
            "show_freight": "false",
            "storage_facility_pickup": "true",
            "storage_facility_delivery": "true",
            "team_drivers": "false",
            "weekend_pickup": "false",
            "weekend_delivery": "false"
        },
        "stops": [
            {
                "id": 1234567,
                "type": "pickup",
                "pickup_date": "2023-11-01",
                "pickup_from_time": "09:00",
                "pickup_until_time": "16:00",
                "delivery_date": "2023-11-17",
                "delivery_from_time": "08:00",
                "delivery_until_time": "17:00",
                "name": "ACME inc.",
                "attn": "Bob",
                "address": "123 Main Street",
                "suite": "227",
                "department": "Reception",
                "city": "Montreal",
                "country": "CA",
                "state": "QC",
                "postal_code": "A1B2C3",
                "phone": "866-320-8383",
                "phone_ext": "123",
                "is_commercial": "true",
                "address_id": 123457,
                "instruction": "Residential Delivery. Appointment Delivery. Tailgate",
                "freight_description": "Pallet of paper",
                "items": [
                    {
                        "id": 1234567,
                        "stop_id": 1234567,
                        "type": "Bags",
                        "width": 48,
                        "height": 48,
                        "length": 48,
                        "weight": 2,
                        "units": "imperial",
                        "quantity": 2
                    },
                    "..."
                ]
            },
            "..."
        ],
        "carriers": [
            {
                "id": 1234567,
                "carrier_id": 7654321,
                "has_insurance": "false"
            },
            "..."
        ],
        "charges": [
            {
                "type": "service",
                "amount": "5.00"
            },
            "..."
        ]
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Order)
The Order to be created
Name Example Value
id (integer)
order ID 		1234567
company_id (integer)
Company ID 		7654321
status (enum)
Order status. Options are arrived at destination terminal|cancelled|claim|delayed|delivered|in bond|in storage|in transit|invoiced|no charge|on hold|out for delivery|picked up|preordered|quoted|rate discrepancy|ready to invoice|rfq|scheduled for delivery|scheduled for pickup|tbd quoted|tbd|user-confirmed|warehousing 		arrived at destination terminal|cancelled|claim|delayed|delivered|in bond|in storage|in transit|invoiced|no charge|on hold|out for delivery|picked up|preordered|quoted|rate discrepancy|ready to invoice|rfq|scheduled for delivery|scheduled for pickup|tbd quoted|tbd|user-confirmed|warehousing
purchase_order (string)
Purchase Order Number 		ABC-EFGH-12-34
quote_options (Quote Options)
Quote Options
Name Example Value
insurance (Insurance Option)
Insurance
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
toggle (boolean)
Whether the insurance option is toggled 		false
commodity (string)
Insurance commodity 		Wire decking
limited_access (Limited Access Option)
Limited Access
Name Example Value
pickup_toggle (boolean)
Whether Limited Access pickup option is toggled 		true
pickup_message (string)
Pickup Limited Access note or message
delivery_toggle (boolean)
Whether Limited Access delivery option is toggled 		true
delivery_message (string)
Delivery Limited Access note or message
dangerous_goods (Dangerous Goods Option)
Dangerous Goods
Name Example Value
un (string)
The UN number or United Nations number that identifies the good. 		UN3480
class (number)
The Dangerous Goods class number. 		8
toggle (boolean)
Whether Dangerous Goods option is toggled 		false
commodity (string)
The good being shipped 		Sodium Hydroxide Solution
packaging_group (string)
The Packaging Group. Options are I|II|III which stands for High danger, Medium danger or Low danger. 		II
appointment_delivery (boolean)
Appointment Delivery 		false
blind_pickup (boolean)
Blind Pickup 		false
blind_delivery (boolean)
Blind Delivery 		false
heated_service (boolean)
Heated service 		false
inside_pickup (boolean)
Inside Pickup 		false
inside_delivery (boolean)
Inside Delivery 		true
tailgate_pickup (boolean)
Tailgate Pickup 		false
tailgate_delivery (boolean)
Tailgate Delivery 		true
residential_pickup (boolean)
Residential Pickup 		true
residential_delivery (boolean)
Residential Delivery 		false
small_truck_pickup (boolean)
Small Truck Pickup 		false
small_truck_delivery (boolean)
Small Truck Delivery 		true
show_freight (boolean)
Show Freight 		false
storage_facility_pickup (boolean)
Public Storage Facility Pickup 		true
storage_facility_delivery (boolean)
Public Storage Facility Delivery 		true
team_drivers (boolean)
Driver Assist 		false
weekend_pickup (boolean)
Weekend Pickup 		false
weekend_delivery (boolean)
Weekend Delivery 		false
stops (array)
Pickup and Delivery
Name Example Value
id (integer)
The Order Address ID 		1234567
type (enum)
The stop type. Options are pickup|switch|delivery 		pickup|switch|delivery
pickup_date (date)
Pickup date 		2023-11-01
pickup_from_time (time)
Time from when the pickup should be done 		09:00
pickup_until_time (time)
Time until when the pickup should be done 		16:00
delivery_date (date)
Delivery date 		2023-11-17
delivery_from_time (time)
Time from when the delivery should be done 		08:00
delivery_until_time (time)
Time until when the delivery should be done 		17:00
name (string)
Stop name 		ACME inc.
attn (string)
The attn name 		Bob
address (string)
Delivery or Pickup address 		123 Main Street
suite (string)
The unit or office number 		227
department (string)
Company or organization department 		Reception
city (string)
The city 		Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1B2C3
phone (string)
866-320-8383
phone_ext (number)
123
is_commercial (boolean)
Is the address entered a commercial address? true by default 		true
address_id (integer)
The address ID, when taken from the address book 		123457
instruction (string)
Pickup or Delivery instructions 		Residential Delivery. Appointment Delivery. Tailgate
freight_description (string)
Freight Description 		Pallet of paper
items (array)
Items to be picked up or delivered to the current location
Name Example Value
id (integer)
The Item ID 		1234567
stop_id (integer)
The Stop ID 		1234567
type (enum)
The item type. 		Bags|Bales|Barrels|Boxes|Bundles|Cartons|Crates|Drums|Pallets|Pieces|skids|Skids|Totes
width (integer)
Width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
height (integer)
Height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
length (integer)
Length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
weight (integer)
Weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		2
units (enum)
The width, height, length and weight Unit Measurement System. Options are imperial|metric 		imperial|metric
quantity (integer)
The number of items 		2
carriers (array)
Order carriers
Name Example Value
id (integer)
The transit operation ID 		1234567
carrier_id (integer)
The carrier ID 		7654321
has_insurance (boolean)
True if the carrier has an insurance 		false
charges (array)
Order charges
Name Example Value
type (enum)
Type of charge 		service|...
amount (number)
Charge amount 		5.00
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Modify an Order

Update an order identified by id field from the request uri

Action

[PUT] /v2/logistics/orders/{orderId}

URI Parameters

Parameter Value Description
order_id 1234567 The order ID

Request

PUT /v2/logistics/orders/{orderId} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "purchase_order": "ACME inc.",
    "pickup": {
        "name": "ACME inc.",
        "attn": "Bob",
        "date": "2023-11-01",
        "from_time": "09:00",
        "until_time": "16:00",
        "address": "123 Main Street",
        "suite": "227",
        "department": "Reception",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1B2C3",
        "phone": "866-320-8383",
        "phone_ext": "123",
        "is_commercial": "true",
        "special_instruction": "Residential Pickup. Appointment Delivery. Tailgate",
        "freight_description": "Pallet of paper",
        "items": [
            {
                "quantity": 2,
                "width": 48,
                "height": 48,
                "length": 48,
                "weight": 2,
                "units": "imperial",
                "type": "Bags"
            },
            "..."
        ]
    },
    "delivery": {
        "name": "ACME inc.",
        "attn": "Bob",
        "date": "2023-11-01",
        "from_time": "09:00",
        "until_time": "16:00",
        "address": "123 Main Street",
        "suite": "227",
        "department": "Reception",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "866-320-8383",
        "phone_ext": "123",
        "is_commercial": "true",
        "special_instruction": "Residential Delivery. Appointment Delivery. Tailgate",
        "freight_description": "Pallet of paper",
        "items": [
            {
                "quantity": 2,
                "width": 48,
                "height": 48,
                "length": 48,
                "weight": 2,
                "units": "imperial",
                "type": "Bags"
            },
            "..."
        ]
    },
    "shipment_info": {
        "shipment_type": "LTL",
        "container_type": "20ft",
        "truck_type": "24 foot Straight Truck",
        "truck_details": "Tailgate, Frozen"
    },
    "options": {
        "insurance": {
            "value": 123.45,
            "toggle": "false",
            "commodity": "Wire decking"
        },
        "limited_access": {
            "pickup_toggle": "true",
            "pickup_message": "",
            "delivery_toggle": "true",
            "delivery_message": ""
        },
        "dangerous_goods": {
            "un": "UN3480",
            "class": 8,
            "toggle": "false",
            "commodity": "Sodium Hydroxide Solution",
            "packaging_group": "II"
        },
        "appointment_delivery": "false",
        "blind_pickup": "false",
        "blind_delivery": "false",
        "heated_service": "false",
        "inside_pickup": "false",
        "inside_delivery": "true",
        "tailgate_pickup": "false",
        "tailgate_delivery": "true",
        "residential_pickup": "true",
        "residential_delivery": "false",
        "small_truck_pickup": "false",
        "small_truck_delivery": "true",
        "show_freight": "false",
        "storage_facility_pickup": "true",
        "storage_facility_delivery": "true",
        "team_drivers": "false",
        "weekend_pickup": "false",
        "weekend_delivery": "false"
    }
}

Details

Name Example Value
purchase_order (string)
The purchase order 		ACME inc.
pickup (Order Pickup)
Pickup specification, including pickup address and items to be shipped.
Name Example Value
name (string)
Pickup name 		ACME inc.
attn (string)
Attn name 		Bob
date (date)
Pickup date. Can be YYYY-MM-DD. Should be greater or eqal to the current date and not greater than Delivery Date. 		2023-11-01
from_time (time)
Time from when the pickup should be done. In 24h format hh:mm. 		09:00
until_time (time)
Time until when the pickup should be done. In 24h format hh:mm. 		16:00
address (string)
Pickup address 		123 Main Street
suite (string)
The unit or office number 		227
department (string)
Company or organization department 		Reception
city (string)
Pickup city 		Montreal
country (string)
Pickup country. ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
Pickup state or province. ISO 3166-1 alpha-2 two letter state if applicable in the country. 		QC
postal_code (string)
Pickup postal code. 		A1B2C3
phone (string)
866-320-8383
phone_ext (number)
123
is_commercial (boolean)
Is the address entered a commercial address? true by default 		true
special_instruction (string)
Pickup instructions 		Residential Pickup. Appointment Delivery. Tailgate
freight_description (string)
Freight Description 		Pallet of paper
items (array)
Items to be picked up
Name Example Value
quantity (integer)
The number of items 		2
width (integer)
Width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
height (integer)
Height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
length (integer)
Length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
weight (integer)
Weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		2
units (enum)
Width, height, length and weight Unit System. Options are imperial|metric. 		imperial|metric
type (enum)
The item type 		Bags|Bales|Barrels|Boxes|Bundles|Cartons|Crates|Drums|Pallets|Pieces|skids|Skids|Totes
delivery (Order Delivery)
Delivery specification, including delivery address and items to be shipped.
Name Example Value
name (string)
Delivery name 		ACME inc.
attn (string)
The attn name 		Bob
date (date)
Delivery date. Can be YYYY-MM-DD. Should be greater or eqal to the Pickup Date. 		2023-11-01
from_time (time)
Time from when delivery should be done. In 24h format hh:mm. 		09:00
until_time (time)
Time until when delivery should be done. In 24h format hh:mm. 		16:00
address (string)
Delivery address 		123 Main Street
suite (string)
The unit or office number 		227
department (string)
Company or organization department 		Reception
city (string)
Delivery city 		Montreal
country (string)
Delivery country. ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
Delivery state or province. ISO 3166-1 alpha-2 two letter state if applicable in the country. 		QC
postal_code (string)
Delivery postal code. 		A1A1A1
phone (string)
866-320-8383
phone_ext (number)
123
is_commercial (boolean)
Is the address entered a commercial address? true by default 		true
special_instruction (string)
Delivery instructions 		Residential Delivery. Appointment Delivery. Tailgate
freight_description (string)
Freight Description 		Pallet of paper
items (array)
Items to be delivered
Name Example Value
quantity (integer)
The number of items 		2
width (integer)
Width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
height (integer)
Height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
length (integer)
Length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
weight (integer)
Weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		2
units (enum)
Width, height, length and weight Unit System. Options are imperial|metric. 		imperial|metric
type (enum)
The item type 		Bags|Bales|Barrels|Boxes|Bundles|Cartons|Crates|Drums|Pallets|Pieces|skids|Skids|Totes
shipment_info (Shipment Specification)
Shipment specification, including shipment type, container type, truck type and truck details.
Name Example Value
shipment_type (enum)
Shipment type 		LTL|FTL|CL|LTL
container_type (enum)
Container type 		20ft|40ft
truck_type (enum)
Truck type 		24 foot Straight Truck|53 foot Dry Van|Cargo Van|Cube Truck|Flat Bed|Refrigerated|Sprinter Van
truck_details (string)
Truck details 		Tailgate, Frozen
options (Quote Options)
The options for this shipment. None of the options are required.
Name Example Value
insurance (Insurance Option)
Insurance
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
toggle (boolean)
Whether the insurance option is toggled 		false
commodity (string)
Insurance commodity 		Wire decking
limited_access (Limited Access Option)
Limited Access
Name Example Value
pickup_toggle (boolean)
Whether Limited Access pickup option is toggled 		true
pickup_message (string)
Pickup Limited Access note or message
delivery_toggle (boolean)
Whether Limited Access delivery option is toggled 		true
delivery_message (string)
Delivery Limited Access note or message
dangerous_goods (Dangerous Goods Option)
Dangerous Goods
Name Example Value
un (string)
The UN number or United Nations number that identifies the good. 		UN3480
class (number)
The Dangerous Goods class number. 		8
toggle (boolean)
Whether Dangerous Goods option is toggled 		false
commodity (string)
The good being shipped 		Sodium Hydroxide Solution
packaging_group (string)
The Packaging Group. Options are I|II|III which stands for High danger, Medium danger or Low danger. 		II
appointment_delivery (boolean)
Appointment Delivery 		false
blind_pickup (boolean)
Blind Pickup 		false
blind_delivery (boolean)
Blind Delivery 		false
heated_service (boolean)
Heated service 		false
inside_pickup (boolean)
Inside Pickup 		false
inside_delivery (boolean)
Inside Delivery 		true
tailgate_pickup (boolean)
Tailgate Pickup 		false
tailgate_delivery (boolean)
Tailgate Delivery 		true
residential_pickup (boolean)
Residential Pickup 		true
residential_delivery (boolean)
Residential Delivery 		false
small_truck_pickup (boolean)
Small Truck Pickup 		false
small_truck_delivery (boolean)
Small Truck Delivery 		true
show_freight (boolean)
Show Freight 		false
storage_facility_pickup (boolean)
Public Storage Facility Pickup 		true
storage_facility_delivery (boolean)
Public Storage Facility Delivery 		true
team_drivers (boolean)
Driver Assist 		false
weekend_pickup (boolean)
Weekend Pickup 		false
weekend_delivery (boolean)
Weekend Delivery 		false

Response

200 OK 

{
    "content": {
        "id": 1234567,
        "company_id": 7654321,
        "status": "arrived at destination terminal",
        "purchase_order": "ABC-EFGH-12-34",
        "quote_options": {
            "insurance": {
                "value": 123.45,
                "toggle": "false",
                "commodity": "Wire decking"
            },
            "limited_access": {
                "pickup_toggle": "true",
                "pickup_message": "",
                "delivery_toggle": "true",
                "delivery_message": ""
            },
            "dangerous_goods": {
                "un": "UN3480",
                "class": 8,
                "toggle": "false",
                "commodity": "Sodium Hydroxide Solution",
                "packaging_group": "II"
            },
            "appointment_delivery": "false",
            "blind_pickup": "false",
            "blind_delivery": "false",
            "heated_service": "false",
            "inside_pickup": "false",
            "inside_delivery": "true",
            "tailgate_pickup": "false",
            "tailgate_delivery": "true",
            "residential_pickup": "true",
            "residential_delivery": "false",
            "small_truck_pickup": "false",
            "small_truck_delivery": "true",
            "show_freight": "false",
            "storage_facility_pickup": "true",
            "storage_facility_delivery": "true",
            "team_drivers": "false",
            "weekend_pickup": "false",
            "weekend_delivery": "false"
        },
        "stops": [
            {
                "id": 1234567,
                "type": "pickup",
                "pickup_date": "2023-11-01",
                "pickup_from_time": "09:00",
                "pickup_until_time": "16:00",
                "delivery_date": "2023-11-17",
                "delivery_from_time": "08:00",
                "delivery_until_time": "17:00",
                "name": "ACME inc.",
                "attn": "Bob",
                "address": "123 Main Street",
                "suite": "227",
                "department": "Reception",
                "city": "Montreal",
                "country": "CA",
                "state": "QC",
                "postal_code": "A1B2C3",
                "phone": "866-320-8383",
                "phone_ext": "123",
                "is_commercial": "true",
                "address_id": 123457,
                "instruction": "Residential Delivery. Appointment Delivery. Tailgate",
                "freight_description": "Pallet of paper",
                "items": [
                    {
                        "id": 1234567,
                        "stop_id": 1234567,
                        "type": "Bags",
                        "width": 48,
                        "height": 48,
                        "length": 48,
                        "weight": 2,
                        "units": "imperial",
                        "quantity": 2
                    },
                    "..."
                ]
            },
            "..."
        ],
        "carriers": [
            {
                "id": 1234567,
                "carrier_id": 7654321,
                "has_insurance": "false"
            },
            "..."
        ],
        "charges": [
            {
                "type": "service",
                "amount": "5.00"
            },
            "..."
        ]
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Order)
The Order to be modified
Name Example Value
id (integer)
order ID 		1234567
company_id (integer)
Company ID 		7654321
status (enum)
Order status. Options are arrived at destination terminal|cancelled|claim|delayed|delivered|in bond|in storage|in transit|invoiced|no charge|on hold|out for delivery|picked up|preordered|quoted|rate discrepancy|ready to invoice|rfq|scheduled for delivery|scheduled for pickup|tbd quoted|tbd|user-confirmed|warehousing 		arrived at destination terminal|cancelled|claim|delayed|delivered|in bond|in storage|in transit|invoiced|no charge|on hold|out for delivery|picked up|preordered|quoted|rate discrepancy|ready to invoice|rfq|scheduled for delivery|scheduled for pickup|tbd quoted|tbd|user-confirmed|warehousing
purchase_order (string)
Purchase Order Number 		ABC-EFGH-12-34
quote_options (Quote Options)
Quote Options
Name Example Value
insurance (Insurance Option)
Insurance
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
toggle (boolean)
Whether the insurance option is toggled 		false
commodity (string)
Insurance commodity 		Wire decking
limited_access (Limited Access Option)
Limited Access
Name Example Value
pickup_toggle (boolean)
Whether Limited Access pickup option is toggled 		true
pickup_message (string)
Pickup Limited Access note or message
delivery_toggle (boolean)
Whether Limited Access delivery option is toggled 		true
delivery_message (string)
Delivery Limited Access note or message
dangerous_goods (Dangerous Goods Option)
Dangerous Goods
Name Example Value
un (string)
The UN number or United Nations number that identifies the good. 		UN3480
class (number)
The Dangerous Goods class number. 		8
toggle (boolean)
Whether Dangerous Goods option is toggled 		false
commodity (string)
The good being shipped 		Sodium Hydroxide Solution
packaging_group (string)
The Packaging Group. Options are I|II|III which stands for High danger, Medium danger or Low danger. 		II
appointment_delivery (boolean)
Appointment Delivery 		false
blind_pickup (boolean)
Blind Pickup 		false
blind_delivery (boolean)
Blind Delivery 		false
heated_service (boolean)
Heated service 		false
inside_pickup (boolean)
Inside Pickup 		false
inside_delivery (boolean)
Inside Delivery 		true
tailgate_pickup (boolean)
Tailgate Pickup 		false
tailgate_delivery (boolean)
Tailgate Delivery 		true
residential_pickup (boolean)
Residential Pickup 		true
residential_delivery (boolean)
Residential Delivery 		false
small_truck_pickup (boolean)
Small Truck Pickup 		false
small_truck_delivery (boolean)
Small Truck Delivery 		true
show_freight (boolean)
Show Freight 		false
storage_facility_pickup (boolean)
Public Storage Facility Pickup 		true
storage_facility_delivery (boolean)
Public Storage Facility Delivery 		true
team_drivers (boolean)
Driver Assist 		false
weekend_pickup (boolean)
Weekend Pickup 		false
weekend_delivery (boolean)
Weekend Delivery 		false
stops (array)
Pickup and Delivery
Name Example Value
id (integer)
The Order Address ID 		1234567
type (enum)
The stop type. Options are pickup|switch|delivery 		pickup|switch|delivery
pickup_date (date)
Pickup date 		2023-11-01
pickup_from_time (time)
Time from when the pickup should be done 		09:00
pickup_until_time (time)
Time until when the pickup should be done 		16:00
delivery_date (date)
Delivery date 		2023-11-17
delivery_from_time (time)
Time from when the delivery should be done 		08:00
delivery_until_time (time)
Time until when the delivery should be done 		17:00
name (string)
Stop name 		ACME inc.
attn (string)
The attn name 		Bob
address (string)
Delivery or Pickup address 		123 Main Street
suite (string)
The unit or office number 		227
department (string)
Company or organization department 		Reception
city (string)
The city 		Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1B2C3
phone (string)
866-320-8383
phone_ext (number)
123
is_commercial (boolean)
Is the address entered a commercial address? true by default 		true
address_id (integer)
The address ID, when taken from the address book 		123457
instruction (string)
Pickup or Delivery instructions 		Residential Delivery. Appointment Delivery. Tailgate
freight_description (string)
Freight Description 		Pallet of paper
items (array)
Items to be picked up or delivered to the current location
Name Example Value
id (integer)
The Item ID 		1234567
stop_id (integer)
The Stop ID 		1234567
type (enum)
The item type. 		Bags|Bales|Barrels|Boxes|Bundles|Cartons|Crates|Drums|Pallets|Pieces|skids|Skids|Totes
width (integer)
Width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
height (integer)
Height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
length (integer)
Length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
weight (integer)
Weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		2
units (enum)
The width, height, length and weight Unit Measurement System. Options are imperial|metric 		imperial|metric
quantity (integer)
The number of items 		2
carriers (array)
Order carriers
Name Example Value
id (integer)
The transit operation ID 		1234567
carrier_id (integer)
The carrier ID 		7654321
has_insurance (boolean)
True if the carrier has an insurance 		false
charges (array)
Order charges
Name Example Value
type (enum)
Type of charge 		service|...
amount (number)
Charge amount 		5.00
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Quote order

Search all carriers rates that match any quote requested by the user.

Action

[POST] /v2/logistics/orders/rates

Request

POST /v2/logistics/orders/rates HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json 
{
    "pickup": {
        "name": "ACME inc.",
        "attn": "Bob",
        "date": "2023-11-01",
        "from_time": "09:00",
        "until_time": "16:00",
        "address": "123 Main Street",
        "suite": "227",
        "department": "Reception",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1B2C3",
        "phone": "866-320-8383",
        "phone_ext": "123",
        "is_commercial": "true",
        "special_instruction": "Residential Pickup. Appointment Delivery. Tailgate",
        "freight_description": "Pallet of paper",
        "items": [
            {
                "quantity": 2,
                "width": 48,
                "height": 48,
                "length": 48,
                "weight": 2,
                "units": "imperial",
                "type": "Bags"
            },
            "..."
        ]
    },
    "delivery": {
        "name": "ACME inc.",
        "attn": "Bob",
        "date": "2023-11-01",
        "from_time": "09:00",
        "until_time": "16:00",
        "address": "123 Main Street",
        "suite": "227",
        "department": "Reception",
        "city": "Montreal",
        "country": "CA",
        "state": "QC",
        "postal_code": "A1A1A1",
        "phone": "866-320-8383",
        "phone_ext": "123",
        "is_commercial": "true",
        "special_instruction": "Residential Delivery. Appointment Delivery. Tailgate",
        "freight_description": "Pallet of paper",
        "items": [
            {
                "quantity": 2,
                "width": 48,
                "height": 48,
                "length": 48,
                "weight": 2,
                "units": "imperial",
                "type": "Bags"
            },
            "..."
        ]
    },
    "shipment_info": {
        "shipment_type": "LTL",
        "container_type": "20ft",
        "truck_type": "24 foot Straight Truck",
        "truck_details": "Tailgate, Frozen"
    },
    "options": {
        "insurance": {
            "value": 123.45,
            "toggle": "false",
            "commodity": "Wire decking"
        },
        "limited_access": {
            "pickup_toggle": "true",
            "pickup_message": "",
            "delivery_toggle": "true",
            "delivery_message": ""
        },
        "dangerous_goods": {
            "un": "UN3480",
            "class": 8,
            "toggle": "false",
            "commodity": "Sodium Hydroxide Solution",
            "packaging_group": "II"
        },
        "appointment_delivery": "false",
        "blind_pickup": "false",
        "blind_delivery": "false",
        "heated_service": "false",
        "inside_pickup": "false",
        "inside_delivery": "true",
        "tailgate_pickup": "false",
        "tailgate_delivery": "true",
        "residential_pickup": "true",
        "residential_delivery": "false",
        "small_truck_pickup": "false",
        "small_truck_delivery": "true",
        "show_freight": "false",
        "storage_facility_pickup": "true",
        "storage_facility_delivery": "true",
        "team_drivers": "false",
        "weekend_pickup": "false",
        "weekend_delivery": "false"
    }
}

Details

Name Example Value
pickup (Order Pickup)
Pickup specification, including pickup address and items to be shipped.
Name Example Value
name (string)
Pickup name 		ACME inc.
attn (string)
Attn name 		Bob
date (date)
Pickup date. Can be YYYY-MM-DD. Should be greater or eqal to the current date and not greater than Delivery Date. 		2023-11-01
from_time (time)
Time from when the pickup should be done. In 24h format hh:mm. 		09:00
until_time (time)
Time until when the pickup should be done. In 24h format hh:mm. 		16:00
address (string)
Pickup address 		123 Main Street
suite (string)
The unit or office number 		227
department (string)
Company or organization department 		Reception
city (string)
Pickup city 		Montreal
country (string)
Pickup country. ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
Pickup state or province. ISO 3166-1 alpha-2 two letter state if applicable in the country. 		QC
postal_code (string)
Pickup postal code. 		A1B2C3
phone (string)
866-320-8383
phone_ext (number)
123
is_commercial (boolean)
Is the address entered a commercial address? true by default 		true
special_instruction (string)
Pickup instructions 		Residential Pickup. Appointment Delivery. Tailgate
freight_description (string)
Freight Description 		Pallet of paper
items (array)
Items to be picked up
Name Example Value
quantity (integer)
The number of items 		2
width (integer)
Width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
height (integer)
Height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
length (integer)
Length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
weight (integer)
Weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		2
units (enum)
Width, height, length and weight Unit System. Options are imperial|metric. 		imperial|metric
type (enum)
The item type 		Bags|Bales|Barrels|Boxes|Bundles|Cartons|Crates|Drums|Pallets|Pieces|skids|Skids|Totes
delivery (Order Delivery)
Delivery specification, including delivery address and items to be shipped.
Name Example Value
name (string)
Delivery name 		ACME inc.
attn (string)
The attn name 		Bob
date (date)
Delivery date. Can be YYYY-MM-DD. Should be greater or eqal to the Pickup Date. 		2023-11-01
from_time (time)
Time from when delivery should be done. In 24h format hh:mm. 		09:00
until_time (time)
Time until when delivery should be done. In 24h format hh:mm. 		16:00
address (string)
Delivery address 		123 Main Street
suite (string)
The unit or office number 		227
department (string)
Company or organization department 		Reception
city (string)
Delivery city 		Montreal
country (string)
Delivery country. ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
Delivery state or province. ISO 3166-1 alpha-2 two letter state if applicable in the country. 		QC
postal_code (string)
Delivery postal code. 		A1A1A1
phone (string)
866-320-8383
phone_ext (number)
123
is_commercial (boolean)
Is the address entered a commercial address? true by default 		true
special_instruction (string)
Delivery instructions 		Residential Delivery. Appointment Delivery. Tailgate
freight_description (string)
Freight Description 		Pallet of paper
items (array)
Items to be delivered
Name Example Value
quantity (integer)
The number of items 		2
width (integer)
Width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
height (integer)
Height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
length (integer)
Length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
weight (integer)
Weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		2
units (enum)
Width, height, length and weight Unit System. Options are imperial|metric. 		imperial|metric
type (enum)
The item type 		Bags|Bales|Barrels|Boxes|Bundles|Cartons|Crates|Drums|Pallets|Pieces|skids|Skids|Totes
shipment_info (Shipment Specification)
Shipment Specification
Name Example Value
shipment_type (enum)
Shipment type 		LTL|FTL|CL|LTL
container_type (enum)
Container type 		20ft|40ft
truck_type (enum)
Truck type 		24 foot Straight Truck|53 foot Dry Van|Cargo Van|Cube Truck|Flat Bed|Refrigerated|Sprinter Van
truck_details (string)
Truck details 		Tailgate, Frozen
options (Quote Options)
Quote options. None of the options are required.
Name Example Value
insurance (Insurance Option)
Insurance
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
toggle (boolean)
Whether the insurance option is toggled 		false
commodity (string)
Insurance commodity 		Wire decking
limited_access (Limited Access Option)
Limited Access
Name Example Value
pickup_toggle (boolean)
Whether Limited Access pickup option is toggled 		true
pickup_message (string)
Pickup Limited Access note or message
delivery_toggle (boolean)
Whether Limited Access delivery option is toggled 		true
delivery_message (string)
Delivery Limited Access note or message
dangerous_goods (Dangerous Goods Option)
Dangerous Goods
Name Example Value
un (string)
The UN number or United Nations number that identifies the good. 		UN3480
class (number)
The Dangerous Goods class number. 		8
toggle (boolean)
Whether Dangerous Goods option is toggled 		false
commodity (string)
The good being shipped 		Sodium Hydroxide Solution
packaging_group (string)
The Packaging Group. Options are I|II|III which stands for High danger, Medium danger or Low danger. 		II
appointment_delivery (boolean)
Appointment Delivery 		false
blind_pickup (boolean)
Blind Pickup 		false
blind_delivery (boolean)
Blind Delivery 		false
heated_service (boolean)
Heated service 		false
inside_pickup (boolean)
Inside Pickup 		false
inside_delivery (boolean)
Inside Delivery 		true
tailgate_pickup (boolean)
Tailgate Pickup 		false
tailgate_delivery (boolean)
Tailgate Delivery 		true
residential_pickup (boolean)
Residential Pickup 		true
residential_delivery (boolean)
Residential Delivery 		false
small_truck_pickup (boolean)
Small Truck Pickup 		false
small_truck_delivery (boolean)
Small Truck Delivery 		true
show_freight (boolean)
Show Freight 		false
storage_facility_pickup (boolean)
Public Storage Facility Pickup 		true
storage_facility_delivery (boolean)
Public Storage Facility Delivery 		true
team_drivers (boolean)
Driver Assist 		false
weekend_pickup (boolean)
Weekend Pickup 		false
weekend_delivery (boolean)
Weekend Delivery 		false

Response

200 OK 

{
    "content": [
        {
            "price": {
                "charges": {
                    "freight": "92.00",
                    "tailgate_delivery": "64",
                    "tailgate_pickup": "64"
                },
                "adjustments": "3.00",
                "debits": "5.00",
                "brokerage": "10.00",
                "subtotal": "75.00",
                "total": "100.00",
                "taxes": "15.00"
            },
            "service": {
                "flagship_code": "freightStandard",
                "transit_time": "2-4, meaning 2 to 4 days",
                "estimated_delivery_date": "2023-11-07",
                "carrier_code": "My Company Name",
                "carrier_desc": "Mtl-Toron Express-Transit Inc.",
                "carrier_name": "",
                "carrier_id": 1234567
            }
        },
        "..."
    ],
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (array)
All carriers rates that match the request of the user
Name Example Value
price (Carrier Rate)
Rate price
Name Example Value
charges (Rate Charges)
Rate charges
Name Example Value
freight (number)
Freight 		92.00
tailgate_delivery (number)
Tailgate pickup 		64
tailgate_pickup (number)
Tailgate Delivery 		64
adjustments (number)
Adjustments 		3.00
debits (number)
Debits 		5.00
brokerage (number)
Brokerage 		10.00
subtotal (number)
Subtotal 		75.00
total (number)
Total amount 		100.00
taxes (number)
Taxes 		15.00
service (Rate Carrier)
Rate carrier
Name Example Value
flagship_code (string)
Flagship service Code. 		freightStandard
transit_time (string)
The transit time. Expressed as a range of days. 		2-4, meaning 2 to 4 days
estimated_delivery_date (date)
The estimated delivery date 		2023-11-07
carrier_code (string)
Carrier system code 		My Company Name
carrier_desc (string)
Carrier name 		Mtl-Toron Express-Transit Inc.
carrier_name (string)
Carrier system name
carrier_id (integer)
Carrier ID 		1234567
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]

Confirm an Order

Confirms the order identified by id field from the request uri

Action

[PUT] /v2/logistics/orders/confirm/{order_id}

URI Parameters

Parameter Value Description
order_id 1234567 The order id

Request

PUT /v2/logistics/orders/confirm/{order_id} HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
Content-Type: application/json

Response

200 OK 

{
    "content": {
        "id": 1234567,
        "company_id": 7654321,
        "status": "arrived at destination terminal",
        "purchase_order": "ABC-EFGH-12-34",
        "quote_options": {
            "insurance": {
                "value": 123.45,
                "toggle": "false",
                "commodity": "Wire decking"
            },
            "limited_access": {
                "pickup_toggle": "true",
                "pickup_message": "",
                "delivery_toggle": "true",
                "delivery_message": ""
            },
            "dangerous_goods": {
                "un": "UN3480",
                "class": 8,
                "toggle": "false",
                "commodity": "Sodium Hydroxide Solution",
                "packaging_group": "II"
            },
            "appointment_delivery": "false",
            "blind_pickup": "false",
            "blind_delivery": "false",
            "heated_service": "false",
            "inside_pickup": "false",
            "inside_delivery": "true",
            "tailgate_pickup": "false",
            "tailgate_delivery": "true",
            "residential_pickup": "true",
            "residential_delivery": "false",
            "small_truck_pickup": "false",
            "small_truck_delivery": "true",
            "show_freight": "false",
            "storage_facility_pickup": "true",
            "storage_facility_delivery": "true",
            "team_drivers": "false",
            "weekend_pickup": "false",
            "weekend_delivery": "false"
        },
        "stops": [
            {
                "id": 1234567,
                "type": "pickup",
                "pickup_date": "2023-11-01",
                "pickup_from_time": "09:00",
                "pickup_until_time": "16:00",
                "delivery_date": "2023-11-17",
                "delivery_from_time": "08:00",
                "delivery_until_time": "17:00",
                "name": "ACME inc.",
                "attn": "Bob",
                "address": "123 Main Street",
                "suite": "227",
                "department": "Reception",
                "city": "Montreal",
                "country": "CA",
                "state": "QC",
                "postal_code": "A1B2C3",
                "phone": "866-320-8383",
                "phone_ext": "123",
                "is_commercial": "true",
                "address_id": 123457,
                "instruction": "Residential Delivery. Appointment Delivery. Tailgate",
                "freight_description": "Pallet of paper",
                "items": [
                    {
                        "id": 1234567,
                        "stop_id": 1234567,
                        "type": "Bags",
                        "width": 48,
                        "height": 48,
                        "length": 48,
                        "weight": 2,
                        "units": "imperial",
                        "quantity": 2
                    },
                    "..."
                ]
            },
            "..."
        ],
        "carriers": [
            {
                "id": 1234567,
                "carrier_id": 7654321,
                "has_insurance": "false"
            },
            "..."
        ],
        "charges": [
            {
                "type": "service",
                "amount": "5.00"
            },
            "..."
        ]
    },
    "errors": [],
    "notices": []
}

Details

Name Example Value
content (Order)
The Order to confirmed
Name Example Value
id (integer)
order ID 		1234567
company_id (integer)
Company ID 		7654321
status (enum)
Order status. Options are arrived at destination terminal|cancelled|claim|delayed|delivered|in bond|in storage|in transit|invoiced|no charge|on hold|out for delivery|picked up|preordered|quoted|rate discrepancy|ready to invoice|rfq|scheduled for delivery|scheduled for pickup|tbd quoted|tbd|user-confirmed|warehousing 		arrived at destination terminal|cancelled|claim|delayed|delivered|in bond|in storage|in transit|invoiced|no charge|on hold|out for delivery|picked up|preordered|quoted|rate discrepancy|ready to invoice|rfq|scheduled for delivery|scheduled for pickup|tbd quoted|tbd|user-confirmed|warehousing
purchase_order (string)
Purchase Order Number 		ABC-EFGH-12-34
quote_options (Quote Options)
Quote Options
Name Example Value
insurance (Insurance Option)
Insurance
Name Example Value
value (decimal)
CAD$ value of the items to insure. Note that exlusions apply, see here for details 		123.45
toggle (boolean)
Whether the insurance option is toggled 		false
commodity (string)
Insurance commodity 		Wire decking
limited_access (Limited Access Option)
Limited Access
Name Example Value
pickup_toggle (boolean)
Whether Limited Access pickup option is toggled 		true
pickup_message (string)
Pickup Limited Access note or message
delivery_toggle (boolean)
Whether Limited Access delivery option is toggled 		true
delivery_message (string)
Delivery Limited Access note or message
dangerous_goods (Dangerous Goods Option)
Dangerous Goods
Name Example Value
un (string)
The UN number or United Nations number that identifies the good. 		UN3480
class (number)
The Dangerous Goods class number. 		8
toggle (boolean)
Whether Dangerous Goods option is toggled 		false
commodity (string)
The good being shipped 		Sodium Hydroxide Solution
packaging_group (string)
The Packaging Group. Options are I|II|III which stands for High danger, Medium danger or Low danger. 		II
appointment_delivery (boolean)
Appointment Delivery 		false
blind_pickup (boolean)
Blind Pickup 		false
blind_delivery (boolean)
Blind Delivery 		false
heated_service (boolean)
Heated service 		false
inside_pickup (boolean)
Inside Pickup 		false
inside_delivery (boolean)
Inside Delivery 		true
tailgate_pickup (boolean)
Tailgate Pickup 		false
tailgate_delivery (boolean)
Tailgate Delivery 		true
residential_pickup (boolean)
Residential Pickup 		true
residential_delivery (boolean)
Residential Delivery 		false
small_truck_pickup (boolean)
Small Truck Pickup 		false
small_truck_delivery (boolean)
Small Truck Delivery 		true
show_freight (boolean)
Show Freight 		false
storage_facility_pickup (boolean)
Public Storage Facility Pickup 		true
storage_facility_delivery (boolean)
Public Storage Facility Delivery 		true
team_drivers (boolean)
Driver Assist 		false
weekend_pickup (boolean)
Weekend Pickup 		false
weekend_delivery (boolean)
Weekend Delivery 		false
stops (array)
Pickup and Delivery
Name Example Value
id (integer)
The Order Address ID 		1234567
type (enum)
The stop type. Options are pickup|switch|delivery 		pickup|switch|delivery
pickup_date (date)
Pickup date 		2023-11-01
pickup_from_time (time)
Time from when the pickup should be done 		09:00
pickup_until_time (time)
Time until when the pickup should be done 		16:00
delivery_date (date)
Delivery date 		2023-11-17
delivery_from_time (time)
Time from when the delivery should be done 		08:00
delivery_until_time (time)
Time until when the delivery should be done 		17:00
name (string)
Stop name 		ACME inc.
attn (string)
The attn name 		Bob
address (string)
Delivery or Pickup address 		123 Main Street
suite (string)
The unit or office number 		227
department (string)
Company or organization department 		Reception
city (string)
The city 		Montreal
country (string)
ISO 3166-1 alpha-2 two letter country code 		CA
state (string)
ISO 3166-1 alpha-2 two letter state if applicable in the country 		QC
postal_code (string)
A1B2C3
phone (string)
866-320-8383
phone_ext (number)
123
is_commercial (boolean)
Is the address entered a commercial address? true by default 		true
address_id (integer)
The address ID, when taken from the address book 		123457
instruction (string)
Pickup or Delivery instructions 		Residential Delivery. Appointment Delivery. Tailgate
freight_description (string)
Freight Description 		Pallet of paper
items (array)
Items to be picked up or delivered to the current location
Name Example Value
id (integer)
The Item ID 		1234567
stop_id (integer)
The Stop ID 		1234567
type (enum)
The item type. 		Bags|Bales|Barrels|Boxes|Bundles|Cartons|Crates|Drums|Pallets|Pieces|skids|Skids|Totes
width (integer)
Width of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
height (integer)
Height of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
length (integer)
Length of the package ceiled up to the nearest integer. eg: 3.2 = 4 		48
weight (integer)
Weight of the package ceiled up to the nearest integer. eg: 3.2 = 4 		2
units (enum)
The width, height, length and weight Unit Measurement System. Options are imperial|metric 		imperial|metric
quantity (integer)
The number of items 		2
carriers (array)
Order carriers
Name Example Value
id (integer)
The transit operation ID 		1234567
carrier_id (integer)
The carrier ID 		7654321
has_insurance (boolean)
True if the carrier has an insurance 		false
charges (array)
Order charges
Name Example Value
type (enum)
Type of charge 		service|...
amount (number)
Charge amount 		5.00
errors (array)
Messages that AFFECT the outcome of the request will be shown here
[]
notices (array)
Messages that MIGHT affect the outcome of the request will be shown here
[]