Skip to content

Rates

The /rates endpoint is used to get a rate (quote) for a given shipment. This is useful to get an estimate of the cost, delivery time and available services for the packages intended to be shipped. You need to provide at least the package specs (dimensions and weight) as well as the origin and the destination.

Request a rate

This can be acheived with a simple POST /v1/rates

curl --request POST \
  --url https://api.purplship.com/v1/rates \
  --header 'authorization: Token <your api token>' \
  --header 'content-type: application/json' \
  --data '{
    "shipper": {
        "postal_code":"H4J1G4", 
        "country_code":"CA", 
        "city": "Montreal"
    },
    "recipient": {
        "postal_code":"89109", 
        "city":"Las Vegas", 
        "country_code":"US"
    },
    "shipment": {
        "items": [
            {
                "id":"1", 
                "height":3, 
                "length":10, 
                "width":3,
                "weight":4.0
            }
        ], 
        "is_document": true
    },
    "carriers": []
}'
var http = require("http");

var options = {
  "method": "POST",
  "hostname": "api.purplship.com",
  "path": "/v1/rates",
  "headers": {
    "content-type": "application/json",
    "content-length": "355",
    "authorization": "Token <your api token>"
  }
};

var req = http.request(options, function (res) {
  var chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    var body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({ 
    shipper: { postal_code: 'H4J1G4', country_code: 'CA', city: 'Montreal' },
    recipient: { postal_code: '89109', city: 'Las Vegas', country_code: 'US' },
    shipment: 
        { 
            packages: [ 
                { id: '1', height: 3, length: 10, width: 3, weight: 4 } 
            ],
            is_document: true 
        },
        carriers: [] // empty list means all configured carriers
    }));
req.end();
import requests

url = "https://api.purplship.com/v1/rates"

payload = """{
    "shipper": {
        "postal_code":"H4J1G4", 
        "country_code":"CA", 
        "city": "Montreal"
    },
    "recipient": {
        "postal_code":"89109", 
        "city":"Las Vegas", 
        "country_code":"US"
    },
    "shipment": {
        "items": [
            {
                "id":"1", 
                "height":3, 
                "length":10, 
                "width":3,
                "weight":4.0
            }
        ], 
        "is_document": true
    },
    "carriers": [] # empty list means all configured carriers
}"""
headers = {
    'content-type': "application/json",
    'authorization': "Token <your api token>"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{
    "shipper": {
        "postal_code":"H4J1G4", 
        "country_code":"CA", 
        "city": "Montreal"
    },
    "recipient": {
        "postal_code":"89109", 
        "city":"Las Vegas", 
        "country_code":"US"
    },
    "shipment": {
        "items": [
            {
                "id":"1", 
                "height":3, 
                "length":10, 
                "width":3,
                "weight":4.0
            }
        ], 
        "is_document": true
    },
    "carriers": []
}');

$request->setRequestUrl('https://api.purplship.com/v1/rates');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders(array(
  'authorization' => 'Token <your api token>',
  'content-type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

Response

{
    "errors": [
        {
            "carrier": "CanadaPost",
            "code": "Server",
            "message": "postal-code value '89109' is not a valid instance of type PostalCodeType"
        }
    ],
    "quotes": [
        {
            "base_charge": 927.9,
            "carrier": "UPS",
            "currency": "USD",
            "delivery_date": null,
            "discount": 776.36,
            "duties_and_taxes": 595.1800000000001,
            "extra_charges": [
                {
                    "amount": 776.36,
                    "currency": "USD",
                    "name": "DSCNT"
                },
                {
                    "amount": 480.0,
                    "currency": "USD",
                    "name": "HOL_WE_PU_DEL"
                },
                {
                    "amount": 85.18,
                    "currency": "USD",
                    "name": "2"
                },
                {
                    "amount": 30.0,
                    "currency": "USD",
                    "name": "CA_BORDER"
                }
            ],
            "service_name": "UPS_Freight_LTL_Guaranteed",
            "service_type": "309",
            "total_charge": 332.72
        },
        {
            "base_charge": 62.66,
            "carrier": "DHL",
            "currency": "CAD",
            "delivery_date": "2018-10-25 10:30:00",
            "discount": 0,
            "duties_and_taxes": 0,
            "extra_charges": [
                {
                    "amount": 8.0,
                    "currency": "CAD",
                    "name": "10:30 PREMIUM"
                },
                {
                    "amount": 5.12,
                    "currency": "CAD",
                    "name": "FUEL SURCHARGE"
                }
            ],
            "service_name": "EXPRESS 10:30 DOC",
            "service_type": "TD",
            "total_charge": 75.78
        },
        {
            "base_charge": 62.66,
            "carrier": "DHL",
            "currency": "CAD",
            "delivery_date": "2018-10-25 12:00:00",
            "discount": 0,
            "duties_and_taxes": 0,
            "extra_charges": [
                {
                    "amount": 3.0,
                    "currency": "CAD",
                    "name": "12:00 PREMIUM"
                },
                {
                    "amount": 4.76,
                    "currency": "CAD",
                    "name": "FUEL SURCHARGE"
                }
            ],
            "service_name": "EXPRESS 12:00 DOC",
            "service_type": "TD",
            "total_charge": 70.42
        },
        {
            "base_charge": 62.66,
            "carrier": "DHL",
            "currency": "CAD",
            "delivery_date": "2018-10-25 11:59:00",
            "discount": 0,
            "duties_and_taxes": 0,
            "extra_charges": [
                {
                    "amount": 4.54,
                    "currency": "CAD",
                    "name": "FUEL SURCHARGE"
                }
            ],
            "service_name": "EXPRESS WORLDWIDE DOC",
            "service_type": "TD",
            "total_charge": 67.2
        },
        {
            "base_charge": 64.51,
            "carrier": "DHL",
            "currency": "CAD",
            "delivery_date": "2018-10-25 11:59:00",
            "discount": 0,
            "duties_and_taxes": 0,
            "extra_charges": [],
            "service_name": "EXPRESS EASY DOC",
            "service_type": "TD",
            "total_charge": 64.51
        },
        {
            "base_charge": 172.22,
            "carrier": "Fedex",
            "currency": "USD",
            "delivery_date": null,
            "discount": 0.0,
            "duties_and_taxes": 0.0,
            "extra_charges": [
                {
                    "amount": 14.21,
                    "currency": "USD",
                    "name": "FUEL"
                }
            ],
            "service_name": "INTERNATIONAL_FIRST",
            "service_type": "PAYOR_ACCOUNT_SHIPMENT",
            "total_charge": 186.43
        },
        {
            "base_charge": 91.57,
            "carrier": "Fedex",
            "currency": "USD",
            "delivery_date": null,
            "discount": 0.0,
            "duties_and_taxes": 0.0,
            "extra_charges": [
                {
                    "amount": 7.55,
                    "currency": "USD",
                    "name": "FUEL"
                }
            ],
            "service_name": "INTERNATIONAL_PRIORITY",
            "service_type": "PAYOR_ACCOUNT_SHIPMENT",
            "total_charge": 99.12
        },
        {
            "base_charge": 69.11,
            "carrier": "Fedex",
            "currency": "USD",
            "delivery_date": null,
            "discount": 0.0,
            "duties_and_taxes": 0.0,
            "extra_charges": [
                {
                    "amount": 5.71,
                    "currency": "USD",
                    "name": "FUEL"
                }
            ],
            "service_name": "INTERNATIONAL_ECONOMY",
            "service_type": "PAYOR_ACCOUNT_SHIPMENT",
            "total_charge": 74.82
        },
        {
            "base_charge": 26.15,
            "carrier": "Fedex",
            "currency": "USD",
            "delivery_date": null,
            "discount": 0.0,
            "duties_and_taxes": 0.0,
            "extra_charges": [
                {
                    "amount": 1.63,
                    "currency": "USD",
                    "name": "FUEL"
                }
            ],
            "service_name": "FEDEX_GROUND",
            "service_type": "PAYOR_ACCOUNT_PACKAGE",
            "total_charge": 27.78
        }
    ]
}

Tip

Visit the API reference for further details about the request parameters.