# Get Shipment Rates

## Payload Description

Here's the documentation for the payload in a tabular form:

<table data-header-hidden><thead><tr><th width="161"></th><th width="99"></th><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Field</strong></td><td><strong>Type</strong></td><td><strong>Required</strong></td><td><strong>Validation Rules</strong></td><td><strong>Description</strong></td></tr><tr><td><code>type</code></td><td>String</td><td>Yes</td><td>Must be one of <code>interstate</code>, <code>intrastate</code>, <code>international_us</code>, <code>frozen-international</code>, <code>international</code></td><td>The type of shipment.</td></tr><tr><td><code>toAddress.name</code></td><td>String</td><td>Yes</td><td>Max length: 255</td><td>Recipient's name.</td></tr><tr><td><code>toAddress.email</code></td><td>String</td><td>Yes</td><td>Must be a valid email address, Max length: 255</td><td>Recipient's email.</td></tr><tr><td><code>toAddress.address</code></td><td>String</td><td>Yes</td><td>Max length: 255</td><td>Recipient's address.</td></tr><tr><td><code>toAddress.phone</code></td><td>String</td><td>Yes</td><td>Must match the regex: <code>^\d{11}$</code> (11 digits)</td><td>Recipient's phone number.</td></tr><tr><td><code>fromAddress.name</code></td><td>String</td><td>Yes</td><td>Max length: 255</td><td>Sender's name.</td></tr><tr><td><code>fromAddress.email</code></td><td>String</td><td>Yes</td><td>Must be a valid email address, Max length: 255</td><td>Sender's email.</td></tr><tr><td><code>fromAddress.address</code></td><td>String</td><td>Yes</td><td>Max length: 255</td><td>Sender's address.</td></tr><tr><td><code>fromAddress.phone</code></td><td>String</td><td>Yes</td><td>Must match the regex: <code>^\d{11}$</code> (11 digits)</td><td>Sender's phone number.</td></tr><tr><td><code>parcels.width</code></td><td>Numeric</td><td>Yes</td><td>Must be a number, Minimum value: 1</td><td>Parcel width.</td></tr><tr><td><code>parcels.length</code></td><td>Numeric</td><td>Yes</td><td>Must be a number, Minimum value: 1</td><td>Parcel length.</td></tr><tr><td><code>parcels.height</code></td><td>Numeric</td><td>Yes</td><td>Must be a number, Minimum value: 1</td><td>Parcel height.</td></tr><tr><td><code>parcels.weight</code></td><td>Numeric</td><td>Yes</td><td>Must be a number, Minimum value: 0.01</td><td>Parcel weight.</td></tr><tr><td><code>items</code></td><td>Array</td><td>Yes</td><td>Must be an array, Minimum of 1 item</td><td>List of items.</td></tr><tr><td><code>items.*.name</code></td><td>String</td><td>Yes</td><td>Max length: 255</td><td>Item name.</td></tr><tr><td><code>items.*.description</code></td><td>String</td><td>No</td><td>Optional</td><td>Item description.</td></tr><tr><td><code>items.*.weight</code></td><td>Numeric</td><td>Yes</td><td>Must be a number, Minimum value: 0.01</td><td>Item weight.</td></tr><tr><td><code>items.*.category</code></td><td>String</td><td>Yes</td><td>Max length: 255</td><td>Item category.</td></tr><tr><td><code>items.*.amount</code></td><td>Numeric</td><td>Yes</td><td>Must be a number, Minimum value: 500</td><td>Item amount (price).</td></tr><tr><td><code>items.*.quantity</code></td><td>Integer</td><td>Yes</td><td>Must be an integer, Minimum value: 1</td><td>Item quantity.</td></tr><tr><td><code>items.*.hscode</code></td><td>Array</td><td>Yes, If type is international</td><td>Must be an array</td><td><a href="/pages/gSVPqMUIcaTQeRVtXnPW">See Hscode docs here</a></td></tr><tr><td><code>items.*.hscode.category</code></td><td>String</td><td>Yes, If type is international</td><td>Must be a string</td><td><a href="/pages/gSVPqMUIcaTQeRVtXnPW">See Hscode docs here</a></td></tr><tr><td><code>items.*.hscode.subcategory</code></td><td>String</td><td>Yes, If type is international</td><td>Must be a string</td><td><a href="/pages/gSVPqMUIcaTQeRVtXnPW">See Hscode docs here</a></td></tr><tr><td><code>items.*.hscode.code</code></td><td>String</td><td>Yes, If type is international</td><td>Must be a size 6 integer/codee</td><td><a href="/pages/gSVPqMUIcaTQeRVtXnPW">See Hscode docs here</a></td></tr></tbody></table>

