This page describes the core entities of the Courier API and how they relate. These are the data structures behind delivery options, pricing, and trip execution.
Identifiers
Each resource is returned with a guid field that identifies it. Identifiers carry a type prefix: vehicle types use VEH_, quotes use TQT_, trips use TRP_, and webhook events use EVT_. When a path or request body refers to another resource, it names it as <resource>_id, for example quote_id or trip_id, and the value is that resource’s guid.
Vehicle
A Vehicle is a type of delivery service offered on the platform, such as a motorcycle, car, or van. A vehicle type defines delivery characteristics like capacity and service coverage, and it is available only in supported cities. Each has a guid (prefix VEH_) and a human-readable name.
You do not book a vehicle directly. You select a vehicle type when requesting a quote or booking a trip, and that choice determines whether the delivery can be priced and carried out. When you specify a vehicle, the API accepts either its guid or its name. Common types are motorcycle for small packages and documents, car for medium deliveries, and van for large or bulk loads.
Quote
A Quote is a price estimate for a proposed delivery, generated from the pickup and dropoff locations, the selected vehicle type, the estimated distance and duration, and the applicable pricing rules. Each quote references exactly one vehicle type.
Quotes are time-limited and must be booked before they expire. Once booked, a quote produces a single trip and cannot be reused, and booking an expired quote returns an error.
Trip
A Trip is an active or completed delivery. Trips are usually created by booking a quote, in which case the trip inherits the vehicle type and locations from the quote. A trip has one pickup location, one or more dropoff locations, a vehicle type, pricing information, and an execution status.
A trip can deliver to several dropoffs in one run. The driver works through them in order, and each stop is tracked and emits its own events as it begins and completes. Set optimize_route when creating the trip or quote to have the dropoffs ordered for an efficient route.
After a trip is created, the platform looks for an available driver to assign. A trip can have at most one assigned driver. A trip moves through a defined set of statuses as it is carried out; see Trip Lifecycle & Events for the full list and the order they occur in.
Location
A Location is a geographic point used for pickup or dropoff. Locations are embedded inside quotes and trips rather than managed on their own. Each trip has exactly one pickup and one or more dropoffs. A location can include coordinates, a label, optional contact details, and delivery instructions used during execution.
Driver
A Driver is the courier assigned to a trip. Driver details become available only after a driver is assigned, and a trip has at most one. The details are provided to help coordinate the delivery.
Fare
A Fare is the pricing attached to a quote or a trip. On a quote, the fare is an estimate calculated at pricing time. On a trip, it is the amount charged, finalized when the trip completes. A fare has a total amount, a currency, and an itemized breakdown. The fare carries from the quote into the trip.
Courier trips are billed to the merchant’s Gozem wallet. If the balance is too low to cover a trip, booking is rejected with the insufficient_wallet_balance error, so keep the wallet funded for the volume you expect. See Errors for the full list of Courier error codes.
Invoice
An Invoice is generated for a trip that completes successfully, exactly one per completed trip. It contains billing and reconciliation details derived from the final fare. Trips that are canceled or never completed have no invoice.
Message
A Message is communication exchanged between the client and the driver during an active trip. Messages belong to a specific trip and are available only after a driver is assigned. A trip can have several messages over its course.
Event
An Event records a significant action or state change during a trip. Events form a chronological record of the trip’s history, including status transitions and system actions. The same changes that produce events also drive the webhooks you subscribe to; see Trip Lifecycle & Events for the Courier events and the platform Webhooks guide for how delivery works.