Home / ClutchShipper API

ClutchShipper API

ClutchShipper RESTful API GUIDE

Version 2.1.0

1. API Summary and Information


Introduction

Clutch Shipper’s API serves to efficiently create and print shipping labels at a reduced cost. This document contains implementation instructions for integrating ClutchShipper RESTful API into your system.

API base path

https://clutchshipper.com/api/

 

2. Common Elements

All requests to Clutch Shipper API have in common some elements on the header and response.

Common Request Header Fields

Except session token calls, all API calls require to include in the header the information described in the table below:

Field Name Type Comments
Token String Token obtained in a Session Token call. It is required for authentication.
Content-type String required value: "application/json"



Common Response Fields

Clutch Shipper API services response in an established format as is shown in the table below. In case of no error, the field "ResponseResults" will contain the requested information.

Field Name Type Comments
ResponseStatus Container
ResponseStatus.Code Integer Request status code
ResponseStatus.Description String Request status description
ResponseStatus.Error String Null if no errors
ResponseStatus.Message String Transaction/Error message
ResponseResults Container Requested information


In case of error, the "Message" could contain a reference code, which would be useful when reporting the error to support staff. Reference code example: (ref: 231221.112327.295367)

Status Code and Description

Some common values returned on fields "Code" and "Description" are listed on the table below.

Code Description
200 Success
201 Created
202 Accepted
400 Bad request
401 Unauthorized
402 Payment Required
403 Forbidden
404 Not Found
405 Method Not Allowed
412 Precondition Failed
422 Unprocessable Entity
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable



Response Example:

{
    "ResponseResults": null,
    "ResponseStatus": {
        "Code": 401,
        "Description": "Unauthorized",
        "Error": "Unauthorized",
        "Message": "Incorrect username or password. (ref: 240223.083613.381851)"
    }
}


3. Session Token

A session token is needed to access ClutchShipper API services. This token expires after 12 hours (720 minutes) of being delivered. Once it expires, a new token must be requested again before making further service calls.

Method: GET
Route: /auth/token

Request Header


Field Name Type Comments
Authorization String It requires username and password, both case sensitive, joined, and encoded as a base 64 string.
Syntax: "Basic " + base64_string(username + ":" + password)


Examples:


HTTP Example
GET /api/auth/token HTTP/1.1
Host: clutchshipper.com
Authorization: Basic bXlfbmFtZTpteV9wYXNz

Python Example
import requests, base64
url = "https://clutchshipper.com/api/auth/token"
username = "My_Username"
password = "My_Password"
credentials = base64.b64encode(bytes(username + ":" + password,'UTF-8')).decode('ascii')
headers = {'Authorization': 'Basic ' + credentials}
response = requests.request("GET", url, headers=headers, data={})

Response

Response is null in case of error, otherwise are returned the fields described in the table below:

Field Name Type Comments
Token String Token required in the header of your API requests for authentication.


Examples:


Successful Authentication
{
    "ResponseResults": {
        "Token": "15576696791511562927-80cb9752-78d6-4fe1-8ed8-97f1e125bfd4"
    },
    "ResponseStatus": {
        "Code": 200,
        "Description": "Success",
        "Error": null,
        "Message": "Valid credentials."
    }
}
Failed Authentication
{
    "ResponseResults": null,
    "ResponseStatus": {
        "Code": 401,
        "Description": "Unauthorized",
        "Error": "Unauthorized",
        "Message": "Incorrect username or password. (ref: 240223.083613.381851)"
    }
}

4. Available Services



Services allowed for domestic shipping


Code Name Notes
01 UPS Next Day Air
02 UPS 2nd Day Air
03 UPS Ground
12 UPS 3 Day Select
13 UPS Next Day Air Saver
14 UPS Next Day Air Early
59 UPS 2nd Day Air A.M.
std-us-swa-mfn Amazon Shipping Ground Contact us to access this service


Services allowed from US to unincorporated territories or overseas


Code Name Canada Puerto Rico
01 UPS Next Day Air X
02 UPS 2nd Day Air X
03 UPS Ground X
11 UPS Standard X


Services allowed from overseas to US


Code Name Notes
KRTHZXR Korea Standard Shipping from KR to US

 

5. Address Validation



Setting

Clutch Shipper API supports Address Validation for US addresses by adding the field "AddressValidation" in a regular shipping label request. The valid values for this field are:

Value Description Comments
false/0 No validation is performed. This is the default value.
true / 1 Validates the address. The validation is performed for sender and receiver.



Candidates

If the validated address does not exist, the API will return an error but also it will return candidate addresses which may be similar to the one that was provided. The information returned is shown in the table below:

Field Name Type Comments
Candidates Container
ShipFrom Array Empty array if no candidates
ShipFrom[i] Container
ShipFrom[i].AddressLine1 String
ShipFrom[i].AddressLine2 String
ShipFrom[i].City String
ShipFrom[i].PostalCode String
ShipFrom[i].StateCode String
ShipFrom[i].CountryCode String
ShipTo Array Empty array if no candidates
ShipTo[i] Container
ShipTo[i].AddressLine1 String
ShipTo[i].AddressLine2 String
ShipTo[i].City String
ShipTo[i].PostalCode String
ShipTo[i].StateCode String
ShipTo[i].CountryCode String



Response Example