#### Notes:

* The **phone** fields for both the `toAddress` and `fromAddress` must contain exactly 11 digits, enforced by a regular expression.
* **Parcel dimensions** (width, length, height) and **weight** must be numeric, with weight having a minimum value of `0.01`.
* **Items** require at least one entry in the array, and each item has specific validations for its name, description, weight, category, amount (minimum 500), and quantity (minimum 1).
* **interstate**: Shipping between different states within the same country.
* **intrastate**: Shipping within a single state.
* **international\_us**: Shipping within the United States.
* **international**: Shipping between different countries.
* **frozen-international**: Shipping frozen items (e.g., foodstuffs) internationally. Supported countries include shipping from Nigeria to the US, Canada, and the UK.

## Request Sample

{% tabs %}
{% tab title="Curl" %}

```javascript
curl --location 'https://delivery-staging.apiideraos.com/api/v2/token/tariffs/allprice' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Secret Key' \
--data-raw '{
  "type": "intrastate",
  "toAddress": {
    "name": "hey mary",
    "email": "ola@gmail.com",
    "address": "Lekki phase 1, Lekki, Nigeria",
    "phone": "09012344467"
  },
  "fromAddress": {
    "name": "mary john",
    "email": "john@gmail.com",
    "address": "Victoria island, Lagos, Nigeria",
    "phone": "09123456789"
  },
  "parcels": {
    "width": 32.5,
    "length": 32.5,
    "height": 32.5,
    "weight": "2"
  },
  "items": [
    {
      "name": "item 1",
      "description": "item 1",
      "weight": "506.0",
      "category": "beauty",
      "amount": "46000000.0",
      "quantity": "23"
    }
  ]
}'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import json

url = "https://delivery-staging.apiideraos.com/api/v2/token/tariffs/allprice"

payload = json.dumps({
  "type": "intrastate",
  "toAddress": {
    "name": "hey mary",
    "email": "ola@gmail.com",
    "address": "Lekki phase 1, Lekki, Nigeria",
    "phone": "09012344467"
  },
  "fromAddress": {
    "name": "mary john",
    "email": "john@gmail.com",
    "address": "Victoria island, Lagos, Nigeria",
    "phone": "09123456789"
  },
  "parcels": {
    "width": 32.5,
    "length": 32.5,
    "height": 32.5,
    "weight": "2"
  },
  "items": [
    {
      "name": "item 1",
      "description": "item 1",
      "weight": "506.0",
      "category": "beauty",
      "amount": "46000000.0",
      "quantity": "23"
    }
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer Secret Key'
}

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

print(response.text)

```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require "uri"
require "json"
require "net/http"

url = URI("https://delivery-staging.apiideraos.com/api/v2/token/tariffs/allprice")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer Secret Key"
request.body = JSON.dump({
  "type": "intrastate",
  "toAddress": {
    "name": "hey mary",
    "email": "ola@gmail.com",
    "address": "Lekki phase 1, Lekki, Nigeria",
    "phone": "09012344467"
  },
  "fromAddress": {
    "name": "mary john",
    "email": "john@gmail.com",
    "address": "Victoria island, Lagos, Nigeria",
    "phone": "09123456789"
  },
  "parcels": {
    "width": 32.5,
    "length": 32.5,
    "height": 32.5,
    "weight": "2"
  },
  "items": [
    {
      "name": "item 1",
      "description": "item 1",
      "weight": "506.0",
      "category": "beauty",
      "amount": "46000000.0",
      "quantity": "23"
    }
  ]
})

response = https.request(request)
puts response.read_body

```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://delivery-staging.apiideraos.com/api/v2/token/tariffs/allprice',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "type": "intrastate",
  "toAddress": {
    "name": "hey mary",
    "email": "ola@gmail.com",
    "address": "Lekki phase 1, Lekki, Nigeria",
    "phone": "09012344467"
  },
  "fromAddress": {
    "name": "mary john",
    "email": "john@gmail.com",
    "address": "Victoria island, Lagos, Nigeria",
    "phone": "09123456789"
  },
  "parcels": {
    "width": 32.5,
    "length": 32.5,
    "height": 32.5,
    "weight": "2"
  },
  "items": [
    {
      "name": "item 1",
      "description": "item 1",
      "weight": "506.0",
      "category": "beauty",
      "amount": "46000000.0",
      "quantity": "23"
    }
  ]
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer Secret Key'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

```

