Overview

Use the Order API to send orders to Grubtech and receive status updates from Grubtech. The API includes endpoints from both Grubtech and the Ordering Platform. The endpoints on Grubtech allow the Ordering Platform to push new orders (Refer Order API Grubtech Endpoints section of the API reference). Endpoints on the Ordering Platform allow it to receive status updates from Grubtech (Refer Order API Order Platform Webhooks section of the API reference). The Ordering Platform is required to implement the endpoints specified under the Ordering Platform section of the API Reference.

Understanding the Order Flow

Adherence to the Grubtech order integration flows, explained below, is required for the order integration. Read through the sections to understand the Order Flows.

Order Creation

When considering the Order Flow, there are 2 endpoints for order creation:

1. Place Order
   When an order is created on the Ordering platform, this order must be pushed to Grubtech. This is performed through the Order Notification endpoint.
   In the first step the order platform sends an order notification to grubtech. Grubtech responds with HTTP 201 if it acknowledged the request. For any status other than 201 or a timeout the order platform may retry posting the request. We recommend retrying 3 - 5 times with an exponential backoff.

2. Order Accepted

If payloadwise and validationwise there are no issues with the order that was placed and if the items are available, the order is created on Grubtech. A notification is then sent to the Ordering platform informing that the order is created and that the kitchen has accepted the order. This is performed through the Order Accepted endpoint.

Order Rejection

The order can be rejected for numerous factors including item unavailability, payload mapping errors or configuration errors. The food aggregator (Ordering Platform) can then notify their customer of the order rejection. The Ordering Platform is expected to respond with HTTP 204 to acknowledge the request. For any other status Grubtech will attempt to retry the API call. When the order comes to Grubtech, the Reject status is sent through the Order Rejected endpoint.

Order Started

Once the order is accepted by Grubtech, this order can be viewed using KDS. The kitchen staff can now see the details of this order. Once the kitchen staff press Start on the order displayed in the KDS, the order moves to preparation. A notification is now sent by Grubtech to inform the Ordering Platform that the kitchen has started preparing the order. This is performed through the Order Started endpoint.

Order Prepared

When the kitchen staff completes preparing the order, they will click the Complete button on the KDS. This indicates that the kitchen has finished preparing the order. This is performed through the Order Prepared endpoint.

The order can now be picked up by the customer, delivered by the restaurant or picked up by the Food Aggregator for delivery after a driver is assigned. This is the general lifecycle flow of an order.

Order Cancelled

However, there is an alternative flow. In the event the Ordering Platform cancels the order, it must be cancelled on Grubtech. The kitchen staff can also cancel an order due to unavailability of items. Grubtech will grab the order cancellation and either honor this request or deny it based on the current status of the order. This is performed through the Order Canceled endpoint. It allows GrubOne to indicate that an order coming from the Ordering Platform is canceled by the partner.

Delivery Status Updates by the Ordering Platform

For orders where the delivery is fulfilled by the Ordering Platform it is recommended that status updates are sent to Grubtech.

Driver Assigned

If the order is picked up for delivery by the food aggregator, they will notify Grubtech when a driver is assigned for the order. This update will include information such as ETA of the driver to the restaurant. If the Ordering Platform sends the order to Grubtech only after a driver is found then this request can be sent immediately after Grubtech accepts the order. This is performed through the Driver Assigned endpoint.

👍

Driver ETA is one of the most important pieces of information that can help a partner optimize their kitchen operation. Providing this information will help you stand out amongst other Ordering Platforms.

Driver Arrived

The driver has arrived to pick up the order, the food aggregator will send the Driver Arrived notification to Grubtech. This is performed through the Driver Arrived endpoint.

Delivery Started

When the driver picks up the order for delivery, the food aggregator notifies Grubtech that the delivery is started. This is performed through the Delivery Started endpoint.

Delivery Completed

The driver has completed the food delivery. The food aggregator notifies Grubtech that the delivery is completed. This is performed through the Delivery Completed endpoint.

NOTE: Delivery Status Updates endpoints are only applicable if the Order Platform (Food Aggregator) is handling the delivery for the order.

The notifications sent by the Food Aggregator are displayed on grubOps - the customer support portal.

Restaurant Delivered Orders

For orders where the delivery is fulfilled by the restaurant, Grubtech sends the status update to the Ordering Platform to indicate that the order is dispatched to the customer. It is mandatory to fill out the delivery details for the order in this flow.

Pick-Up Orders

For orders where the customer picks-up the order, Grubtech sends the status update to the Ordering Platform to indicate that the order is dispatched to the customer.

Scheduled Orders

