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

# Delivery addresses and fee calculation

> How oFatoura stores customer delivery addresses, calculates delivery fees, estimates arrival times, and validates delivery availability based on your branch settings.

When you create a delivery order, oFatoura uses the customer's saved location to calculate the exact delivery fee, estimate the arrival time, and confirm that your branch delivers to that area. All of this happens automatically once your branch delivery settings are configured.

## How saved addresses work

Each customer can have a delivery address stored on their profile. When you attach a customer to a delivery order, the system looks up their saved address and pre-fills the location for you. You can also pick a new location at checkout without overwriting the saved address.

The location must include map coordinates (latitude and longitude) — a street-text address alone is not enough for fee calculation. The location selector provides a map picker so you can drop a pin, or you can enter the address manually and confirm the pin position.

## Selecting a delivery address at checkout

<Steps>
  <Step title="Open a delivery order">
    Create a new order and set the order type to **Delivery**. The location selector panel appears automatically.
  </Step>

  <Step title="Choose a saved address or add a new one">
    If the customer already has a saved address, it appears in the list. Select it to load the location instantly.

    To use a different address, choose **Add new location** and either drop a pin on the map or type the address into the search field and confirm the pin.
  </Step>

  <Step title="Review the calculated details">
    Once a location is pinned, the system displays:

    * **Delivery fee** — calculated automatically (see below)
    * **Distance** — straight-line or routed distance in kilometres
    * **ETA** — estimated delivery time (minimum and maximum, in minutes)
    * **Free delivery** — a notice if the order qualifies (see below)

    If the location is outside your delivery range, or if delivery is not available at the current time, an error is shown and you cannot proceed.
  </Step>

  <Step title="Confirm the address">
    Click **Confirm** (or equivalent) to apply the address and fee to the order.
  </Step>
</Steps>

## How delivery fees are calculated

Your branch supports three fee models. You configure the active model in [Branch Delivery Settings](/settings/delivery).

| Fee model             | How it works                                                                                                                                                        |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Fixed fee**         | Every delivery order within the delivery radius is charged a flat amount, regardless of distance.                                                                   |
| **Per-distance rate** | The fee is the distance (in km) multiplied by your per-km rate.                                                                                                     |
| **Tiered fee**        | You define distance bands (e.g. 0–2 km, 2–5 km, 5–10 km), each with its own flat fee. The system applies the fee for the band that matches the customer's distance. |

<Note>
  Distance is measured using the Google Maps Distance Matrix service. Your branch needs a valid Google Maps API key configured for distance-based calculations to work. Without it, the distance field will be unavailable.
</Note>

## Free delivery eligibility

You can set up one or both free-delivery conditions in your branch delivery settings:

* **Free above a spend threshold** — if the order subtotal meets or exceeds a set amount, the delivery fee is waived automatically.
* **Free within a radius** — customers within a set distance (e.g. 1 km) from your branch get free delivery.

When a customer qualifies, the fee shown in the location selector drops to zero and a free-delivery notice is displayed on the order.

## ETA calculation

The ETA shown to staff is an estimate based on the distance and the delivery speed you have configured in your branch settings, plus any buffer time you have added. It displays as a range (for example, "25–35 min") rather than a single value.

ETA is informational — it helps staff communicate an expected arrival time. It does not block or route orders automatically.

## Delivery-hours validation

If your branch restricts delivery to specific hours, the location selector checks whether the current time falls within those hours before allowing address confirmation. If you try to set a delivery address outside those hours, the system shows a warning and prevents the order from proceeding as a delivery.

You manage delivery hours alongside your other delivery rules in [Branch Delivery Settings](/settings/delivery).

## Saving an address to a customer profile

You can also add or update a customer's delivery address directly from the customer list, without going through an order:

<Steps>
  <Step title="Open the customer record">
    Go to **Customers** in the sidebar and find the customer. Click the edit icon on their row.
  </Step>

  <Step title="Update the delivery address field">
    Enter the address in the **Delivery address** field and save. This stores the address text on the customer's profile so it is available next time you create a delivery order for them.
  </Step>
</Steps>

<Tip>
  For full fee calculation and ETA, the address must also include map coordinates. Coordinates are captured when you use the map picker during checkout — the text field in the customer profile stores the human-readable address only.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The delivery fee shows zero unexpectedly">
    Check whether the customer's location qualifies for free delivery under your spend threshold or radius rules in [Branch Delivery Settings](/settings/delivery). Also verify that the fee model is set and that your distance tiers or per-km rate are saved.
  </Accordion>

  <Accordion title="Distance and ETA are not showing">
    This usually means your Google Maps API key is missing or not authorised for the Distance Matrix service. Check your branch delivery settings and confirm the key is entered and active.
  </Accordion>

  <Accordion title="The location is rejected as out of range">
    The customer's pinned location exceeds your maximum delivery radius. You can increase the radius in [Branch Delivery Settings](/settings/delivery) or inform the customer that delivery is not available to their address.
  </Accordion>

  <Accordion title="Delivery is blocked even though the address is valid">
    If your branch has restricted delivery hours, orders outside those hours are blocked regardless of address. Check the delivery hours in your branch settings and confirm the current time falls within them.
  </Accordion>
</AccordionGroup>

***

## Related

* [Branch Delivery Settings](/settings/delivery)
* [Managing Customers](/customers/managing-customers)
* [Creating Orders on the POS](/pos/creating-orders)
* [Delivery Executives and Logistics](/pos/delivery-executives)