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.

Print a Label by its Tracking Number

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

Print All Labels of a Request

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
}