{
    "ResponseStatus": {
        "Code": 202,
        "Description": "Accepted",
        "Error": "Accepted",
        "Message": "The address is ambiguous. Select a candidate for it. (ref: 240220.094236.164733)"
    },
    "ResponseResults": {
        "Candidates": {
            "ShipFrom": [],
            "ShipTo": [
                {
                    "AddressLine1": "1234 NW 82ND AVE",
                    "AddressLine2": "",
                    "City": "DORAL",
                    "StateCode": "FL",
                    "PostalCode": "22345",
                    "CountryCode": "US"
                },
                {
                    "AddressLine1": "1234 Northwest 82nd ave",
                    "AddressLine2": "",
                    "City": "Doral",
                    "StateCode": "FL",
                    "PostalCode": "21345",
                    "CountryCode": "US"
                }
            ]
        }
    }
}


6. Delivery Confirmation

Setting

Clutch Shipper API supports Signature Required service for domestic shipping by adding the field "DeliveryConfirmation" in a regular shipping label request. This service requires the recipient to sign for a package before it is released into their possession. Notice that all packages included in the same request will require the signature. The valid values for this field are:

Value Description Comments
0 No signature required. This is the default value.
1 Delivery Signature Required.
2 Delivery Adult Signature Required

Important: Delivery Confirmation is not available for Amazon shipping, in that case this field is ignored.

 

7. Return Service

Setting

Clutch Shipper API allows to create return service labels by adding the field "ReturnService" in a regular shipping label request. The valid values for this field are:

Value Description Comments
0 Creates a Regular Forward Label. This is the default value in order to create a forward label, not a return label.
1 Creates a Return Label by swapping sender and receiver input information. With this option you do not have to modify the original request of a forward shipment, the API will swap the addresses for you in order to create the return label.
2 Creates a Return Label by keeping sender and receiver input information as is. The API will not swap the addresses as in option 1.

 

 

8. Create Shipping Labels

Method: POST
Route: /v2/shipments/label-request


Domestic Shipping Request


Field Name Type Required Length/Range Comments
RequestId String Yes 10 ... 28 Special characters are not allowed
ShipmentDescription String No 0 ... 50
ServiceCode String Yes 20 See section "Available Services"
AddressValidation Integer No 0 ... 1 See section "Address Validation"
DeliveryConfirmation Integer No 0 ... 2 See section "Delivery Confirmation"
ReturnService Integer No 0 ... 2 See section "Return Service"
ShipFrom Container Yes
ShipFrom.Name String Yes 1 ... 35
ShipFrom.AttentionName String No 0 ... 35
ShipFrom.Phone String No 10 ... 15
ShipFrom.EmailAddress String No 0 ... 50
ShipFrom.Address Container Yes
ShipFrom.Address.AddressLine1 String Yes 1 ... 35
ShipFrom.Address.AddressLine2 String No 0 ... 35
ShipFrom.Address.City String Yes 1 ... 45
ShipFrom.Address.PostalCode String Yes 5 ... 10 Zip extension not required
ShipFrom.Address.StateProvinceCode String Yes 2 U.S. State abbreviation
ShipFrom.Address.CountryCode String Yes 2 Allowed: "US"
ShipTo Container Yes
ShipTo.Name String Yes 1 ... 35
ShipTo.AttentionName String No 0 ... 35
ShipTo.Phone String No 10 ... 15
ShipTo.EmailAddress String No 0 ... 50
ShipTo.Address Container Yes
ShipTo.Address.AddressLine1 String Yes 1 ... 35
ShipTo.Address.AddressLine2 String No 0 ... 35
ShipTo.Address.City String Yes 1 ... 45
ShipTo.Address.PostalCode String Yes 5 ... 10 Zip extension not required
ShipTo.Address.StateProvinceCode String Yes 2 U.S. State abbreviation
ShipTo.Address.CountryCode String Yes 2 Allowed: "US"
Package Array Yes
Package[i] Container Yes
Package[i].NumberLabels Integer No 1 ... 99 By default = 1
Package[i].Reference String No 0 ... 28
Package[i].PackageWeight Container Yes
Package[i].PackageWeight.Weight Number Yes 1 ... 150.0
Package[i].PackageWeight.UnitOfMeasurement String Yes 3 Allowed: LBS, KGS, OZS
Package[i].Dimensions Container Yes
Package[i].Dimensions.Length Number Yes 1 ... 99.99
Package[i].Dimensions.Height Number Yes 1 ... 99.99
Package[i].Dimensions.Width Number Yes 1 ... 99.99
Package[i].Dimensions.UnitOfMeasurement String Yes 2 Allowed: IN, CM
Package[i].DeclaredValue Container No
Package[i].DeclaredValue.MonetaryValue Number yes 0 ... 50000
Package[i].DeclaredValue.CurrencyCode String yes 3 Example: USD
Package[i].Items Array Conditional Required only for Amazon Shipping
Package[i].Items[i] Container Yes
Package[i].Items[i].Description String No 100
Package[i].Items[i].Quantity Integer Yes 1 ... 99
Package[i].Items[i].ItemWeight Container Yes
Package[i].Items[i].ItemWeight.UnitOfMeasurement String Yes 3 Allowed: LBS, KGS, OZS
Package[i].Items[i].ItemWeight.Weight Number Yes 1 ... 150.0



Examples:


POST /api/v2/shipments/label-request HTTP/1.1
Host: clutchshipper.com
Token: 15576696791511562927-80cb9752-78d6-4fe1-8ed8-97f1e125bfd4
Content-type: application/json


