> For the complete documentation index, see [llms.txt](https://docs.shipbubble.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shipbubble.com/api-reference/rates/request-shipping-rates.md).

# Request shipping rates

Things to note: 

* Shipment rates requested after 6 PM (GMT +1) will be scheduled for processing the following day.
* You can only request a shipment for a maximum of 7 days from the current date of request.
* The successful rate response will indicate which courier is the cheapest, fastest, and best value for money, which is a combination of speed, price, and reliability.
* A rate request token expires after 7 days of generation.

{% hint style="warning" %}
**For your package items**

Strive to be as accurate as possible when shipping! The more accurate your information is, the better the rate quote you will receive from the couriers.

Additionally, if the shipping information is incorrect, most carriers will follow up with a charge to make up the difference.
{% endhint %}

<mark style="color:green;">`POST`</mark> `https://api.shipbubble.com/v1/shipping/fetch_rates`

#### Request Body

| Name                                                      | Type   | Description                                                                                                                                                                                                                                     |
| --------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sender\_address\_code<mark style="color:red;">\*</mark>   | int    | address code of label pickup (gotten from **Addresses API**)                                                                                                                                                                                    |
| reciever\_address\_code<mark style="color:red;">\*</mark> | int    | address code of label pickup (gotten from **Addresses API**)                                                                                                                                                                                    |
| pickup\_date<mark style="color:red;">\*</mark>            | string | specified date for shipment processing(format: "**yyyy-mm-dd**")                                                                                                                                                                                |
| category\_id<mark style="color:red;">\*</mark>            | int    | package item category                                                                                                                                                                                                                           |
| package\_items<mark style="color:red;">\*</mark>          | Array  | An array of items to be shipped, a sample package item object looks like **`{ name:'Jameson', description:'Too sweet', unit_weight:'0.002', unit_amount:'5000', quantity:'2' }`**, all object items are required, item weight unit is in **KG** |
| service\_type                                             | string | filter rates by their service types ex. **dropoff** or **pickup**                                                                                                                                                                               |
| delivery\_instructions                                    | string | additional delivery instructions for package                                                                                                                                                                                                    |
| package\_dimension<mark style="color:red;">\*</mark>      | Object | <p>Dimension pf package to be delivered (in <strong>CM</strong>), if you are not sure of your dimension, you can make use of the <strong>Package Dimensions API</strong></p><p></p><p>{ "length":12, "width":10, "height":10 }</p>              |

{% tabs %}
{% tab title="200: OK request\_token is used to uniquely identify each rates API request" %}

```javascript
{
    "status": "success",
    "message": "Retrieved successfully",
    "data": {
        "request_token": "b724643e35047b44bf6499ce32dec6bf44b4de88859c03198a6f5714e026173b",
        "couriers": [
            {
                "courier_id": "cora",
                "courier_name": "Cora",
                "courier_image": "https://res.cloudinary.com/delivry/image/upload/v1659021064/courier_images/topship_ixpqdt.jpg",
                "service_code": "cora",
                "insurance": {
                    "code": "not available",
                    "fee": 0
                },
                "discount": {
                    "percentage": 10,
                    "symbol": "%",
                    "discounted": 0
                },
                "service_type": "pickup",
                "waybill": false,
                "on_demand": false,
                "is_cod_available": false,
                "cod_remit_days": 2,
                "tracking_level": 7,
                "ratings": 3,
                "votes": 1,
                "connected_account": false,
                "rate_card_amount": 3063,
                "rate_card_currency": "NGN",
                "pickup_eta": "Within 3 hours",
                "pickup_eta_time": "2025-04-10 15:44:06",
                "dropoff_station": null,
                "pickup_station": null,
                "delivery_eta": "Within 23 hrs",
                "delivery_eta_time": "2025-04-11 12:44:06",
                "info": null,
                "currency": "NGN",
                "vat": 188,
                "total": 3063,
                "tracking": {
                    "bars": 4,
                    "label": "Good"
                }
            },
            {
                "courier_id": 1,
                "courier_name": "Routely (Express Standard)",
                "courier_image": "https://res.cloudinary.com/delivry/image/upload/v1659021064/courier_images/topship_ixpqdt.jpg",
                "service_code": "routely",
                "insurance": {
                    "code": "not available",
                    "fee": 0
                },
                "discount": {
                    "percentage": 10,
                    "symbol": "%",
                    "discounted": 270
                },
                "service_type": "dropoff",
                "waybill": false,
                "on_demand": false,
                "is_cod_available": false,
                "tracking_level": 7,
                "ratings": 3,
                "votes": 1,
                "connected_account": false,
                "rate_card_amount": 12451.04,
                "rate_card_currency": "NGN",
                "pickup_eta": "Within 1 day(s)",
                "pickup_eta_time": "2025-04-11 12:44:06",
                "dropoff_station": {
                    "name": "Find your nearest Routely dropoff location here",
                    "address": "https://www.routely.co/",
                    "phone": "+2349080777728"
                },
                "pickup_station": {
                    "name": "Find your nearest Routely pickup location here",
                    "address": "https://www.routely.co/",
                    "phone": "+2349080777728"
                },
                "delivery_eta": "Within 1 - 4 working days",
                "delivery_eta_time": "2025-04-15 12:44:06",
                "info": null,
                "currency": "NGN",
                "vat": 834,
                "total": 12451.04,
                "tracking": {
                    "bars": 4,
                    "label": "Good"
                }
            }
        ],
        "fastest_courier": {
            "courier_id": 2,
            "courier_name": "Routely (Express Premium)",
            "courier_image": "https://res.cloudinary.com/delivry/image/upload/v1659021064/courier_images/topship_ixpqdt.jpg",
            "service_code": "routely",
            "insurance": {
                "code": "not available",
                "fee": 0
            },
            "discount": {
                "percentage": 10,
                "symbol": "%",
                "discounted": 270
            },
            "service_type": "pickup",
            "waybill": false,
            "on_demand": false,
            "is_cod_available": false,
            "tracking_level": 7,
            "ratings": 3,
            "votes": 1,
            "connected_account": false,
            "rate_card_amount": 3308,
            "rate_card_currency": "NGN",
            "pickup_eta": "Within 2 hour(s)",
            "pickup_eta_time": "2025-04-10 16:44:06",
            "dropoff_station": null,
            "pickup_station": null,
            "delivery_eta": "Within 9 hrs",
            "delivery_eta_time": "2025-04-10 22:44:06",
            "info": null,
            "currency": "NGN",
            "vat": 203,
            "total": 3308,
            "tracking": {
                "bars": 4,
                "label": "Good"
            }
        },
        "cheapest_courier": {
            "courier_id": "dellyman",
            "courier_name": "Dellyman",
            "courier_image": "https://res.cloudinary.com/delivry/image/upload/v1697995461/courier_images/dellyman_logo_ckd6z8.png",
            "service_code": "dellyman",
            "insurance": {
                "code": "not available",
                "fee": 0
            },
            "discount": {
                "percentage": 0,
                "symbol": "%",
                "discounted": 0
            },
            "service_type": "pickup",
            "waybill": false,
            "on_demand": false,
            "is_cod_available": false,
            "tracking_level": 6,
            "ratings": 3,
            "votes": 1,
            "connected_account": true,
            "rate_card_amount": 1830,
            "rate_card_currency": "NGN",
            "pickup_eta": "Within 24 hours",
            "pickup_eta_time": "2025-04-11 12:44:06",
            "dropoff_station": null,
            "pickup_station": null,
            "delivery_eta": "Within 1 - 2 working days",
            "delivery_eta_time": "2025-04-13 12:44:06",
            "info": null,
            "currency": "NGN",
            "vat": 0,
            "total": 400,
            "tracking": {
                "bars": 3,
                "label": "Average"
            }
        },
        "checkout_data": {
            "ship_from": {
                "name": "Lebron James",
                "phone": "+2348057575855",
                "email": "lebron@james.com",
                "address": "Teslim Balogun Stadium, Alh. Masha Road, Lagos, Nigeria"
            },
            "ship_to": {
                "name": "Burger King",
                "phone": "+2347072377527",
                "email": "sdsfsfs997@gmail.com",
                "address": "brt bus oshodi terminal, oshodi, Lagos, Nigeria"
            },
            "currency": "NGN",
            "package_amount": 801500,
            "package_weight": 8.5,
            "pickup_date": "April 10th 2025",
            "is_invoice_required": false
        }
    }
}
```

{% endtab %}
{% endtabs %}

#### Some key fields returned in the courier rates array

| Field Name          | Description                                                                                                                                                                            |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| rate\_card\_amount  | The amount to be displayed to your customer as shipping cost. It's always the same value as the total field, only in cases where the courier account chosen is your connected courier. |
| total               | The amount that will be charged from your shipping wallet for the delivery.                                                                                                            |
| pickup\_eta\_time   | Estimated time frame within which the package will be picked up.                                                                                                                       |
| delivery\_eta\_time | Estimated time frame within which the package will be delivered.                                                                                                                       |
| is\_cod\_available  | Indicates if cash on delivery option is available for the rate returned. If true, **cod\_fee** will contain a service charge of the cod offering.                                      |
| tracking\_level     | Indicates how responsive the tracking systems of the courier rates are, ranging from 1 - 10.                                                                                           |

{% hint style="info" %}
There are currently two service delivery types: **pickup** and **dropoff**.

If a service type is marked as **pickup**, it means the selected courier would pick up the package at the sender's address and deliver it to the receiver's address

If a service type is marked as **dropoff**, the sender must deliver the package to a courier **dropoff** station. In this case, a **dropoff station** and **pickup station** object will be included in the response. it will contain the name and address of the dropoff station.

Check the example response for object definition
{% endhint %}