> For the complete documentation index, see [llms.txt](https://support.ordereazi.com/central/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.ordereazi.com/central/apps/couriers/city-logistics.md).

# City Logistics

Get City Logistics rates, book shipments from your closest branch, and print parcel labels from your OrderEazi projects with the City Logistics app.

When you ship from several branches, or across borders, arranging each City Logistics collection by hand takes time. The City Logistics app (**City Logistics Courier App** in the App Gallery) brings City Logistics' rates and bookings into OrderEazi Central. It collects each shipment from the closest of your branches, and prints the parcel labels.

### Before you start

You'll need:

* **A City Logistics access token:** The token City Logistics issues for your account. The test (QA) and live (Production) systems are separate, so each has its own token.
* **Your service code and collection references:** Ask City Logistics for your service code, such as ECO. Also ask for each branch's collection reference, such as CTN1 or JHB1.
* **Your branches' details:** Each branch's address, and its map coordinates (latitude and longitude).
* **A courier supplier and product:** Your courier must exist as a supplier in OrderEazi, with a product you charge courier costs to.
* **Permissions:** You need **View Installed Apps** and **Configure and Open Installed Apps**, in the **App Gallery** permission group. See [App Gallery](/central/apps/app-gallery.md).

### How to set up City Logistics

> **Warning:** On **Production**, every booking is a real consignment, billed to your City Logistics account. New installs start on **QA**, City Logistics' test system, so test there first.

1. In the main menu, select **Apps**.
2. If **Installed Apps** opens, select **View Gallery**.
3. Find **City Logistics Courier App**, and select **Install**.
4. On **Installed Apps**, select **Open** on **City Logistics Courier App**.
5. Under **City Logistics Account**, choose the **Environment**: **QA** for testing, or **Production**.
6. Enter your **Access Token** for that environment.
7. Enter your **Default Service Level**, the service code City Logistics gave you.
8. Choose your **OrderEazi Supplier**.
9. Choose your **OrderEazi Product**.
10. Select **Save**.

From then on, City Logistics appears in **Get Courier Quote** on your projects. Once saved, the token isn't shown again, and a label shows **Captured** or **Not captured**, with the date it expires.

With the **OrderEazi Supplier** and **OrderEazi Product** set, **Add Customer Charge** on the shipment adds the courier cost to the project. Without them, the shipment shows **Courier supplier not linked**. See [Expenses, discounts, and shipments](/central/order-management/projects/expenses-discounts-and-shipments.md).

### How to renew your token

> **Warning:** A token that has already expired can't be renewed. City Logistics has to issue a new one, and quotes and bookings fail until you enter it.

Before the expiry date on the app's settings, select **Renew token** under **City Logistics Account**. Your token is swapped for a fresh one.

### How to add your collection locations

City Logistics collects from your own branches, set up on the app's **Locations** tab. The **From** address on the **Addresses** step of **Get Courier Quote** isn't where City Logistics collects.

1. On the app's **Locations** tab, add a location for each branch.
2. Enter its name, company name, and street address.
3. Enter its latitude and longitude.
4. Enter its **City Logistics Reference**, the code City Logistics knows the branch by.
5. Tick **Active**.
6. Select **Save**.

Every active location needs a **City Logistics Reference**. A booking from a location with the wrong reference is refused, and City Logistics lists the references you can use.

The coordinates aren't looked up for you, and they decide which branch is closest. To find them, right-click the branch on an online map and copy the pair it shows, latitude first.

A location can be a child of a parent branch, such as a "Tokai" store under a "Bellville (Head Office)" branch. A child location's shipments are collected from its parent. Child locations are one level deep, and each belongs to one parent.

### How City Logistics works

* **Choosing a branch:** If your branch or organisation name matches a location's name, that location is used, or its parent if it's a child. Otherwise, the active location with the shortest driving time to the delivery address is used.
* **Rates:** You get one rate, for your **Default Service Level**, excluding VAT. Each parcel on the project is sent as a separate item.
* **Booking:** The shipment is booked with City Logistics straight away. The waybill number on the **Shipments** tab is your client's order number, or the project number if there isn't one.
* **Labels:** Select **View Labels** on the shipment to open every parcel's label in one PDF, sized for a 4 × 3 inch label printer.
* **Cancelling:** Deleting the shipment from the project cancels the booking with City Logistics.

City Logistics delivers within South Africa, and to Namibia, Botswana, Lesotho, Eswatini, Zimbabwe, Mozambique, Zambia, and Kenya.

**Example:** A project for a client in Durban is collected from your Johannesburg location (reference JHB1), the closest active location. You get one ECO rate and book it. The **Shipments** tab shows the client's order number as the waybill, and **View Labels** opens a label for each of the 3 parcels.

### How to turn on automatic booking

1. Open **City Logistics Courier App** from **Installed Apps**, as in the setup steps.
2. Under **Automatic Shipment Creation**, tick the checkbox.
3. Select **Save**.

From then on, **Auto consign**, **Auto Consign Shipment** in the Fulfillment Manager, and a completed **ReadyForDelivery** step all book your **Default Service Level**, from a branch chosen by the same rules as a quote. See [Couriers](/central/apps/couriers.md).

### What the City Logistics app does not do

* **Track shipments:** Status updates and proof of delivery aren't received after booking.
* **Offer other service levels:** Every quote uses your **Default Service Level**.
* **Send declared value:** Insurance isn't sent with the booking.

### Related pages

* [Couriers](/central/apps/couriers.md): how courier apps work in OrderEazi
* [Getting a courier quote](/central/order-management/projects/getting-a-courier-quote.md): get rates and book from a project
* [Fulfillment Manager](/central/order-management/delivery/fulfillment-manager.md): book shipments for several projects