UPS Shipping Body
{
    "RequestId": "test_000001",
    "ShipmentDescription": "",    
    "ServiceCode": "03",
    "AddressValidation": true,
    "DeliveryConfirmation": 0,
    "ReturnService": 0,
    "ShipFrom":{
        "Name": "Sender Name", 
        "Phone": "2133730000", 
        "EmailAddress": "sender@email.com", 
        "Address": {
            "AddressLine1": "1234 Sender Address Ave",
            "City": "Los Angeles",
            "StateProvinceCode": "CA",
            "PostalCode": "92231",            
            "CountryCode": "US"
        }
    },
    "ShipTo":{
        "Name": "Receiver Name", 
        "AttentionName": "Receiver", 
        "EmailAddress": "receiver@gmail.com", 
        "Address": {
            "AddressLine1": "6789 Receiver Address Ave",
            "AddressLine2": "Apt 15",            
            "City": "Doral",
            "StateProvinceCode": "FL",
            "PostalCode": "27000",            
            "CountryCode": "US"
        }
    },
    "Package": [
        {
            "PackageWeight": {
                "Weight": 5.0,
                "UnitOfMeasurement": "LBS"            
            },
            "Dimensions": {
                "Length": 7.0, 
                "Width": 8.0, 
                "Height": 9.0,
                "UnitOfMeasurement": "IN"
            }
        },
        {
            "NumberLabels": 2,
            "Reference": "test ref.",
            "PackageWeight": {
                "Weight": 2.0,
                "UnitOfMeasurement": "LBS"            
            },
            "Dimensions": {
                "Length": 6.0, 
                "Width": 11.0, 
                "Height": 9.0,
                "UnitOfMeasurement": "IN"
            },
            "DeclaredValue":{
                "MonetaryValue": 125.0,
                "CurrencyCode": "USD"
            }
        }
    ]
}


Amazon Shipping Body
{
    "RequestId": "test_000001",
    "ServiceCode": "std-us-swa-mfn",
    "AddressValidation": true,
    "ShipFrom":{
        "Name": "Sender Name", 
        "Phone": "2133730000", 
        "EmailAddress": "sender@email.com", 
        "Address": {
            "AddressLine1": "1234 Sender Address Ave",
            "City": "Los Angeles",
            "StateProvinceCode": "CA",
            "PostalCode": "92231",            
            "CountryCode": "US"
        }
    },
    "ShipTo":{
        "Name": "Receiver Name", 
        "AttentionName": "Receiver", 
        "EmailAddress": "receiver@gmail.com", 
        "Address": {
            "AddressLine1": "6789 Receiver Address Ave",
            "AddressLine2": "Apt 15",            
            "City": "Doral",
            "StateProvinceCode": "FL",
            "PostalCode": "27000",            
            "CountryCode": "US"
        }
    },
    "Package": [
        {
            "NumberLabels": 2,
            "PackageWeight": {
                "Weight": 2.0,
                "UnitOfMeasurement": "LBS"            
            },
            "Dimensions": {
                "Length": 6.0, 
                "Width": 11.0, 
                "Height": 9.0,
                "UnitOfMeasurement": "IN"
            },
            "DeclaredValue":{
                "MonetaryValue": 125.0,
                "CurrencyCode": "USD"
            },
           "Items":[
                {
                    "Description": "item 1",
                    "Quantity": 1,
                    "ItemWeight":{
                        "UnitOfMeasurement": "LBS",
                        "Weight": 2.0
                    }
                }
            ]
        }
    ]
}



International Shipping Request

The API supports international shipping toward Canada or Puerto Rico, but it is available only for some services as described in section "Available Services". The request requires all fields described for domestic shipping and additionally consider the following:

Field Name Type Required Length/Range Comments
ShipmentDescription String Yes 0 ... 50
InvoiceLineTotal Container Yes
InvoiceLineTotal.MonetaryValue Number Yes 0 ... 100000
InvoiceLineTotal.CurrencyCode String yes 3 Example: USD
ShipTo.Address.StateProvinceCode String Yes 2 ... 4 For Puerto Rico use "PR"
ShipTo.Address.CountryCode String Yes 2 Allowed: "CA", "PR"



Examples:


POST /api/v2/shipments/label-request HTTP/1.1
Host: clutchshipper.com
Token: 15576696791511562927-80cb9752-78d6-4fe1-8ed8-97f1e125bfd4
Content-type: application/json


Canada Shipping Body
{
    "RequestId": "test_000001",
    "ShipmentDescription": "Content description required",
    "ServiceCode": "11",
    "InvoiceLineTotal": {
        "MonetaryValue": 100.0,
        "CurrencyCode": "USD"
    },    
    "ShipFrom":{
        "Name": "Sender Name", 
        "Phone": "2133730000", 
        "EmailAddress": "sender@email.com", 
        "Address": {
            "AddressLine1": "1234 Sender Address Ave",
            "City": "Los Angeles",
            "StateProvinceCode": "CA",
            "PostalCode": "92231",            
            "CountryCode": "US"
        }
    },
    "ShipTo":{
        "Name": "Receiver Name", 
        "AttentionName": "Receiver", 
        "EmailAddress": "receiver@gmail.com", 
        "Address": {
            "AddressLine1": "6789 Receiver Address Ave",
            "AddressLine2": "Apt 15",            
            "City": "Burnaby",
            "StateProvinceCode": "BC",
            "PostalCode": "V5H 2P8",            
            "CountryCode": "CA"
        }
    },
    "Package": [
        {
            "PackageWeight": {
                "Weight": 5.0,
                "UnitOfMeasurement": "LBS"            
            },
            "Dimensions": {
                "Length": 7.0, 
                "Width": 8.0, 
                "Height": 9.0,
                "UnitOfMeasurement": "IN"
            }
        }
    ]
}


