# Get Single Rate

Use this endpoint to retrieve rates individually from each carrier, allowing for faster queries and enabling you to select the best carriers for your business. While the [`allprice`](/api-references/get-shipment-rates.md) endpoint is functional, we recommend using this endpoint for an improved user experience. Unlike the [`allprice`](/api-references/get-shipment-rates.md) endpoint, which waits for all rates to be returned, this endpoint displays rates as they become available, significantly reducing wait times and enhancing the overall experience.

## Available Couriers

To get started, you need to send a request to retrieve a list of available couriers. Refer to the relevant [documentation](/api-references/get-available-couriers.md) here for detailed instructions on how to make this request and properly integrate it into your workflow. This is the first step toward selecting the right courier for your shipping needs. 

## Requests

### Parameter

The request includes a parameter called `carrier_name`, where you specify the name of the courier you want to query. For example, use the following endpoint format to retrieve prices for a specific carrier:\
`https://delivery-staging.apiideraos.com/api/v2/token/tariffs/getpricesingle/{carrier_name}`

Replace `{carrier_name}` with the actual courier name to retrieve the relevant rates.

### Payload

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/getpricesingle/fedex' \
--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/getpricesingle/fedex"

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/getpricesingle/fedex")

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/getpricesingle/fedex',
  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/getpricesingle/fedex", 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/getpricesingle/fedex"
  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 type field is required., The to address.name field is required., The to address.email field is required., The to address.address field is required., The to address.phone field is required., The from address.name field is required., The from address.email field is required., The from address.address field is required., The from address.phone field is required., The parcels.width field is required., The parcels.length field is required., The parcels.height field is required., The parcels.weight field is required., The items field is required."
}
```

{% endtab %}

{% tab title="200" %}

```json
{
    "data": {
        "redis_key": "2c89e045-3a84-4316-923a-7729edbe4e21",
        "rates": {
            "courier": {
                "id": "2c89e045-3a84-4316-923a-7729edbe4e21",
                "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": "2c89e045-3a84-4316-923a-7729edbe4e21",
            "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"
            ],
            "redis_key": "2c89e045-3a84-4316-923a-7729edbe4e21",
            "tax": 365,
            "Surcharge": 1176,
            "dollarAmount": 3.19,
            "originalAmount": null
        },
        "get_rates_key": "2c89e045-3a84-4316-923a-7729edbe4e21",
        "podPercentage": 2.5,
        "completed": true
    },
    "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-single-rate.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.