Use Cases - Endpoints Explained#

There is a lot you can do with an /Orders (Partner Picking) integration. Here’s a quick list below

Use below links to jump to the topic:

• Overview of PUT endpoint

• Via PUT endpoint you can perform following actions

  • Accept an order (Vendor Delivery only)

  • Fulfill an order

  • Partial fulfilment of an order

  • Modify items in order and fulfil order

  • Modify weight of an item and fulfil order

  • Replace out-of-stock item

  • Add a new item to the order

  • Update the cart to validate the changes (optional)

• Retrieve order history using the GET endpoints

  • Retrieve single order details

  • Retrieve multiple orders details

Overview of PUT endpoint#

Check API Specifications

The PUT endpoint on order uuid ({order_id}) is used to fulfill, modify, and replace items in the orders. Orders created by the customers are sent to your configured webhook with RECEIVED status. Your picking devices can integrate the PUT endpoint to process orders.

Following are the available order and item level statuses:

Partner Picking Integrations allow you choose preferred delivery flows:

• Platform Delivery: Platform riders will be delivering the orders to the customer. READY_FOR_PICKUP order status should be used to fulfil the order with this delivery flow. You're expected to receive order status to your webhook

  • RECEIVED

  • READY_FOR_PICKUP

  • DISPATCHED

  • CANCELLED

• Vendor Delivery: You need to arrange the logistics for delivering orders to the customer. You are expected to use the PUT endpoint to progress the order through the following sequence:

  PUT requests you send:

  • ACCEPTED (optional) — acknowledge the order after receipt, before dispatching. Requires accepted_for timestamp.

  • DISPATCHED — fulfil the order once ready for delivery.

  Webhook events you will receive:

  • RECEIVED — order created by the customer

  • READY_FOR_PICKUP — confirmation sent after your DISPATCHED PUT request succeeds

  • CANCELLED — order cancelled by customer or logistics

Identifying delivery flow and order type from the webhook payload#

Every incoming order webhook event includes two fields your system should use to route processing logic:

Fulfilling guide by field value:

• transport_type: LOGISTICS_DELIVERY → Platform Delivery flow. Fulfil with READY_FOR_PICKUP. Platform rider will pick up the order.

• transport_type: VENDOR_DELIVERY → Vendor Delivery flow. Fulfil with DISPATCHED (optionally preceded by ACCEPTED). You arrange delivery.

• order_type: PICKUP → Customer collects in-store. Suppress delivery address display in your picking UI. Use READY_FOR_PICKUP to fulfil.

• Item status:

  • IN_CART, item is added to the cart by the picker

  • NOT_FOUND, item not available at store

  • NOT_PROCESSED, initial status of an item when received to your webhook

  • REPLACED, item has been removed from the order with a replacement.

  • ADDITION, new additional item added to the order

Order identifiers in the webhook payload#

Each incoming order webhook event contains three distinct identifiers:

Timings in the webhook payload#

The webhook payload includes additional fields your system should parse to handle order routing and display correctly:

Timing fields:

Loyalty program:

original_pricing object reference: item level inforamtion when customer placed the order

promotion array reference: item-level promotions applied at order creation

Below are possible scenarios to fulfill an order using PUT endpoint, you can find the request body for each scenario please adjust it accordingly to your requirements.

1) Accept an order using the PUT endpoint (Vendor Delivery only)#

Check API Specifications

Purpose: Acknowledge that your store has received and accepted the order, before dispatching it. This is an optional intermediate step available exclusively to Vendor Delivery partners.

How does it work?

• Send a PUT request with status: ACCEPTED after receiving the RECEIVED webhook event

• The accepted_for field is required when using ACCEPTED status — it sets the estimated delivery time for the order

• accepted_for must be a valid ISO 8601 datetime (e.g. 2024-09-11T12:00:00Z)

• After accepting, send a separate PUT request with status: DISPATCHED to fulfil the order

Request:

