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.
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 |
|
200 OK
{
"content": [
{
"price": {
"charges": {
"freight": 123.45,
"signature_required": 123.45,
"insurance": 123.45,
"multipiece": 123.45
},
"adjustments": null,
"debits": 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": []
}
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 |
|
debits
(null)
Charges that are deducted before the invoice is generated |
|
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 |
|
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,
"debits": 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": []
}
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 |
|
debits
(null)
Charges that are deducted before the invoice is generated |
|
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 |
|
|
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,
"debits": 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": []
}
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 |
|
debits
(null)
Charges that are deducted before the invoice is generated |
|
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 |
[]
|
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
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
},
"debits": {
"fuel_surchage": -123.45
},
"subtotal": 123.45,
"total": 123.45,
"taxes": {
"gst": 123.45,
"qst": 123.45,
"pst": 123.45,
"hst": 123.45
}
},
"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": []
}
Name |
Example Value |
content
(Shipment) {...}
|
Name |
Example Value |
id
(interger)
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|predispatch|dispatch|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 |
|
debits
(Shipment Debits) {...}
Charges that are deducted before the invoice is generated |
Name |
Example Value |
fuel_surchage
(decimal)
Freight |
-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 |
|
|
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 |
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 |
[]
|
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 |
|
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
},
"debits": {
"fuel_surchage": -123.45
},
"subtotal": 123.45,
"total": 123.45,
"taxes": {
"gst": 123.45,
"qst": 123.45,
"pst": 123.45,
"hst": 123.45
}
},
"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": []
}
Name |
Example Value |
content
(Shipment) {...}
|
Name |
Example Value |
id
(interger)
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|predispatch|dispatch|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 |
|
debits
(Shipment Debits) {...}
Charges that are deducted before the invoice is generated |
Name |
Example Value |
fuel_surchage
(decimal)
Freight |
-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 |
|
|
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 |
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
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,
"debits": 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": []
}
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 |
|
debits
(null)
Charges that are deducted before the invoice is generated |
|
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
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 |
status |
dispatched |
Filter by the shipment status. Options are prequoted|quoted|predispatch|dispatch|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
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
},
"debits": {
"fuel_surchage": -123.45
},
"subtotal": 123.45,
"total": 123.45,
"taxes": {
"gst": 123.45,
"qst": 123.45,
"pst": 123.45,
"hst": 123.45
}
},
"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": []
}
Name |
Example Value |
content
(Shipment List) {...}
|
Name |
Example Value |
records
(array) {...}
Array with the shipments belonging to the requested page |
Name |
Example Value |
id
(interger)
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|predispatch|dispatch|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 |
|
debits
(Shipment Debits) {...}
Charges that are deducted before the invoice is generated |
Name |
Example Value |
fuel_surchage
(decimal)
Freight |
-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 |
|
|
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 |
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,
"width": 52,
"height": 30,
"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 |
width
(decimal)
width of the box(outer size) |
52 |
height
(decimal)
height of the box(outer size) |
30 |
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 |
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": []
}
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 |
Request
GET /ship/available_services HTTPS/1.1
Host: api.smartship.io
X-Smartship-Token: kXCSNMGOk39QB5cp-DlnFGX3TA77xZE_yqWqwnia1pGc
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": []
}
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 |
[]
|
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
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": "Reception",
"instruction": "contain glass product, etc.",
"cancelled": "0",
"units": "imperial",
"shipments": [
"integer",
"..."
]
},
"errors": [],
"notices": []
}
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
|
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 |
Reception |
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": "Reception",
"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
|
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". |
Reception |
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. |
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": "Reception",
"instruction": "contain glass product, etc.",
"cancelled": "0",
"units": "imperial",
"shipments": [
"integer",
"..."
]
},
"errors": [],
"notices": []
}
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
|
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 |
Reception |
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": "Reception",
"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". |
Reception |
instruction
(string)
Special attention for delivery |
contain glass product, etc. |
shipments
(array) {...}
Shipment Ids (e.g., 123456, 234567,) |
[]
|
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": "Reception",
"instruction": "contain glass product, etc.",
"cancelled": "0",
"units": "imperial",
"shipments": [
"integer",
"..."
]
},
"..."
],
"errors": [],
"notices": []
}
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
|
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 |
Reception |
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": "Reception",
"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": []
}
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
|
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 |
Reception |
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": "Reception",
"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
|
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". |
Reception |
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. |
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": "Reception",
"instruction": "contain glass product, etc.",
"cancelled": "0",
"units": "imperial",
"shipments": [
"integer",
"..."
]
},
"errors": [],
"notices": []
}
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
|
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 |
Reception |
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
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
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": "Reception",
"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": []
}
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
|
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 |
Reception |
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 |
[]
|
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
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": []
}
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 |
[]
|
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
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": []
}
Name |
Example Value |
content
(array) {...}
|
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 |
[]
|