Upvendo Knowledge Base

Appearance

Delivery Region (Delivery Zones) ​

Overview ​

The Delivery Region setting defines the single geographic area where your location offers delivery. You choose one of three region types — Postal Code, Radius, or Distance — and that choice determines how the storefront decides whether a customer's address is eligible for delivery.

Key Purpose: Control where you deliver by picking one region method (postal codes, a straight-line radius, or driving distance).

Note: There is no list of separately named, individually-priced "zones" in the product. Delivery is governed by a single delivery_region object plus a single delivery_fee object, both stored on the location's online ordering setting. For how fees, free-delivery thresholds, per-postal-code custom fees, and distance-based pricing tiers work, see Delivery Settings — this page covers only the region/eligibility side.

Purpose ​

This setting lets you define the area your location delivers to. You pick one of three methods — a list of postal codes you deliver to, a fixed radius around the location, or a maximum driving distance — and the storefront uses that to decide whether an address can be delivered to.

Key Concepts ​

  • Delivery Region: A single configuration (delivery_region) on the online ordering setting, not a collection of zones. It has a type plus the value(s) for that type.
  • Region Type (delivery_region.type): One of three values from the DeliveryRegionOptions enum — Postal Code, Radius, or Distance. Only one type is active at a time; switching type changes which value fields apply.
  • Postal Code list (delivery_region.postal_codes): When the type is Postal Code, an array of postal-code strings you deliver to. An address is eligible only if its postal code is in this list.
  • Radius (delivery_region.radius): When the type is Radius, the delivery area is everything within this many kilometres (straight-line) of the location.
  • Maximum driving distance (delivery_region.max_distance): When the type is Distance, the delivery area is everything within this driving distance (in km) of the location.

Actions ​

Choose Delivery Region Type ​

On the delivery settings form, pick one of three region types: Postal Code, Radius, or Distance. The form shows different inputs depending on the choice.

Configure Postal Codes (Postal Code type) ​

Add the postal codes you deliver to, one at a time. Each entry is validated (digits only, at least 4 characters) and added as a chip. Duplicate postal codes are rejected. Remove a postal code by closing its chip.

Set Radius (Radius type) ​

Enter the number of kilometres around the location that you deliver within.

Set Driving Distance (Distance type) ​

Enter the maximum driving distance (in km) that you deliver within. This uses route-based driving distance rather than a straight line.

Location ​

  • Backoffice Page: Online Ordering → Delivery settings (route /online/online-ordering)
  • Backend Request: app/Http/Requests/BackOffice/OnlineOrdering/StoreOnlineOrderingRequest.php (validates the delivery_region block)
  • Backend Enum: app/Enums/DeliveryRegionOptions.php
  • Backend Defaults: app/Constants.php ($DEFAULT_ONLINE_ORDERING_SETTING['delivery_region'])
  • Vue Component: src/views/online/online-ordering/forms/DeliverySettings.vue

The earlier DeliveryZoneController and /pickup-and-delivery/delivery-zones page do not exist in the codebase. Delivery region is part of the Online Ordering settings form, saved through the online ordering settings endpoint.

Fields ​

Region Type ​

PropertyValue
Field IDdelivery_region.type
LabelDelivery Region
TypeEnum (DeliveryRegionOptions)
Allowed ValuesPostal Code, Radius, Distance
DefaultRadius
RequiredYes
Validationrequired, must be a valid DeliveryRegionOptions value

Description: Selects which method defines your delivery area. Only the value field(s) for the chosen type are required and used.

Postal Codes ​

PropertyValue
Field IDdelivery_region.postal_codes
LabelPostal codes you deliver to
TypeArray of strings
Default[] (empty)
RequiredYes, only when type is Postal Code
Backend Validationrequired|array; each entry required|string
Frontend ValidationDigits only; minimum 4 characters; duplicates rejected; trimmed to max 10 characters as typed

Description: The list of postal codes you deliver to when the region type is Postal Code. A customer's address is eligible for delivery only if its postal code is in this list.

Business Logic:

  • Applies only when delivery_region.type is Postal Code.
  • The backend requires at least one postal code in this mode (the array is required).
  • Removing a postal code also removes any per-postal-code custom delivery fee tied to it (custom fees are part of Delivery Settings).

Format Examples (entries are stored as typed; the backend only requires a string):

  • "1012", "1013", "1014"
  • "10115", "10117"

Radius ​

PropertyValue
Field IDdelivery_region.radius
LabelI deliver within … Km
TypeNumber (kilometres)
Default10
RequiredYes, only when type is Radius
Backend Validationrequired|numeric

Description: The straight-line radius (in km) around the location that defines the delivery area when the region type is Radius.

Maximum Driving Distance ​

PropertyValue
Field IDdelivery_region.max_distance
LabelI deliver within … Km (driving distance)
TypeNumber (kilometres)
Default10
RequiredYes, only when type is Distance
Backend Validationrequired|numeric|min:1

Description: The maximum driving distance (in km) that defines the delivery area when the region type is Distance. Uses route-based driving distance.

Business Logic ​

Region Type Determines Eligibility ​