Puerto Rico Shipping Body
{
    "RequestId": "test_000001",
    "ShipmentDescription": "Content description required",
    "ServiceCode": "03",
    "InvoiceLineTotal": {
        "MonetaryValue": 100.0,
        "CurrencyCode": "USD"
    },    
    "ShipFrom":{
        "Name": "Sender Name", 
        "Phone": "2133730000", 
        "EmailAddress": "sender@email.com", 
        "Address": {
            "AddressLine1": "1234 Sender Address Ave",
            "City": "Los Angeles",
            "StateProvinceCode": "CA",
            "PostalCode": "92231",            
            "CountryCode": "US"
        }
    },
    "ShipTo":{
        "Name": "Receiver Name", 
        "AttentionName": "Receiver", 
        "EmailAddress": "receiver@gmail.com", 
        "Address": {
            "AddressLine1": "6789 Receiver Address Ave",
            "AddressLine2": "Apt 15",            
            "City": "San Juan",
            "StateProvinceCode": "PR",
            "PostalCode": "00925",            
            "CountryCode": "PR"
        }
    },
    "Package": [
        {
            "PackageWeight": {
                "Weight": 5.0,
                "UnitOfMeasurement": "LBS"            
            },
            "Dimensions": {
                "Length": 7.0, 
                "Width": 8.0, 
                "Height": 9.0,
                "UnitOfMeasurement": "IN"
            }
        }
    ]
}



Overseas Shipping Request

The API supports overseas shipping from South Korea toward US. The request requires all fields described for domestic shipping and additionally consider the following:

Field Name Type Required Length/Range Comments
ShipFrom.Address.CountryCode String Yes 2 Allowed: "KR"
Package[i].NumberLabels Integer No 1 ... 50 By default = 1
Package[i].PackageWeight.Weight Number Yes 1 ... 30.0
Package[i].PackageWeight.UnitOfMeasurement String Yes 3 Allowed: KGS
Package[i].Dimensions.UnitOfMeasurement String Yes 2 Allowed: CM
Package[i].Items Array Yes
Package[i].Items[i] Container Yes
Package[i].Items[i].Description String Yes 100
Package[i].Items[i].Quantity Integer Yes 1 ... 99
Package[i].Items[i].ItemWeight Container Yes
Package[i].Items[i].ItemWeight.UnitOfMeasurement String Yes 3 Allowed: KGS
Package[i].Items[i].ItemWeight.Weight Number Yes 1 ... 30.0
Package[i].Items[i].ItemPrice Container Yes
Package[i].Items[i].ItemPrice.CurrencyCode String Yes 3 Allowed: USD
Package[i].Items[i].ItemPrice.MonetaryValue Number Yes 0 ... 50000



Example:


POST /api/v2/shipments/label-request HTTP/1.1
Host: clutchshipper.com
Token: 15576696791511562927-80cb9752-78d6-4fe1-8ed8-97f1e125bfd4
Content-type: application/json


Overseas Shipping Body
{
    "RequestId": "test_000001",
    "ServiceCode": "KRTHZXR",
    "AddressValidation": true,
    "ShipFrom":{
        "Name": "Sender Name", 
        "Phone": "2133730000", 
        "EmailAddress": "sender@email.com", 
        "Address": {
            "AddressLine1": "1234 Sender Address Ave",
            "City": "Seocho District",
            "StateProvinceCode": "SEOUL",
            "PostalCode": "06772",            
            "CountryCode": "KR"
        }
    },
    "ShipTo":{
        "Name": "Receiver Name", 
        "AttentionName": "Receiver", 
        "EmailAddress": "receiver@gmail.com", 
        "Address": {
            "AddressLine1": "6789 Receiver Address Ave",
            "AddressLine2": "Apt 15",            
            "City": "Doral",
            "StateProvinceCode": "FL",
            "PostalCode": "27000",            
            "CountryCode": "US"
        }
    },
    "Package": [
        {
            "NumberLabels": 2,
            "PackageWeight": {
                "Weight": 2.0,
                "UnitOfMeasurement": "KGS"            
            },
            "Dimensions": {
                "Length": 6.0, 
                "Width": 11.0, 
                "Height": 9.0,
                "UnitOfMeasurement": "CM"
            },
            "Items":[
                {
                    "Description": "item 1",
                    "Quantity": 1,
                    "ItemWeight":{
                        "UnitOfMeasurement": "LBS",
                        "Weight": 2.0
                    },
                    "ItemPrice":{            
                        "MonetaryValue": 10,
                        "CurrencyCode": "USD"
                    }
                }
            ]
        }
    ]
}

Response


Field Name Type Comments
RequestId String
ServiceCode String
ShipmentIdentificationNumber String Tracking number of the first package in the shipment
ResidentialAddressIndicator Boolean True = receiver address is residential, Null = unclassified
TotalCharges Container
TotalCharges.MonetaryValue Number
TotalCharges.CurrencyCode String
TotalBillingWeight Container
TotalBillingWeight.Weight Number
TotalBillingWeight.UnitOfMeasurement String
PackageResults Array
PackageResults[i] Container
PackageResults[i].Sequence Integer
PackageResults[i].TrackingNumber String
PackageResults[i].Charge Container
PackageResults[i].Charge.MonetaryValue Number
PackageResults[i].Charge.CurrencyCode String
PackageResults[i].BillingWeight Container
PackageResults[i].BillingWeight.Weight Number
PackageResults[i].BillingWeight.UnitOfMeasurement String



Example