curl --location --request PUT 'https://glovo.partner.deliveryhero.io/v2/chains/9d4a63b5-3e07-4440-96af-aa04797da3a0/orders/807c225f-ac6d-445d-a074-ea960c892ca7' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
   "order_id": "807c225f-ac6d-445d-a074-ea960c892ca7",  // required
   "status": "ACCEPTED",                                  // required — Vendor Delivery only
   "accepted_for": "2024-09-11T12:00:00Z",               // required when status is ACCEPTED; ISO 8601 UTC
   "items": [
       {
           "sku": "222316",
           "pricing": {
               "pricing_type": "UNIT",
               "unit_price": 85,
               "quantity": 2
           },
           "status": "IN_CART"
       }
   ]
}'

Response: 200 as success. No webhook event is triggered by the ACCEPTED status.

2) Fulfill an order via the PUT endpoint with optional confirmed_amount#

Check API Specifications

Purpose: Complete order fulfillment, depending on your chosen delivery flows you can fulfil an order using READY_FOR_PICKUP or DISPATCHED order status

How does it work?
Order and item level status are to be considered while fulfilling the order.

• Item status

  • IN_CART should be used for picked item

• Order Status

  • READY_FOR_PICKUP to be used for fulfillment if you are using Platform Delivery

  • DISPATCHED to be used for fulfillment if you are using Vendor Delivery

The request below demonstrates fulfillment in the Platform delivery flow. Upon a successful request, you should receive an HTTP status `200`, along with the corresponding order fulfillment confirmation sent to your webhook.

curl --location --request PUT 'https://glovo.partner.deliveryhero.io/v2/chains/9d4a63b5-3e07-4440-96af-aa04797da3a0/orders/807c225f-ac6d-445d-a074-ea960c892ca7' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data "order_id": "807c225f-ac6d-445d-a074-ea960c892ca7",
   "items": [
       {
           "sku": "222316",
           "pricing": {
               "pricing_type": "UNIT",
               "unit_price": 85,
               "quantity": 2,
               "min_quantity": 0,  //optional
               "max_quantity": 2   //optional
           },
           "status": "IN_CART" // required item level status
       },
       {
           "sku": "146344",
           "pricing": {
               "pricing_type": "UNIT",
               "total_price": 14,
               "quantity": 1,
               "min_quantity": 0, //optional
               "max_quantity": 1  //optional
           },
           "status": "IN_CART" // required item level status
       }
   ],
   "status": "READY_FOR_PICKUP" or "DISPATCHED", // required order status, use READY_FOR_PICKUP Logicstis deliverery & DISPATCHED for vendor delivery
   "confirmed_amount": 99.00                       // optional — see note below
}

Response: 200 as success with above request body

3) Partial fulfillment of an order using the PUT endpoint#

Check API Specifications

Purpose: Fulfill an order that includes both out-of-stock and available items from the store, ensuring that no items from the order are omitted.

How does it work?
Order and item level status are to be considered while fulfilling the order.

• Item status

  • IN_CART should be used for picked item

  • NOT_FOUND can be used for out-of-stock items

• Order status

  • READY_FOR_PICKUP to be used for fulfillment if you are using Platform Delivery

  • DISPATCHED to be used for Vendor Delivery

The request below demonstrates fulfillment in the Platform delivery flow. A Successful request should have HTTP status 200 with corresponding order fulfillment confirmation is sent to your webhook.

curl --location --request PUT 'https://glovo.partner.deliveryhero.io/v2/chains/9d4a63b5-3e07-4440-96af-aa04797da3a0/orders/807c225f-ac6d-445d-a074-ea960c892ca7'
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data

   "order_id": "807c225f-ac6d-445d-a074-ea960c892ca7",
   "items": [
       {
           "sku": "222316",
           "pricing": {
               "pricing_type": "UNIT",
               "unit_price": 85,
               "quantity": 2,
               "min_quantity": 0,
               "max_quantity": 2
           },
           "status": "NOT_FOUND"
       },
       {
           "sku": "146344",
           "pricing": {
               "pricing_type": "UNIT",
               "total_price": 14,
               "quantity": 1,
               "min_quantity": 0,
               "max_quantity": 1
           },
           "status": "IN_CART"
       }
   ],
   "status": "READY_FOR_PICKUP" or "DISPATCHED"
}

