> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryoto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout API for live shipping rates

> Show real carrier options, prices and delivery estimates at your checkout with the OTO checkout API: what to request, what comes back and how to display it.

> [!NOTE]
>
> **Where to find it:** Settings → Developers → API Documentation — [Open in OTO ↗](https://app.tryoto.com/api-integrations)

Most checkouts guess at shipping. A flat rate, a table of postcodes, a promise of “3–5 working days” that nobody has checked against a carrier since it was written.

## What the API is for

OTO already knows, for a given origin, destination and parcel, which carriers will take it, what each will charge you, and how long each usually takes. The checkout API exposes that to your storefront at the moment it matters — while the customer is deciding.

This is the same engine that [carrier selection](https://docs.tryoto.com/modules/shipping-management/carrier-integration.md) uses internally. The difference is only who is asking.

## Requesting options

`POST /rest/v2/checkOTODeliveryFee`

| Field | Required | What it is |
| - | - | - |
| `originCity` | Yes | The pickup city — which hub the order would ship from. |
| `destinationCity` | Yes | Where the customer is. |
| `weight` | Yes | Approximate parcel weight, in kilograms. |
| `originCountry` · `destinationCountry` | No | ISO 3166-2 codes, for cross-border. |
| `length` · `width` · `height` · `packageCount` | No | Dimensions and parcel count, where volumetric weight or multi-box pricing applies. |
| `totalDue` · `currency` | No | Order value, so COD charges and value limits can be applied. |
| `serviceType` | No | Narrows the answer: **express**, **sameDay**, **fastDelivery**, **coldDelivery**, **heavyAndBulky**, **electronicAndHeavy**. |

## What comes back

A list of delivery options, one per carrier service that will accept the shipment.

| Field | What it carries |
| - | - |
| `deliveryOptionName` · `deliveryCompanyName` | The service and the carrier behind it. |
| `price` | The delivery cost. |
| `avgDeliveryTime` | A human-readable estimate — for example *“1 to 2 Working Days”*. |
| `pickupCutOffTime` | The latest time an order can be handed over and still go today — for example *17:00*. |
| `codCharge` · `maxCODValue` | The cash-on-delivery fee, and the value ceiling above which that carrier will not collect. |
| `returnFee` · `insurancePolicy` | What a return on this service costs, and what is covered if it goes missing. |
| `trackingType` · `pickupDropoff` | How the parcel is tracked, and how it is handed over — **freePickup**, **dropoffOnly** or **freePickupDropoff**. |

## Estimated delivery and pickup times

The two time fields answer different questions, and both belong on a checkout.

**Average delivery time** is the duration: how long this service usually takes on this lane. **Pickup cut-off time** is the deadline: order after it and the clock starts tomorrow.

> [!TIP]
>
> **The cut-off is what makes a delivery promise honest**
>
> “Next-day delivery” shown at 9pm is a promise the business cannot keep, and the customer finds out a day later. “Order within 4 hours for delivery tomorrow” is the same information, told in time to act on.
>
> Cut-off times are also the most effective urgency you can put on a checkout, precisely because they are true. The countdown is a fact about your operation, not a marketing device.

## Putting it on a checkout

1. The customer enters a delivery address.
2. Your storefront calls `checkOTODeliveryFee` with that city, the cart’s weight, and the hub you would ship from.
3. You present the options you want to offer — usually cheapest and fastest rather than all of them — with the estimate and, where it is close, the cut-off.
4. The customer’s choice becomes the delivery option on the order, so fulfillment ships what was actually sold.

> [!NOTE]
>
> **Show fewer options than you receive**
>
> A response with nine carriers is a list to choose from, not a menu to display. Checkouts convert worse when shipping becomes a decision with nine branches.
>
> Two or three named by outcome — *Standard, arrives Tuesday* and *Express, arrives tomorrow* — use the same data and ask less of the customer.

## Related

* [Carrier integration](https://docs.tryoto.com/modules/shipping-management/carrier-integration.md) — the carriers these options come from.
* [Shipping automation](https://docs.tryoto.com/modules/shipping-management/shipping-automation.md) — how a carrier is chosen when nobody is asked.
* [Hubs Management](https://docs.tryoto.com/modules/hubs-management/overview.md) — the origin the estimate is measured from.


## Related topics

- [Sales channel integrations](https://docs.tryoto.com/integrations/sales-channels.md)
- [REST API reference](https://docs.tryoto.com/developers/rest-api-reference.md)
- [OTO API overview](https://docs.tryoto.com/developers/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.