{
    "ResponseResults": {
        "RequestId": "test_000001",
        "ResidentialAddressIndicator": false,
        "ServiceCode": "03",
        "ShipmentIdentificationNumber": "1ZX2402221150301923678045",
        "TotalCharges": {
            "CurrencyCode": "USD",
            "MonetaryValue": "80.48"
        },
        "TotalBillingWeight": {
            "UnitOfMeasurement": "LBS",
            "Weight": 54.0
        },
        "PackageResults": [
            {
                "Sequence": 1,
                "TrackingNumber": "1ZX2402221150301923678045",
                "BillingWeight": {
                    "UnitOfMeasurement": "LBS",
                    "Weight": 40.0
                },
                "Charge": {
                    "CurrencyCode": "USD",
                    "MonetaryValue": "29.64"
                }
            },
            {
                "Sequence": 2,
                "TrackingNumber": "1ZX2402221150302695034271",
                "BillingWeight": {
                    "UnitOfMeasurement": "LBS",
                    "Weight": 7.0
                },
                "Charge": {
                    "CurrencyCode": "USD",
                    "MonetaryValue": "25.42"
                }
            },
            {
                "Sequence": 3,
                "TrackingNumber": "1ZX2402221150303697021384",
                "BillingWeight": {
                    "UnitOfMeasurement": "LBS",
                    "Weight": 7.0
                },
                "Charge": {
                    "CurrencyCode": "USD",
                    "MonetaryValue": "25.42"
                }
            }
        ]
    },
    "ResponseStatus": {
        "Code": 200,
        "Description": "Success",
        "Error": null,
        "Message": null
    }    
}


9. Package Tracking

Method: GET
Route: /v2/shipments/package-tracking

Parameters


Field Name Type Required Length/Range Comments
TrackingNumber String Yes


Example

GET /api/v2/shipments/package-tracking?TrackingNumber=1Z99999999999 HTTP/1.1
Host: clutchshipper.com
Token: 15576696791511562927-80cb9752-78d6-4fe1-8ed8-97f1e125bfd4
Content-type: application/json

Response


Field Name Type Comments
TrackingNumber String Tracking number requested
CurrentStatus Container Status of the latest activity ocurred
CurrentStatus.Condition String See "Status Condition" table
CurrentStatus.Code String See "Status Codes" table
CurrentStatus.Description String See "Status Codes" table
CurrentStatus.Type String See "Status Types" table
Destination Container
Destination.City String
Destination.StateProvinceCode String
Destination.CountryCode String
Origin Container
Origin.City String
Origin.StateProvinceCode String
Origin.CountryCode String
Activity Array Scan activity associated with the Tracking Number
Activity[i] Container
Activity[i].EventTime String Date time when the activity ocurred
Activity[i].Location String Location where activity occurred (city, state, country)
Activity[i].Status Container Status associated to the activity
Activity[i].Status.Code String See "Status Codes" table
Activity[i].Status.Description String See "Status Codes" table
Activity[i].Status.Type String See "Status Types" table


Example

{
    "ResponseResults": {
        "TrackingNumber": "1Z99999999999",
        "CurrentStatus": {
            "Code": "9E",
            "Condition": "FIN",
            "Description": "DELIVERED ",
            "Type": "D"
        },
        "Destination": {
            "City": "SAN DIEGO",
            "CountryCode": "US",
            "StateProvinceCode": "CA"
        },
        "Origin": {
            "City": "CYPRESS",
            "CountryCode": "US",
            "StateProvinceCode": "CA"
        },
        "Activity": [
            {
                "EventTime": "02/22/2024 11:42:05",
                "Location": "SAN DIEGO CA US",
                "Status": {
                    "Code": "9E",
                    "Description": "DELIVERED ",
                    "Type": "D"
                }
            },
            {
                "EventTime": "02/22/2024 09:11:10",
                "Location": "San Diego CA US",
                "Status": {
                    "Code": "OT",
                    "Description": "Out For Delivery Today",
                    "Type": "I"
                }
            },
            {
                "EventTime": "02/22/2024 07:27:44",
                "Location": "San Diego CA US",
                "Status": {
                    "Code": "YP",
                    "Description": "Processing at UPS Facility",
                    "Type": "I"
                }
            },
            {
                "EventTime": "02/22/2024 05:31:00",
                "Location": "San Diego CA US",
                "Status": {
                    "Code": "AR",
                    "Description": "Arrived at Facility",
                    "Type": "I"
                }
            },
            {
                "EventTime": "02/22/2024 03:17:00",
                "Location": "Bell CA US",
                "Status": {
                    "Code": "DP",
                    "Description": "Departed from Facility",
                    "Type": "I"
                }
            },
            {
                "EventTime": "02/21/2024 23:40:00",
                "Location": "Bell CA US",
                "Status": {
                    "Code": "AR",
                    "Description": "Arrived at Facility",
                    "Type": "I"
                }
            },
            {
                "EventTime": "02/21/2024 23:18:00",
                "Location": "Los Angeles CA US",
                "Status": {
                    "Code": "DP",
                    "Description": "Departed from Facility",
                    "Type": "I"
                }
            },
            {
                "EventTime": "02/21/2024 21:37:35",
                "Location": "Los Angeles CA US",
                "Status": {
                    "Code": "OR",
                    "Description": "We have your package",
                    "Type": "I"
                }
            },
            {
                "EventTime": "02/21/2024 18:11:00",
                "Location": "Los Angeles CA US",
                "Status": {
                    "Code": "XD",
                    "Description": "Drop-Off",
                    "Type": "I"
                }
            },
            {
                "EventTime": "02/21/2024 17:54:19",
                "Location": "US",
                "Status": {
                    "Code": "MP",
                    "Description": "Shipper created a label, UPS has not received the package yet. ",
                    "Type": "M"
                }
            }
        ]
    },
    "ResponseStatus": {
        "Code": 200,
        "Description": "Success",
        "Error": null,
        "Message": null
    }
}

Status Condition


Condition Description Comments
FIN Delivered Package delivered
ISS Exception Package was not delivered for some exception
LAB Created Label was created
ING In transit Package is in its way
NAV Not Available Tracking not available
VOD Voided Label was voided


Status Types


UPS