Response: 200 as success with above request body

4) Modify items in order and fulfill using the PUT endpoint#

Check API Specifications

Purpose:
You can adjust the quantity of items in the order and fulfil it in a single PUT request. For an item with `“item.pricing_type": "UNIT"` you can modify the `quantity` field

How It Works:

• To adjust the items information items.pricing object to be utilised

• To modify the quantity, ensure the value is within the min_quantity and max_quantity range provided in the order

• Price modifications apply to items with "pricing_type": "UNIT":

  • unit_price can only be decreased, not increased. Attempting to increase unit_price will be rejected.

  • total_price can be increased or decreased at the item level.

curl --location --request PUT 'https://glovo.partner.deliveryhero.io/v2/chains/9d4a63b5-3e07-4440-96af-aa04797da3a0/orders/807c225f-ac6d-445d-a074-ea960c892ca7'
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data

   "order_id": "807c225f-ac6d-445d-a074-ea960c892ca7",
   "items": [
       {
           "sku": "222316",
           "pricing": {
               "pricing_type": "UNIT",
               "unit_price": 85,
               "quantity": 1, // change
               "min_quantity": 0,
               "max_quantity": 2
           },
           "status": "IN_CART"
       },
       {
           "sku": "146344",
           "pricing": {
               "pricing_type": "UNIT",
               "total_price": 14,
               "quantity": 1,
               "min_quantity": 0,
               "max_quantity": 1
           },
           "status": "IN_CART"
       }
   ],
   "status": "READY_FOR_PICKUP" or DISPATCHED
}

Response: 200 as success with above request body

5) Modify weight of an item and fulfill order using the PUT endpoint#

Check API Specifications

Purpose:
You can adjust the weight of items in the order and fulfil it in a single PUT request. For "items.pricing_type": "KG" you should use only weight field

How It Works:

• To adjust the items information items.pricing object to be utilised

• weight to used for modification it should be a decimal value (eg. 1.0, 2.25 etc)

• To modify the weight, ensure the value is in the range of min_quantity and max_quantity of item

• Price modifications are not allowed. Changes to weight will automatically adjust the price

• quantity field is shared at item level, no action is required on this field it has a default value 1

• A successful request returns an HTTP status 200, and the order fulfillment confirmation is sent to your webhook.

curl --location --request PUT 'https://glovo.partner.deliveryhero.io/v2/chains/9d4a63b5-3e07-4440-96af-aa04797da3a0/orders/807c225f-ac6d-445d-a074-ea960c892ca7'
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data

   "order_id": "807c225f-ac6d-445d-a074-ea960c892ca7",
   "items": [
       {
           "sku": "222316",
           "pricing": {
               "pricing_type": "KG",
               "unit_price": 85,
               "quantity": 1,
		  "weight": 1.5,
               "min_quantity": 0.5,
               "max_quantity": 2.5
           },
           "status": "IN_CART"
       },
       {
           "sku": "146344",
           "pricing": {
               "pricing_type": "UNIT",
               "total_price": 14,
               "quantity": 1,
               "min_quantity": 0,
               "max_quantity": 1
           },
           "status": "IN_CART"
       }
   ],
   "status": "READY_FOR_PICKUP" or DISPATCHED
}

Response: 200 as success with above request body

6) Replace an out-of-stock item in an order using the PUT endpoint#

Check API Specifications

The following outlines the constraints that must take into consideration while build logic around Item Replacement flow.

Constraints Requiring Partner-Side Logic#

These scenarios are technically allowed by the API but are not supported by the Platforms. You MUST implement logic into your systems to prevent these replacement scenarios

Item-Replacement limitations from API#

These functionalities are outside the scope of the current IR-Partner Picking Integrations

Purpose: Replacing an item after checking(via phone call) with customer

How does it work?