The stored online ordering setting holds one delivery_region object. Its type selects which value field is required and used:

delivery_region.type = "Postal Code"
    → require delivery_region.postal_codes (non-empty array of strings)

delivery_region.type = "Distance"
    → require delivery_region.max_distance (numeric, min 1)

delivery_region.type = "Radius"   (the default, and the fallback for any other value)
    → require delivery_region.radius (numeric)

(See StoreOnlineOrderingRequest::rules().)

How the Region Affects Delivery Fee ​

The region type also influences how the delivery fee is resolved at checkout:

  • Postal Code: if a customer's postal code matches an entry in the per-postal-code custom-fee list (delivery_fee.custom_fees), that custom fee is used; otherwise the base delivery_fee.fee applies.
  • Distance / Radius: when distance-based pricing is enabled (delivery_fee.distance_pricing_enabled), the fee is resolved by tier (distance_fees) or flat rate per km (flat_rate_per_km) using route-based driving distance.

These fee mechanics live in Delivery Settings; this page only defines the region itself.

Defaults ​

A location with no saved delivery region inherits these defaults (from Constants::$DEFAULT_ONLINE_ORDERING_SETTING):

delivery_region.type          = "Radius"
delivery_region.postal_codes  = []
delivery_region.radius        = 10
delivery_region.max_distance  = 10

Relations ​

Depends On ​

  • Locations: The delivery region is stored per-location, inside the location's online ordering setting.
  • Online Ordering: Delivery must be enabled for the region to matter.

Affects ​

  • Storefront delivery eligibility: Whether an address can be delivered to (not-verified-here — storefront eligibility logic lives outside this repo's setting definition).
  • Delivery Settings / Checkout: The region type drives which delivery-fee mechanism applies (postal-code custom fees vs. distance-based pricing).
  • Delivery Settings — delivery fees, free-delivery threshold, custom per-postal-code fees, distance-based pricing tiers, minimum order, delivery timing.
  • Online Ordering

Business Rules ​

  • There is one delivery region per location, not multiple named zones. The region is a single delivery_region object with a type and the value field(s) for that type.
  • The region type must be one of exactly three values: Postal Code, Radius, or Distance. The default is Radius.
  • Postal Code mode requires at least one postal code; the storefront treats an address as deliverable only if its postal code is in the list.
  • Radius mode uses a straight-line radius in km; Distance mode uses route-based driving distance in km (max_distance, minimum 1).
  • Per-postal-code custom delivery fees and distance-based pricing tiers are configured under Delivery Settings, not on the region itself; removing a postal code also removes any custom fee attached to it.

FAQs ​

  • Can I have several differently-priced delivery zones at once? No. There is a single delivery region per location. You pick one type (Postal Code, Radius, or Distance). You can, however, charge different fees per postal code via the custom-fee list, or different fees per driving-distance tier — both configured under Delivery Settings.
  • What's the difference between Radius and Distance? Radius is a straight-line distance in km from your location. Distance is the maximum driving (route-based) distance in km. Pick Distance when road routes matter more than as-the-crow-flies range.
  • What format should postal codes be in? In the back office the postal-code field accepts digits only and requires at least 4 characters. Duplicate entries are rejected. The backend stores each entry as a string.
  • Is there a limit on how many postal codes I can add? There is no documented maximum count enforced in the code. Each entry must be at least 4 digits and unique.
  • Where do I set the delivery fee for my region? On the same Online Ordering → Delivery settings form, in the Delivery Fee section. See Delivery Settings.

Troubleshooting ​

Problem: "Delivery not available to your area" ​

Causes:

  1. The customer's postal code is not in delivery_region.postal_codes (Postal Code mode).
  2. The address is outside the configured radius (Radius mode) or max_distance (Distance mode).
  3. Delivery is disabled in Online Ordering settings.

Solutions:

  1. Add the postal code to the delivery region (Postal Code mode), or
  2. Increase the radius / max driving distance, or switch region type.
  3. Enable delivery in Online Ordering settings.

Storefront-side eligibility messaging is not verified in this repo.

Problem: Cannot add a postal code ​

Causes:

  1. The value contains non-digit characters (the field strips them).
  2. The value is shorter than 4 characters.
  3. The postal code is already in the list (duplicates are rejected).

Solutions:

  1. Enter digits only.
  2. Enter at least 4 digits.
  3. Use a postal code not already added.

Examples ​

Radius region (default) ​

json
{
  "delivery_region": {
    "type": "Radius",
    "radius": 10,
    "postal_codes": [],
    "max_distance": 10
  }
}

Driving-distance region ​

json
{
  "delivery_region": {
    "type": "Distance",
    "max_distance": 8,
    "radius": 10,
    "postal_codes": []
  }
}

Postal-code region ​

json
{
  "delivery_region": {
    "type": "Postal Code",
    "postal_codes": ["1012", "1013", "1014"],
    "radius": 10,
    "max_distance": 10
  }
}

For the matching delivery_fee configuration (base fee, free-delivery threshold, per-postal-code custom fees, distance tiers, flat rate per km), see Delivery Settings.