Type Description
D Delivered
I In Transit
M Billing Information Received
MV Billing Information Voided
P Pickup
X Exception
RS Returned to Shipper
NA Not Available
O Out for Delivery


Status Codes


UPS

Code Description
9E DELIVERED
OT Out For Delivery Today
YP Processing at UPS Facility
AR Arrived at Facility
DP Departed from Facility
AR Arrived at Facility
DP Departed from Facility
OR We have your package
XD Drop-Off
MP Shipper created a label, UPS has not received the package yet.


AMAZON

Code Description
ReadyForReceive Ready for Receive
PreTransit Pre Transit
PickupDone Pickup Done
Delivered Delivered
Departed Departed
OutForDelivery Out For Delivery
ArrivedAtCarrierFacility Arrived At Carrier Facility
AvailableForPickup Available For Pickup
PickupCancelled Pickup Cancelled
ReturnInitiated Return Initiated
DeliveryAttempted Delivery Attempted
Lost Lost
Rejected Rejected
Undeliverable Undeliverable
Received Received


Clutch Shipper Overseas

Code Description
0 unknown
1 submitted
2 in transit
3 Signed
4 Received
5 Order canceled
6 Delivery failed
7 Returned

 

 

10. Print Labels

Clutch Shipper API allows to retrieve labels as PDF files for printing. This labels are available for 90 days since the date they were created.

Method: GET
Route: /v2/shipments/label-print


Encoded PDF

By default the API return labels as base64 encoded PDF files which must be decoded for printing at the user side. However, the API is also able to return the PDF as a not encoded binary file if the user requires it. The encoded/decoded selection could be done by adding the field "Encoded" in a print label request. The valid values for this field are:

Value Description Comments
true / 1 PDF base64 encoded This is the default value.
false / 0 PDF binary not encoded



Email the Label

The API allows to email the label by adding the field "EmailLabel" in a regular shipping label request. The valid values for this field are:

Value Description Comments
true / 1 Emails the label
false / 0 None This is the default value.


By default, the label will be send to the sender email address included originally in the shipping label request. However, the API allows to use a different email address by adding in the print label request the field "ShipFromNotificationEmail" with the new email address.

Notifications

The API allows to send email notifications to the receiver by adding the option in a print label request. The valid options are:

options Description
NotifyShipping Sends the email when the package has been shipped
NotifyDelivery Sends the email when the package has been delivered


And the posible values for these options are:

Value Description Comments
true / 1 Emails the Notification
false / 0 None This is the default value.


By default, the notification will be send to the receiver email address included originally in the shipping label request. However, the API allows to use a different email address by adding in the print label request the field "ShipToNotificationEmail" with the new email address.

The API returns the label related to the indicated tracking number.

Parameters


Field Name Type Required Length/Range Comments
TrackingNumber String Yes Tracking number
Encoded boolean No See "Encoded PDF" section
EmailLabel boolean No See "Email the label" section
ShipFromNotificationEmail String No 0 .. 50 See "Email the label" section
NotifyShipping boolean No See "Notifications" section
NotifyDelivery boolean No See "Notifications" section
ShipToNotificationEmail String No 0 .. 50 See "Notifications" section



Examples:


Base64 encoded PDF
GET /api/v2/shipments/label-print?TrackingNumber=1Z99999999999 HTTP/1.1
Host: clutchshipper.com
Token: 15576696791511562927-80cb9752-78d6-4fe1-8ed8-97f1e125bfd4
Content-type: application/json


Binary PDF
GET /api/v2/shipments/label-print?TrackingNumber=1Z99999999999&Encoded=false HTTP/1.1
Host: clutchshipper.com
Token: 15576696791511562927-80cb9752-78d6-4fe1-8ed8-97f1e125bfd4
Content-type: application/json


Email label
GET /api/v2/shipments/label-print?TrackingNumber=1Z99999999999&EmailLabel=true HTTP/1.1
Host: clutchshipper.com
Token: 15576696791511562927-80cb9752-78d6-4fe1-8ed8-97f1e125bfd4
Content-type: application/json


The API returns a compiled pdf of all labels obtained for all packages in one shipping label request.

Parameters


Field Name Type Required Length/Range Comments
RequestId String Yes
Encoded boolean No See "Encoded PDF" section
EmailLabel boolean No See "Email the label" section
ShipFromNotificationEmail String No 0 .. 50 See "Email the label" section
NotifyShipping boolean No See "Notifications" section
NotifyDelivery boolean No See "Notifications" section
ShipToNotificationEmail String No 0 .. 50 See "Notifications" section



Example

GET /api/v2/shipments/label-print?RequestId=0200K5 HTTP/1.1
Host: clutchshipper.com
Token: 15576696791511562927-80cb9752-78d6-4fe1-8ed8-97f1e125bfd4
Content-type: application/json


Response

In case it is required a not encoded pdf, the API just returns the binary file. The following response format is in case of an encoded PDF.

Field Name Type Comments
EncodedLabel String Base64 encoded PDF



Examples:


Encoded PDF
{
    "ResponseStatus": {
        "Code": 200,
        "Description": "Success",
        "Error": null,
        "Message": null
        },
    "ResponseResults": {
       "EncodedLabel": "JVBERi0xLjUKJeLjz9MKMyAwIG9iago8PC9Db2xvclNwYWNlWy9JbmRleGVk..."
       }
}


Decoding a PDF in python
import base64 
def decode_label(response): 
    return(base64.b64decode(response["ResponseResults"]["EncodedLabel"]))


