Get Single Rate

Call a single rate individually, rather than waiting on all rates to show up.

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 endpoint is functional, we recommend using this endpoint for an improved user experience. Unlike the allprice 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 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:

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

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

Curl

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": "[e-mail]",
    "address": "Lekki phase 1, Lekki, Nigeria",
    "phone": "09012344467"
  },
  "fromAddress": {
    "name": "mary john",
    "email": "[e-mail]",
    "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"
    }
  ]
}'

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": "[e-mail]",
    "address": "Lekki phase 1, Lekki, Nigeria",
    "phone": "09012344467"
  },
  "fromAddress": {
    "name": "mary john",
    "email": "[e-mail]",
    "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)

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": "[e-mail]",
    "address": "Lekki phase 1, Lekki, Nigeria",
    "phone": "09012344467"
  },
  "fromAddress": {
    "name": "mary john",
    "email": "[e-mail]",
    "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

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": "[e-mail]",
    "address": "Lekki phase 1, Lekki, Nigeria",
    "phone": "09012344467"
  },
  "fromAddress": {
    "name": "mary john",
    "email": "[e-mail]",
    "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;

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": "[e-mail]",
    "address": "Lekki phase 1, Lekki, Nigeria",
    "phone": "09012344467"
  },
  "fromAddress": {
    "name": "mary john",
    "email": "[e-mail]",
    "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));

Golang

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": "[e-mail]",
    "address": "Lekki phase 1, Lekki, Nigeria",
    "phone": "09012344467"
  },
  "fromAddress": {
    "name": "mary john",
    "email": "[e-mail]",
    "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))
}

Response Sample

422

{
    "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."
}

200

{
    "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
}

404

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