1. Only items available in Vendor Catalog (active/inactive) are allowed for replacements

2. If item A is added to the order as a replacement for item B, item B will be marked as REPLACED and removed, while item A will have the status IN_CART. An identifier replaced_id is to be sent which indicates item B is replaced with item A

3. Partners should be able to replace a weighted item with either a weighted or non-weighted item. Pickers must enter the final weight per KG

4. Single PUT request can replace OOS item and fulfill order

5. Customer phone number will be transmitted via order payload

6. Item replacements are available for all Partners Picking Integrated Partners using Partner API

Request:

curl --location --request PUT 'https://glovo.partner.deliveryhero.io/v2/chains/9d4a63b5-3e07-4440-96af-aa04797da3a0/orders/807c225f-ac6d-445d-a074-ea960c892ca7' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data


   "order_id": "807c225f-ac6d-445d-a074-ea960c892ca7",
   "items": [ 								// required
        {
	    "_id": "796ee50e-2cb5-41ec-8a06-4208fe15dcb3",			// required for REPLACED status items; omitting _id returns a 400 error
            "sku": "222316",							// required — do not use _id alone
            "name": "Pepsi",
            "pricing": {							// required
                "pricing_type": "UNIT",					// required
                "unit_price": 85,   // optional,either of  unit_price or total_price to be used to change price but not both
                "quantity": 2, 						// optional,
               },"status": "REPLACED" 						// required
        },{
            "_id": "a5e42c90-351f-4c64-be7a-7dace4b96033", 	// optional
	     "sku": "146344",						// required — do not use _id alone
	     “replaced_id":"796ee50e-2cb5-41ec-8a06-4208fe15dcb3" //required –OOS item _id should be include as replaced_id
            "name": "cola",
            "pricing": { 							// required
                "pricing_type": "UNIT",
                "unit_price": 14,	 // optional,change is possible on either of  unit_price or total_price but not both
		  “quantity": 2 						// required,
               },
            "status": "IN_CART" 						// required
        }],"status": "READY_FOR_PICKUP" 				 	// required

Response: 200 as success with above request body

replacement_preferences object reference: We have pre-checkout replacement functionality, where customer can share replacement suggestion during order creation stage and in order and replacement preferences are transmitted to your webhook on RECEIVED status. For more information check the FAQ

7) Add additional item to order using the PUT endpoint#

Check API Specifications

Used for: if you want to add new items to the customer order e.g. carry bags

How does it work?

1. Multiple items can be added in a single request, with ADDITION item level status

2. If an item already exists in the order, it will be added as a separate entry as long as mandatory fields are provided.

3. Example: If "Cola" is in the order and another "Cola" is added, both will appear separately with their respective quantities.

4. If the item does not exist for the vendor, the request fails with an "item not found" error

5. If required attributes for a new item are missing, the request fails with an "invalid cart update" error

6. Required fields for adding additional Items to order:

   sku: required for product hydration.
   pricing.quantity: required
   pricing.weight: required for weighted items
   pricing.unit_price: optional, Vendors can set a unit price for the additional item, overriding the original price If not provided, the order will use the price from the item hydration

Request:

curl --location --request PUT 'https://glovo.partner.deliveryhero.io/v2/chains/9d4a63b5-3e07-4440-96af-aa04797da3a0/orders/807c225f-ac6d-445d-a074-ea960c892ca7' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data


   “order_id”: “807c225f-ac6d-445d-a074-ea960c892ca7”,
   “items”: [ 								// required
        {
            “sku”: “146344”,						// item.sku is required
            “name”: “cola”,
            “pricing”: { 							// required
                “pricing_type”: “UNIT”,
                “unit_price”: 14,	 //optional, If not provided price registered in the catalog will be used
		  “quantity”: 2 						// required
               },
            “status”: “ADDITION” 						// required new status
        }
   ],
   “status”: “READY_FOR_PICKUP”

Response: 200 as success with above request body

8) Review items and update the cart using the PUT endpoint#

Check API Specifications