{% endtab %}

{% tab title="Javascript" %}

```javascript
const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "Bearer Secret Key");

const raw = JSON.stringify({
  "type": "intrastate",
  "toAddress": {
    "name": "hey mary",
    "email": "ola@gmail.com",
    "address": "Lekki phase 1, Lekki, Nigeria",
    "phone": "09012344467"
  },
  "fromAddress": {
    "name": "mary john",
    "email": "john@gmail.com",
    "address": "Victoria island, Lagos, Nigeria",
    "phone": "09123456789"
  },
  "parcels": {
    "width": 32.5,
    "length": 32.5,
    "height": 32.5,
    "weight": "2"
  },
  "items": [
    {
      "name": "item 1",
      "description": "item 1",
      "weight": "506.0",
      "category": "beauty",
      "amount": "46000000.0",
      "quantity": "23"
    }
  ]
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("https://delivery-staging.apiideraos.com/api/v2/token/tariffs/allprice", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
```

{% endtab %}

{% tab title="Golang" %}

```go
package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://delivery-staging.apiideraos.com/api/v2/token/tariffs/allprice"
  method := "POST"

  payload := strings.NewReader(`{
  "type": "intrastate",
  "toAddress": {
    "name": "hey mary",
    "email": "ola@gmail.com",
    "address": "Lekki phase 1, Lekki, Nigeria",
    "phone": "09012344467"
  },
  "fromAddress": {
    "name": "mary john",
    "email": "john@gmail.com",
    "address": "Victoria island, Lagos, Nigeria",
    "phone": "09123456789"
  },
  "parcels": {
    "width": 32.5,
    "length": 32.5,
    "height": 32.5,
    "weight": "2"
  },
  "items": [
    {
      "name": "item 1",
      "description": "item 1",
      "weight": "506.0",
      "category": "beauty",
      "amount": "46000000.0",
      "quantity": "23"
    }
  ]
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("Authorization", "Bearer Secret Key")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}
```

{% endtab %}
{% endtabs %}

## Response Sample

{% tabs %}
{% tab title="422" %}

```json
{
    "status": false,
    "message": "The to address.phone format is invalid., The from address.phone format is invalid., The parcels.weight must be at least 0.01."
}
```

{% endtab %}

{% tab title="200" %}

```json
{
    "data": {
        "rates": [
            {
                "courier": {
                    "id": "66e957668dbb3",
                    "name": "Dane",
                    "icon": "https://delivery-staging.apiideraos.com/partners/dane.jpeg"
                },
                "amount": 3227,
                "service_charge": 500,
                "delivery_note": null,
                "id": "66e957668dbb3",
                "type": "Dane",
                "currency": "NGN",
                "status": true,
                "estimated_days": "Estimated Days: Within 24hrs",
                "eta": 1,
                "rating": 3.4,
                "pickup": "Same day if booked earlier in the day (on or before 1pm)",
                "dropoff": false,
                "tags": [
                    "Fast",
                    "Local"
                ],
                "tax": 243,
                "dollarAmount": 1.71
            },
            {
                "courier": {
                    "id": "66e95766c63a3",
                    "name": "Uber",
                    "icon": "https://delivery-staging.apiideraos.com/partners/Uber.png"
                },
                "amount": 4272,
                "delivery_note": null,
                "id": "66e95766c63a3",
                "type": "Uber",
                "currency": "NGN",
                "service_charge": 500,
                "status": true,
                "estimated_days": "Estimated Days: Within 4 - 5 hrs",
                "eta": 1,
                "rating": 3.9,
                "pickup": "Pickup is achieved as soon as possible",
                "dropoff": false,
                "tags": [
                    "Convenient",
                    "On Demand",
                    "Speedy"
                ],
                "tax": 258,
                "Surcharge": 832,
                "dollarAmount": 2.26
            },
            {
                "courier": {
                    "id": "66e95766eba86",
                    "name": "Amstel",
                    "icon": "https://delivery-staging.apiideraos.com/partners/amstel.png"
                },
                "amount": 3763,
                "delivery_note": null,
                "service_charge": 500,
                "id": "66e95766eba86",
                "type": "Amstel",
                "currency": "NGN",
                "status": true,
                "estimated_days": "Estimated Days:  Within 24hrs",
                "eta": 1,
                "rating": 3.8,
                "pickup": "Same day if booked earlier in the day (on or before 1pm)",
                "dropoff": false,
                "tags": [
                    "Fast",
                    "Local"
                ],
                "tax": 283,
                "dollarAmount": 1.99
            },
            {
                "status": false,
                "message": "Mavex disabled"
            },
            {
                "status": false,
                "message": "Snap cannot service this shipment. Disabled"
            },
            {
                "courier": {
                    "id": "66e95766ebdcb",
                    "delivery_type_id": null,
                    "name": "ShapShap",
                    "icon": "https://delivery-staging.apiideraos.com/partners/shapshap.png"
                },
                "amount": 2903,
                "fee": 500,
                "actual_amount": 2200,
                "delivery_note": null,
                "id": "66e95766ebdcb",
                "redis_key": "008c4cc7-a7e5-4958-827c-c12b61fe276b",
                "currency": "NGN",
                "type": "shapshap",
                "status": true,
                "estimated_days": "2 - 3 working days",
                "eta": 3,
                "rating": 3,
                "pickup": "Same day if booked earlier in the day (on or before 1pm)",
                "dropoff": false,
                "tags": [
                    "Moderate",
                    "Local",
                    "Save"
                ],
                "tax": 218,
                "dollarAmount": 1.54
            },
            {
                "status": false,
                "message": "Dhl cannot service this shipment at this time your addresses.",
                "type": "dhl"
            },
            {
                "courier": {
                    "id": "0457bdce-003d-4732-a4a4-e663ef0341ad",
                    "name": "Courierplus",
                    "icon": "https://delivery-staging.apiideraos.com/partners/courierplus.png"
                },
                "amount": 1740,
                "service_charge": 500,
                "delivery_note": null,
                "id": "0457bdce-003d-4732-a4a4-e663ef0341ad",
                "type": "Courierplus",
                "origin": "LOS",
                "status": true,
                "destination": "LOS",
                "currency": "NGN",
                "estimated_days": "Estimated days: 3 - 5 days",
                "eta": 7,
                "rating": 3.4,
                "pickup": "Wtihin 24 working hours",
                "dropoff": false,
                "tags": [
                    "Save",
                    "Reliable"
                ],
                "tax": 131,
                "dollarAmount": 0.92
            },
            {
                "status": false,
                "message": "Tranex cannot service this shipment. Disabled"
            },
            {
                "status": false,
                "message": "Prostar cannot service this shipment, parcel is below required weight."
            },
            {
                "courier": {
                    "id": "66e9576892c9e",
                    "name": "ABC",
                    "icon": "https://delivery-staging.apiideraos.com/partners/abc.jpg"
                },
                "amount": 6259,
                "delivery_note": null,
                "VAT": 162,
                "Insurance": 230000,
                "id": "66e9576892c9e",
                "type": "ABC",
                "currency": "NGN",
                "status": true,
                "redis_key": "547ce46c-b0c3-4782-bd82-4375a0d53dea",
                "estimated_days": "Estimated Days: 2 - 5 days",
                "eta": 5,
                "rating": 3.5,
                "pickup": "Dropoff Required",
                "dropoff": true,
                "tags": [
                    "Save",
                    "Local"
                ],
                "tax": 470,
                "dollarAmount": 3.31
            },
            {
                "courier": {
                    "id": "66e95768b5492",
                    "name": "Errandlr",
                    "icon": "https://delivery-staging.apiideraos.com/partners/errandlr.png",
                    "geoId": "nMGut1BRrhJiuw9wmVWlFg=="
                },
                "amount": 2150,
                "delivery_note": null,
                "id": "66e95768b5492",
                "type": "Errandlr",
                "currency": "NGN",
                "redis_key": "nMGut1BRrhJiuw9wmVWlFg==66e95768b548f",
                "status": true,
                "estimated_days": "Estimated Days: Next Day",
                "eta": 2,
                "rating": 3.7,
                "pickup": "Wtihin 24 working hours",
                "dropoff": false,
                "tags": [
                    "Fast",
                    "Reliable"
                ],
                "tax": 162,
                "dollarAmount": 1.14
            },
            {
                "courier": {
                    "id": "66e95768b5496",
                    "name": "Errandlr Economy",
                    "icon": "https://delivery-staging.apiideraos.com/partners/errandlr.png",
                    "geoId": "nMGut1BRrhJiuw9wmVWlFg=="
                },
                "amount": 2473,
                "delivery_note": null,
                "id": "66e95768b5496",
                "type": "Errandlr",
                "currency": "NGN",
                "redis_key": "nMGut1BRrhJiuw9wmVWlFg==66e95768b548f",
                "status": true,
                "estimated_days": "Estimated Days:  2 - 3 Days",
                "eta": 3,
                "rating": 3.7,
                "pickup": "Wtihin 24 working hours",
                "dropoff": false,
                "tags": [
                    "Fast",
                    "Reliable"
                ],
                "tax": 186,
                "dollarAmount": 1.31
            },
            {
                "status": false,
                "message": "SKI cannot service this shipment."
            },
            {
                "courier": {
                    "id": "f373adb2-1831-4384-b788-03e7f20283b8",
                    "name": "Dellyman",
                    "icon": "https://delivery-staging.apiideraos.com/partners/dellyman.jpeg"
                },
                "amount": 2473,
                "service_charge": 500,
                "delivery_note": null,
                "id": "f373adb2-1831-4384-b788-03e7f20283b8",
                "type": "Dellyman",
                "currency": "NGN",
                "status": true,
                "estimated_days": "Estimated days: 2 - 5 days",
                "eta": 5,
                "rating": 3.8,
                "pickup": "Pickup is achieved as soon as possible",
                "dropoff": false,
                "tags": [
                    "Convenient",
                    "On Demand",
                    "Save"
                ],
                "tax": 186,
                "dollarAmount": 1.31
            },
            {
                "status": false,
                "message": "Undefined array key 0"
            },
            {
                "status": false,
                "message": "Dhl cannot service this shipment at this time your addresses.",
                "type": "dhl"
            },
            {
                "courier": {
                    "id": "18e8d530-ceed-4ce6-b3cf-df23b7506aa7",
                    "name": "Fedex",
                    "icon": "https://delivery-staging.apiideraos.com/partners/redstar.png"
                },
                "amount": 6038,
                "service_charge": 500,
                "actual_amount": 2160,
                "delivery_note": "This carrier will need you to print out the waybill.",
                "id": "18e8d530-ceed-4ce6-b3cf-df23b7506aa7",
                "type": "Fedex",
                "pod": true,
                "currency": "NGN",
                "status": true,
                "estimated_days": "Estimated days: 7 to 14 days – Doorstep",
                "eta": 14,
                "rating": 3,
                "pickup": "Wtihin 24-48 working hours",
                "dropoff": false,
                "tags": [
                    "Moderate",
                    "Reliable"
                ],
                "tax": 365,
                "Surcharge": 1176,
                "dollarAmount": 3.19
            },
            {
                "courier": {
                    "id": "66e9576cf2ca4",
                    "name": "Ups Standard",
                    "icon": "https://delivery-staging.apiideraos.com/partners/ups.png"
                },
                "amount": 6714,
                "delivery_note": null,
                "id": "66e9576cf2ca4",
                "type": "Ups",
                "currency": "NGN",
                "redis_key": "66e9576cf2ca2",
                "status": true,
                "estimated_days": "Estimated Days: 3 - 7 Days",
                "eta": 2,
                "rating": 3.3,
                "pickup": "Pickup is achieved as soon as possible",
                "dropoff": false,
                "tags": [
                    "Fast",
                    "Reliable",
                    "Global"
                ],
                "tax": 504,
                "dollarAmount": 3.55
            },
            {
                "courier": {
                    "id": "66e9576cf2ca4",
                    "name": "Ups Saver",
                    "icon": "https://delivery-staging.apiideraos.com/partners/ups.png"
                },
                "amount": 7628,
                "delivery_note": null,
                "id": "66e9576cf2ca4",
                "type": "Ups",
                "currency": "NGN",
                "redis_key": "66e9576cf2ca2",
                "status": true,
                "estimated_days": "Estimated Days: 3 - 10 Days",
                "eta": 2,
                "rating": 3.3,
                "pickup": "Pickup is achieved as soon as possible",
                "dropoff": false,
                "tags": [
                    "Fast",
                    "Reliable",
                    "Global"
                ],
                "tax": 573,
                "dollarAmount": 4.04
            },
            {
                "status": false,
                "message": "This flat rate is not available for you."
            }
        ],
        "kwik_key": null,
        "redis_key": "4416af8a-4ab3-4063-b880-995a65273cd6",
        "get_rates_key": "4e7feab7-e758-4d0d-8b83-5e3aa7dc9d49",
        "podPercentage": 2.5
    },
    "status": true,
    "message": "OK",
    "status_code": 200
}
```

{% endtab %}

{% tab title="404" %}

```json
{
    "status": false,
    "message": "Invalid route or endpoint not found",
    "status_code": 404
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.goshiip.com/api-references/get-shipment-rates.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.