Overview

There are two types of APIs in this platform. First, the logistic partner has to implement two endpoints according to the Grubtech provided API definition. Second, Grubtech needs to implement an endpoint to receive details from the logistic partners. This guide will explain how to use those APIs to integrate the logistic platform to successfully complete any order delivery job.

Understanding the Delivery Flows

Following is a high-level explanation of the overall delivery job life-cycle. Adherence to this logistics integration flow is required and will give you a smooth integration experience. Read through this page carefully and understand the flows.

Delivery Job Creation

This section guides you through the delivery job creation process with related workflows, steps, and endpoint details.

Delivery Job Creation Process

After the restaurant has completed the preparation of the order, a notification is sent through the KDS (Kitchen Display System). Grubtech will call the logistic partner's API to send the required order delivery details as a payload. The Logistic partner will receive the relevant delivery details from the payload and start the order delivery process. Grubtech uses Create Delivery Job API to send the order delivery details to the logistic partner. While processing the order delivery job, the logistic partner will send required status updates back to Grubtech as notifications.

partnerId - The id use to bill the logistic partner account. This is the id used for all the billing processes related to the delivery job.

Create Delivery API contains all the details related to delivery pick-up and delivery drop-off that need to be used by the Logistics partner. The delivery job can be rejected for various factors including errors with partner id, payload mapping errors, or configuration errors. The Logistic partner is expected to respond with HTTP 202 to acknowledge the request.

Delivery Job Cancellation

This section guides you through the delivery job cancellation process with related workflows, steps, and endpoint details.

Delivery Job Cancellation Process

This API section will send order delivery cancellation details to the relevant Logistic partner. The Logistic partner should have implemented the defined endpoint on their end to receive accurate details. Delivery cancellation can be done through the KDS or the Customer Support team, depending on the situation. Grubtech will send the Cancel Delivery Job notification to the Logistic partner.

Delivery job cancellation can happen on three occasions:

When the required partner id is not in the 'Order delivery cancel' notification triggered by Grubtech.
When there are no valid delivery details in the assigned order.
When there is an original request for a delivery job cancellation from KDS or the customer support service.

After the delivery job is canceled by the Logistic partner, it is notified to Grubtech's Update Delivery Job webhook.

Delivery Job Status Updates

This section guides you through the delivery job status update process with related workflows, steps, and endpoint details.

Delivery Job Status Update Process

After Grubtech calls Create Delivery endpoint with the payload, the Logistic partner will grab the order delivery details and start the delivery job processing. During the delivery job processing, the Logistic partner will send major status changes of the delivery job back to Grubtech. The endpoint Update Delivery Status should be configured in the Grubtech end and the Logistic partner should send status updates to Grubtech indicating subsequent status changes of the order delivery job.

Order Delivery Statuses

Since it is important for a restaurant to know the delivery job statuses within the system, it is expected that the Logistic partner will send this information in a correct manner. Each status update will be identified by the Reference id provided by the Logistic partner. These are the six delivery statuses. In an accurate order flow, these statuses will occur as per the following sequence.

DELIVERY_JOB_CREATED
DRIVER_ASSIGNED
DRIVER_ARRIVED
DELIVERY_JOB_STARTED
DELIVERY_JOB_COMPLETED
DELIVERY_JOB_CANCELLED

The Logistic partner will send the delivery status updates to Grubtech. That payload contains tracking details, driver details, and pick-up details with the current delivery job status. Grubtech will use that payload details to further processing or logging purposes.

Testing Delivery Jobs

Refer Perform a UAT for more details on how to proceed with testing your delivery jobs.

Refer the section on Test Tools to learn about the sample tools provided for testing and how to use them.

Refer grubCenter to navigate to the grubCenter Administration Application.
Refer Virtual KDS to navigate to the Grub KDS Sample Kitchen Display System.
Refer Order Dashboard to navigate to the Test Order App - Sample Ordering Application.