Decoding a PDF in Java Script:
Requires the script: https://cdnjs.cloudflare.com/ajax/libs/pdf-lib/1.17.1/pdf-lib.min.js 
async function decode_pdf (response) { 
  var label = null; 
  if (response.ResponseStatus.Code == 200 && response.ResponseResults != null){ 
  var base64_bytes = response.ResponseResults.EncodedLabel; 
  const {PDFDocument} = PDFLib; 
  const doc= await PDFDocument.load('data:application/octet-stream;base64,' + base64_bytes); 
  label = await doc.save(); 
  } 
  return(label); 
}


11. Inquiry Price

This service is available only for domestic shipping and overseas (KR). The returned carges and billing weights are estimations.

Method: POST
Route: /v2/shipments/price-inquiry

Request Body


Field Name Type Required Length/Range Comments
ServiceCode String No 20 Null = Query all services
ShipFrom Container Yes
ShipFrom.Address Container Yes
ShipFrom.Address.AddressLine1 String Yes 1 ... 35
ShipFrom.Address.AddressLine2 String No 0 ... 35
ShipFrom.Address.City String Yes 1 ... 45
ShipFrom.Address.PostalCode String Yes 5 ... 10 Zip extension not required
ShipFrom.Address.StateCode String Yes 2 U.S. State abbreviation
ShipFrom.Address.CountryCode String Yes 2 Allowed: US, KR
ShipTo Container Yes
ShipTo.Address Container Yes
ShipTo.Address.AddressLine1 String Yes 1 ... 35
ShipTo.Address.AddressLine2 String No 0 ... 35
ShipTo.Address.City String Yes 1 ... 45
ShipTo.Address.PostalCode String Yes 5 ... 10 Zip extension not required
ShipTo.Address.StateCode String Yes 2 U.S. State abbreviation
ShipTo.Address.CountryCode String Yes 2 Allowed: US
Package Array Yes
Package[i] Container Yes
Package[i].NumberLabels Integer No 1 ... 99 By default = 1
Package[i].PackageWeight Container Yes
Package[i].PackageWeight.Weight Number Yes 1 ... 150.0
Package[i].PackageWeight.UnitOfMeasurement String Yes 3 Allowed: LBS, KGS
Package[i].Dimensions Container Yes
Package[i].Dimensions.Length Number Yes 1 ... 99.99
Package[i].Dimensions.Height Number Yes 1 ... 99.99
Package[i].Dimensions.Width Number Yes 1 ... 99.99
Package[i].Dimensions.UnitOfMeasurement String Yes 2 Allowed: IN, CM
Package[i].DeclaredValue Container No
Package[i].DeclaredValue.MonetaryValue Number yes 0 ... 50000
Package[i].DeclaredValue.CurrencyCode String yes 3 Allowed: USD


Examples:


POST /api/v2/shipments/price-inquiry HTTP/1.1
Host: clutchshipper.com
Token: 15576696791511562927-80cb9752-78d6-4fe1-8ed8-97f1e125bfd4
Content-type: application/json

Query all services
{
    "ShipFrom":{
        "Address": {
            "AddressLine1": "1234 Sender Address Ave",
            "City": "Los Angeles",
            "StateCode": "CA",
            "PostalCode": "92231",            
            "CountryCode": "US"}
    },
    "ShipTo":{
        "Address": {
            "AddressLine1": "6789 Receiver Address Ave",
            "AddressLine2": "Apt 15",            
            "City": "Doral",
            "StateCode": "FL",
            "PostalCode": "27000",            
            "CountryCode": "US"}
    },
    "Package": [
        {
        "PackageWeight": {
            "Weight": 5.0,
            "UnitOfMeasurement": "LBS"            
            },
        "Dimensions": {
            "Length": 7.0, 
            "Width": 8.0, 
            "Height": 9.0,
            "UnitOfMeasurement": "IN"
            }
        },
        {
        "NumberLabels": 2,
        "PackageWeight": {
            "Weight": 2.0,
            "UnitOfMeasurement": "LBS"            
            },
        "Dimensions": {
            "Length": 6.0, 
            "Width": 11.0, 
            "Height": 9.0,
            "UnitOfMeasurement": "IN"
            },
        "DeclaredValue":{
            "MonetaryValue": 125.0,
            "CurrencyCode": "USD"
            }
        }
    ]
}

Query a specific service
{
    "ServiceCode": "03",
    "ShipFrom":{
        "Address": {
            "AddressLine1": "1234 Sender Address Ave",
            "City": "Los Angeles",
            "StateCode": "CA",
            "PostalCode": "92231",            
            "CountryCode": "US"}
    },
    "ShipTo":{
        "Address": {
            "AddressLine1": "6789 Receiver Address Ave",
            "AddressLine2": "Apt 15",            
            "City": "Doral",
            "StateCode": "FL",
            "PostalCode": "27000",            
            "CountryCode": "US"}
    },
    "Package": [
        {
        "PackageWeight": {
            "Weight": 5.0,
            "UnitOfMeasurement": "LBS"            
            },
        "Dimensions": {
            "Length": 7.0, 
            "Width": 8.0, 
            "Height": 9.0,
            "UnitOfMeasurement": "IN"
            }
        },
        {
        "NumberLabels": 2,
        "PackageWeight": {
            "Weight": 2.0,
            "UnitOfMeasurement": "LBS"            
            },
        "Dimensions": {
            "Length": 6.0, 
            "Width": 11.0, 
            "Height": 9.0,
            "UnitOfMeasurement": "IN"
            },
        "DeclaredValue":{
            "MonetaryValue": 125.0,
            "CurrencyCode": "USD"
            }
        }
    ]
}

Response

The response is an array where each entry contains the estimated charges for a specific shipping service. The table below shows the fields of each entry.

