> For the complete documentation index, see [llms.txt](https://docs.terminal.africa/tship/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.terminal.africa/tship/rate.md).

# Rates

The Rates API allows you to retrieve shipping rates from available carriers.

### The Rate Object

This section describes the different attributes available for a rate.

| Attribute                   | Type       | Description                                                                                                                                             |
| --------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| amount                      | *number*   | Shipping rate amount. Includes any remote delivery fee marked `metadata.remote_area.collection_required: true`. The Priority Pickup fare is additional. |
| carrier\_logo               | *string*   | Image URL for carrier logo.                                                                                                                             |
| carrier\_name               | *string*   | Name of carrier executing shipment.                                                                                                                     |
| carrier\_rate\_description  | *string*   | Carrier description of rate e.g. UPS First Class.                                                                                                       |
| carrier\_reference          | *string*   | Unique identifier for carrier.                                                                                                                          |
| carrier\_slug               | *string*   | Unique slug for carrier.                                                                                                                                |
| currency                    | *string*   | Currency of rate amount.                                                                                                                                |
| delivery\_date              | *date*     | Estimated delivery date for shipment.                                                                                                                   |
| delivery\_eta               | number     | Estimated delivery time in minutes.                                                                                                                     |
| delivery\_time              | *string*   | Human readable description of estimated time to deliver parcel.                                                                                         |
| id                          | *string*   | Unique identifier for rate.                                                                                                                             |
| metadata                    | *object*   | Provides additional information for a rate.                                                                                                             |
| metadata.remote\_area       | *object*   | Optional remote delivery assessment and included-fee disclosure. See Remote area delivery fees below.                                                   |
| pickup\_options             | *array*    | Available option objects: `pickup`, `priority_pickup`, `scheduled_pickup` or `dropoff`. Priority Pickup includes its additional amount and currency.    |
| priority\_pickup\_available | *boolean*  | Whether a valid Priority Pickup quote is available for this rate.                                                                                       |
| priority\_pickup\_fee       | *number*   | Additional quoted Priority Pickup fare in the rate currency. Omitted when unavailable.                                                                  |
| pickup\_eta                 | *number*   | Estimated pickup time in minutes.                                                                                                                       |
| pickup\_time                | *string*   | Human readable description of estimated time to pickup parcel.                                                                                          |
| rate\_id                    | *string*   | Unique reference for rate.                                                                                                                              |
| used                        | *boolean*  | Indicates if a rate has been used in a shipment request.                                                                                                |
| created\_at                 | *datetime* | Time rate created.                                                                                                                                      |
| updated\_at                 | *datetime* | Time rate last updated.                                                                                                                                 |

## Remote area delivery fees

Eligible DHL (`dhl-ng`) and FedEx (`fedex`) rates billed through Terminal can include an upfront remote area delivery charge when this feature is enabled for your account. FedEx support covers Terminal's Nigeria import/export rate-card services. The optional `metadata.remote_area` object explains that charge. Integrations must continue to handle rates without this object.

{% hint style="info" %}
When `metadata.remote_area.collection_required` is `true`, the remote area amount is **already included in `rate.amount`**. Use it to explain the shipping price to your customer. Do not add it to `rate.amount` again.
{% endhint %}

### Remote area fields

The fields below belong to `rate.metadata.remote_area`. Amounts are expressed in currency units, not cents or kobo.

| Field                 | Type     | Description                                                                                                                                                       |
| --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`              | string   | `remote`, `not_remote`, or `unknown`. A missing object or `unknown` status does not confirm that the destination is non-remote.                                   |
| `collection_required` | boolean  | When `true`, the quoted remote delivery amount is included in the shipping price and is to be collected at booking. This is not proof that payment has completed. |
| `amount`              | number   | Remote delivery fee, incremental fuel, and tax combined, converted into `currency`. Use this value for the customer disclosure.                                   |
| `currency`            | string   | Currency of `amount`, matching the requested rate currency.                                                                                                       |
| `fee`                 | number   | Remote delivery fee before its fuel and tax, in **NGN**.                                                                                                          |
| `fuel`                | number   | Incremental fuel attributable to remote delivery, in **NGN**. This is not the fuel charge for the entire shipment.                                                |
| `tax`                 | number   | Tax attributable to the remote delivery fee and its fuel, in **NGN**.                                                                                             |
| `total_ngn`           | number   | Total remote delivery amount in **NGN**: `fee + fuel + tax`.                                                                                                      |
| `service_code`        | string   | Carrier surcharge code: DHL uses `OO`; FedEx uses `OUT_OF_DELIVERY_AREA`. Remote pickup is a separate service.                                                    |
| `source`              | string   | `dhl_api` or `fedex_api` for a successful assessment from the respective carrier.                                                                                 |
| `mode`                | string   | `collect` or `shadow`. Shadow observations do not increase the quoted shipping price.                                                                             |
| `checked_at`          | datetime | ISO timestamp when the assessment was made.                                                                                                                       |
| `expires_at`          | datetime | ISO timestamp after which the quote must be refreshed before booking.                                                                                             |

Successful assessments include the monetary fields. An `unknown` assessment can omit them. Additional diagnostic metadata may also be present; integrations should tolerate additional fields.

The public rate response omits the internal `breakdown` object and shipment cost. Read `metadata.remote_area.amount` and `metadata.remote_area.currency` for customer display. Do not interpret `fee`, `fuel`, or `tax` as the requested currency: those components remain in NGN even for a USD quote.

### Sample DHL rate response

This is an abbreviated example from the shipment rates response. The identifiers and timestamps illustrate the response shape; obtain a fresh rate before booking. The amounts are examples, not fixed tariffs.

```json
{
  "status": true,
  "message": "Rates retrieved successfully",
  "data": [
    {
      "rate_id": "RT-EXAMPLE",
      "carrier_slug": "dhl-ng",
      "carrier_name": "DHL Express",
      "currency": "NGN",
      "amount": 117695.37,
      "metadata": {
        "remote_area": {
          "status": "remote",
          "mode": "collect",
          "collection_required": true,
          "amount": 32250,
          "currency": "NGN",
          "fee": 20000,
          "fuel": 10000,
          "tax": 2250,
          "total_ngn": 32250,
          "service_code": "OO",
          "source": "dhl_api",
          "checked_at": "2026-11-12T07:14:54.277Z",
          "expires_at": "2026-11-12T07:29:54.277Z"
        }
      }
    }
  ]
}
```

In this example, the shipping price before remote delivery is NGN 85,445.37. Adding NGN 32,250.00 produces the returned `rate.amount` of **NGN 117,695.37**. Other selected services, such as insurance or Priority Pickup, follow their own pricing rules.

### Sample FedEx rate

FedEx uses the same fields and display logic. This abbreviated rate illustrates a base shipping price of NGN 100,000 plus a remote delivery increment of NGN 7,155.22. The increment includes fee, fuel and tax; `amount` already includes it. Prices and service tiers vary by shipment and account.

```json
{
  "rate_id": "RT-FEDEX-EXAMPLE",
  "carrier_slug": "fedex",
  "currency": "NGN",
  "amount": 107155.22,
  "metadata": {
    "remote_area": {
      "status": "remote",
      "mode": "collect",
      "collection_required": true,
      "amount": 7155.22,
      "currency": "NGN",
      "fee": 4371.77,
      "fuel": 2284.25,
      "tax": 499.2,
      "total_ngn": 7155.22,
      "service_code": "OUT_OF_DELIVERY_AREA",
      "source": "fedex_api",
      "checked_at": "2026-11-12T09:00:00.000Z",
      "expires_at": "2026-11-12T09:15:00.000Z"
    }
  }
}
```

Use the assessment on the selected carrier's rate. A destination can attract a delivery-area fee from FedEx even when DHL does not charge one. FedEx `OUT_OF_PICKUP_AREA` is a different service and is not included in this remote delivery field. Connected customer-account quotes and `fedex-us` rates retain their existing pricing path.

### Display the fee without charging it twice

The following example uses the selected rate from `response.data`. It displays the returned shipping amount and adds an informational message about the portion attributable to remote delivery.

```html
<p id="shipping-total"></p>
<p id="remote-area-message"></p>
```

```javascript
function renderShippingRate(rate) {
  const formatMoney = (amount, currency) =>
    new Intl.NumberFormat("en-NG", {
      style: "currency",
      currency,
      currencyDisplay: "narrowSymbol"
    }).format(amount);

  if (!Number.isFinite(rate.amount) || !rate.currency) {
    throw new Error("A priced shipping rate is required");
  }

  const remote = rate.metadata?.remote_area;
  const remoteIsIncluded =
    remote?.collection_required === true &&
    remote.status === "remote" &&
    Number.isFinite(remote.amount) &&
    remote.amount > 0 &&
    remote.currency === rate.currency;

  // The returned amount already includes any collected remote delivery fee.
  const shippingTotal = rate.amount;
  document.getElementById("shipping-total").textContent =
    `Shipping: ${formatMoney(shippingTotal, rate.currency)}`;

  // Clear the message when the customer selects a rate without an included fee.
  document.getElementById("remote-area-message").textContent = remoteIsIncluded
    ? `Includes remote area delivery: ${formatMoney(remote.amount, remote.currency)} (fee, fuel and tax)`
    : "";

  return shippingTotal;
}

// response is the JSON body returned by the rates endpoint.
const shippingTotal = renderShippingRate(response.data[0]);
// shippingTotal is 117695.37. Do not add remote.amount to it again.
```

The customer sees:

> Shipping: ₦117,695.37
>
> Includes remote area delivery: ₦32,250.00 (fee, fuel and tax)

If your UI uses a price breakdown, label the remote amount as **included**. Only split the shipping price into base shipping and remote delivery if you subtract the included remote amount from the base; the sum must still equal `rate.amount`.

### Quote validity and payment

* Check `expires_at` before enabling booking. Obtain a fresh quote if it has expired, or if the address, package details, or selected service changes. Quotes normally last 15 minutes; always use the returned timestamp rather than a fixed client timer.
* Book using the selected persisted `rate_id` through the normal shipment flow. A non-persisted quote may omit `rate_id`; obtain a persisted rate before booking.
* In `shadow` mode, `collection_required` is `false`: the assessment is informational and its amount has not been added to the shipping price. Do not display it as an included charge or collect it separately.
* `not_remote` means no remote delivery charge was returned for that assessment. A missing object or `unknown` status must not be presented as confirmation that the destination is non-remote.
* `collection_required: true` describes the quote. Once the booking payment succeeds, Terminal records the paid allocation and skips a later duplicate remote delivery charge. Interrupted payments and reversed allocations require review; the rate object alone is not a payment receipt.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.terminal.africa/tship/rate.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