Purpose: If you want to update the cart to validate changes with our platform on item quantity, weight, additions or replacements before finalizing the order with fulfillment status.

How does it work?
The UPDATE_CART order status allows you to modify items in an order and receive immediate feedback.

• UPDATE_CART is just for quick feedback (running validations and checks) response to you while picking, there is no actual change in the order status on this operation. No webhook event is shared

• You can call PUT with UPDATE_CART as many times as needed to ensure the order contains the correct set of items

• UPDATE_CART is an optional status, it can be integrated into your existing operations

• If you want to update price, quantity, add items, or make replacements, they can push the changes first with UPDATE_CART status. & READY_FOR_PICKUP status must be used for completing the order fulfilment

Request:

curl --location --request PUT 'https://glovo.partner.deliveryhero.io/v2/chains/9d4a63b5-3e07-4440-96af-aa04797da3a0/orders/807c225f-ac6d-445d-a074-ea960c892ca7' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data


   "order_id": "807c225f-ac6d-445d-a074-ea960c892ca7", 			// required
    "items": [ 								// required
        {
	    "_id": "796ee50e-2cb5-41ec-8a06-4208fe15dcb3",			// optional
            "sku": "222316",							// required — do not use _id alone
            "name": "Pepsi",
            "pricing": {							// required
                "pricing_type": "KG",					// required
                "unit_price": 85,// optional,either of  unit_price or total_price to be used to change price but not both
                "quantity": 1, 						// optional,
		"weight": 1.3 					// required for weighted items
               },"status": "IN_CART" 						// required
        },{
            "_id": "a5e42c90-351f-4c64-be7a-7dace4b96033",
	     "sku": "146344",						//  item.sku is required

            "name": "cola",
            "pricing": { 							// required
                "pricing_type": "UNIT",
                "unit_price": 14,	 // optional,change is possible on either of  unit_price or total_price but not both
		  “quantity": 2 						// required
               },
           "status": "IN_CART" 						        }],"status": "UPDATE_CART" 	// required !new status!

Retrieve historic orders with our GET endpoint#

You will be able to request order Information on:

• Single order

• Multiple orders

Retrieve single order details#

Purpose:
If you want to check the status of an individual order using GET endpoint /order_id

How It Works:
The GET Order ID endpoint allows you to retrieve details of a specific order from our Order Transmission Service.

• The Order ID must be in UUID format (e.g. 807c225f-ac6d-445d-a074-ea960c892ca7).

• Refer to the order_id field in the order payload.

• Only orders from the past 60 days can be accessed through this endpoint.

Request:

curl --location  --request GET 'https://glovo.partner.deliveryhero.io/v2/chains/9d4a63b5-3e07-4440-96af-aa04797da3a0/orders/807c225f-ac6d-445d-a074-ea960c892ca7' \
--header 'Accept: application/json' \
--header 'Authorization: ***

Response: HTTP 200 with order object

Retrieve multiple orders details#

Purpose:
If you need to fetch order history from a specific store.

How It Works:
The Vendor ID endpoint allows you to specify a date range to retrieve store orders. Only orders from the last 60 days are accessible.

Allowed GET Request Parameters:

• start_time – Start date & time should be in UTC (e.g., 2024-09-11T10:40:00).

• end_time – End date & time should be in UTC (e.g., 2024-08-12T12:40:00, max 60-day range).

• page_size – Number of orders per page. Accepted range: 1–500 (default: 20).

• page – Page number of results (default: 1).

Pagination response fields:

Request:

curl --location 'https://glovo.partner.deliveryhero.io/v2/chains/{chain_id}/vendors/7253942?start_time=2024-09-11T10%3A40%3A00&end_time=2024-09-12T12%3A40%3A00&page_size=&page=' \
--header 'Content-Type: application/json' \
--header 'Authorization: ***' \
--data ''

Response: 200 with orders array object

Below are the Error codes observed while integrating with GET endpoints**:**

• 400 bad request is observed when the request body is not valid

• 401 Unauthorised is observed when token is not valid

• 404 Not found is observed when order is not available in our DB