Field Name Type Comments
ServiceCode String
ResidentialAddressIndicator Boolean True = receiver address is residential, Null = unclassified
TotalCharges Container
TotalCharges.MonetaryValue Number
TotalCharges.CurrencyCode String
TotalBillingWeight Container
TotalBillingWeight.Weight Number
TotalBillingWeight.UnitOfMeasurement String
PackageResults Array
PackageResults[i] Container
PackageResults[i].Charge Container
PackageResults[i].Charge.MonetaryValue Number
PackageResults[i].Charge.CurrencyCode String
PackageResults[i].BillingWeight Container
PackageResults[i].BillingWeight.Weight Number
PackageResults[i].BillingWeight.UnitOfMeasurement String


Example

{
    "ResponseStatus": {
        "Code": 200,
        "Description": "Success",
        "Error": null,
        "Message": null
    },
    "ResponseResults": [
        {
            "ServiceCode": "03",
            "ResidentialAddressIndicator": null,
            "TotalCharges": {
                "CurrencyCode": "USD",
                "MonetaryValue": 31.28
            },
            "TotalBillingWeight": {
                "UnitOfMeasurement": "LBS",
                "Weight": 25.0
            },
            "PackageResults": [
                {
                    "BillingWeight": {
                        "UnitOfMeasurement": "LBS",
                        "Weight": 15.0
                    },
                    "Charge": {
                        "CurrencyCode": "USD",
                        "MonetaryValue": "17.22"
                    }
                },
                {
                    "BillingWeight": {
                        "UnitOfMeasurement": "LBS",
                        "Weight": 10
                    },
                    "Charge": {
                        "CurrencyCode": "USD",
                        "MonetaryValue": "14.06"
                    }
                }
            ]
        },
        {
            "ServiceCode": "12",        
            "ResidentialAddressIndicator": null,
            "TotalCharges": {
                "CurrencyCode": "USD",
                "MonetaryValue": 99.17
            },
            "TotalBillingWeight": {
                "UnitOfMeasurement": "LBS",
                "Weight": 25.0
            },
            "PackageResults": [
                {
                    "BillingWeight": {
                        "UnitOfMeasurement": "LBS",
                        "Weight": 15.0
                    },
                    "Charge": {
                        "CurrencyCode": "USD",
                        "MonetaryValue": "56.57"
                    }
                },
                {
                    "BillingWeight": {
                        "UnitOfMeasurement": "LBS",
                        "Weight": 10
                    },
                    "Charge": {
                        "CurrencyCode": "USD",
                        "MonetaryValue": "42.60"
                    }
                }
            ]
        }
    ]
}


12. Inquiry Balance

Method: GET
Route: /v2/reports/balance

Parameters


Field Name Type Required Length/Range Comments
None None None None None


Example

GET /api/v2/reports/balance HTTP/1.1
Host: clutchshipper.com
Token: 15576696791511562927-80cb9752-78d6-4fe1-8ed8-97f1e125bfd4
Content-type: application/json

Response


Field Name Type Comments
Balance Container
Balance.MonetaryValue Number
Balance.CurrencyCode String


Example

{
    "ResponseStatus": {
        "Code": 200,
        "Description": "Success",
        "Error": null,
        "Message": null
    },
    "ResponseResults": {
        "Balance": {
            "MonetaryValue": 100.26,
            "CurrencyCode": "USD"
            }
    }
}


13. Void Labels

A label can be void only when its status condition did not change from "Created" to another condition.

Method: PUT
Route: /v2/shipments/void

Request Body


Field Name Type Required Length/Range Comments
TrackingNumber String Yes Tracking number


Examples:


PUT /api/v2/shipments/void HTTP/1.1
Host: clutchshipper.com
Token: 15576696791511562927-80cb9752-78d6-4fe1-8ed8-97f1e125bfd4
Content-type: application/json

Body
{
    "TrackingNumber": "1Z000000000000"
}

Response



Field Name Type Comments
VoidedTrackingNumber String


Example

{
    "ResponseStatus": {
        "Code": 200,
        "Description": "Success",
        "Error": null,
        "Message": null
    },
    "ResponseResults": {
        "VoidedTrackingNumber": "1Z000000000000"
    }
}


14. Change Password

To change the account's password, it is required to validate the current user credentials, as well as the session token, and additionally the new password must satisfy the following: At least 8 characters long, a combination of uppercase letters, lowercase letters, numbers, and symbols from this set {@, #, $, !, %, &}

Method: PUT
Route: /v2/accounts/password

Request Header


Field Name Type Comments
Authorization String It requires username and password, both case sensitive, joined, and encoded as a base 64 string.
Syntax: "Basic " + base64_string(username + ":" + password)
Token String The current session token
NewPassword String The new password


Example

PUT /api/v2/accounts/password HTTP/1.1
Host: clutchshipper.com
Authorization: Basic bXlfbmFtZTpteV9wYXNz
Token: 15576696791511562927-80cb9752-78d6-4fe1-8ed8-97f1e125bfd4
NewPassword: newP@55word

Response

If the password was successfully changed, the response code would be 200 for the status "Success".

Examples:


Password Successfully Changed
{
    "ResponseStatus": {
        "Code": 200,
        "Description": "Success",
        "Error": null,
        "Message": "The password has been successfully changed."
    },
    "ResponseResults": null
}

Unauthorized Change Attempt
{
    "ResponseStatus": {
        "Code": 401,
        "Description": "Unauthorized",
        "Error": "Unauthorized",
        "Message": "User not authorized to access the information. (ref: 246.090.451)"
    },
    "ResponseResults": null
}

New Password Does Not Meet Requirements
{
    "ResponseStatus": {
        "Code": 400,
        "Description": "Bad request",
        "Error": "Bad request",
        "Message": "Password must be longer than or equal to 8 characters. (ref: 240.094.018)"
    },
    "ResponseResults": null
}