gOnline supports orders that need to be prepared at a future date and time. We call these scheduled orders. gOnline does not have any validations on the scheduled order time. It is the responsibility of the Ordering Platform to validate if the scheduled order time is sensible. For example, a scheduled order that needs to delivered in 10 minutes or after one month is not practical. When a scheduled order is placed, gOnline forwards the order to the store in real-time and it is shown on grubOPS as a scheduled order. Any order with the scheduledOrder attribute is considered a scheduled order.

Payment Options

gOnline supports the following payment options. You need to use the payment.paymentStatus in combination with payment.paymentMethod to indicate which payment option is used for the order.

• Please note that, when using LOYALTY_POINTS or VOUCHER as the paymentMethod, payment amount must be equivalent to the actual currency amount of the order.

Loyalty Points

gOnline offers the flexibility to provide more information about how Loyalty points have been utilized for a given order. You can send information related to Loyalty Points in a dedicated space given under the payment section of the order payload payment.loyaltyPoints. Please refer to the following sample payload for more information related to Loyalty points.

{
  "id": "234123898712389722",
  "displayId": "10130",
  ...
  "payment": {
    "status": "PREPAID",
    "method": null,
    "charges": {
      "subTotal": {
        "amount": 1000,
        "currencyCode": "AED",
        "formattedAmount": "AED 10.00"
      },
      "total": {
        "amount": 1600,
        "currencyCode": "AED",
        "formattedAmount": "AED 16.00"
      },
      "deliveryFee": {
        "amount": 600,
        "currencyCode": "AED",
        "formattedAmount": "AED 6.00"
      }
    },
    "discounts": [],
    "tax": [
      {
        "amount": {
          "amount": 200,
          "currencyCode": "AED",
          "formattedAmount": "AED 2.00"
        },
        "name": "VAT"
      }
    ],
    "settlements": [
      {
        "method": "CARD",
        "amount": {
          "amount": 1000,
          "currencyCode": "AED",
          "formattedAmount": "AED 10.00"
        },
        "notes": "10 paid in cash"
      },
      {
        "method": "LOYALTY_POINTS",
        "amount": {
          "amount": 600,
          "currencyCode": "AED",
          "formattedAmount": "AED 6.00"
        },
        "notes": "6 utilized using loyalty points"
      }
    ],
    "loyaltyPoints": {
      "system" : "SIMPLEX_LOYALTY",
      "points" : "6",
      "reference" : "LSFS67DSW19",
      "notes": "6 loyalty points have been utilized from Simplex Club"
    }
  },
  ...
}

Multiple Payment Settlements

Multiple payment settlements are an accepted payment option in gOnline. For a given order, payment can be settled via multiple payment methods. If payment is settled by multiple settlements, we expect payment.paymentMethod to be null and payment.settlements to contain one or more entries.

Sample order payload with multiple payment settlements is given below.

{
  "id": "234123898712389722",
  "displayId": "10130",
  ...
  "payment": {
    "status": "PREPAID",
    "method": null,
    "charges": {
      "subTotal": {
        "amount": 1000,
        "currencyCode": "AED",
        "formattedAmount": "AED 10.00"
      },
      "total": {
        "amount": 1600,
        "currencyCode": "AED",
        "formattedAmount": "AED 16.00"
      },
      "deliveryFee": {
        "amount": 600,
        "currencyCode": "AED",
        "formattedAmount": "AED 6.00"
      }
    },
    "discounts": [],
    "tax": [
      {
        "amount": {
          "amount": 200,
          "currencyCode": "AED",
          "formattedAmount": "AED 2.00"
        },
        "name": "VAT"
      }
    ],
    "settlements": [
      {
        "method": "CARD",
        "amount": {
          "amount": 600,
          "currencyCode": "AED",
          "formattedAmount": "AED 6.00"
        }
      },
      {
        "method": "LOYALTY_POINTS",
        "amount": {
          "amount": 1000,
          "currencyCode": "AED",
          "formattedAmount": "AED 10.00"
        },
        "notes": "10 AED redeemed using 100 loyalty points"
      }
    ],
    "loyaltyPoints": {
      "system" : "SIMPLEX_LOYALTY",
      "points" : "100",
      "reference" : "KHSD67SDW92SD"
    }
  },
  ...
}

Handling Discounts

The Ordering Platform should not include any discounts provided by the food aggregator to the customers. The Ordering Platform should only include discounts given by the partner to the customers.

📘

Ensure that you correctly identify platform discounts from partner discounts. Correct discount information should be passed to Grubtech as partners rely on reports generated by Grubtech for reconciliations.