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

  • Fulfill an order
  • Partial fulfilment of an order
  • Modify items in order and fulfil order
  • Modify weight of an item and fulfil order
  • Cancel an 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:

• Order status:

  • RECEIVED, sent by our service to your webhook when an order is created
  • READY_FOR_PICKUP, status is sent to your webhook as a confirmation when the order is fulfilled by using PUT endpoint
  • DISPATCHED,
    • For Platform Delivery flow: status is automatically sent by our service to your webhook after order is picked up by the rider
    • For Vendor Delivery flow: status is sent to your webhook as a confirmation when the order is fulfilled by using PUT endpoint
  • CANCELLED, event is sent by our service when an order is canceled by the customer, or logistics.
  • UPDATE_CART, status is used for item modifications using the PUT endpoint. No webhook event is triggered. Must be use before order fulfilment statues i.e. READY_FOR_PICKUP or`DISPATCHED`

• 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

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 in the following order
  • RECEIVED
  • READY_FOR_PICKUP
  • DISPATCHED
  • CANCELLED
• Vendor Delivery: You need to arrange the logistics for delivering orders to the customer. DISPATCHED order status should be used to fulfil the order with this delivery flow. You're expected to receive order status to your webhook in the following order
  • RECEIVED
  • DISPATCHED
  • CANCELLED

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

1) Fulfill an order via the PUT endpoint#

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 fulfilment if you are using Platform Delivery
  • DISPATCHED to be used for fulfilment 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://foodora.partner.deliveryhero.io/v2/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
}

Response: 200 with the above request body

2) Partial fulfilment 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 fulfilment 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 fulfilment confirmation is sent to your webhook.

curl --location --request PUT 'https://foodora.partner.deliveryhero.io/v2/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 with above request body

3) Modify items in order and fulfil 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". Either unit_price or total_price to be adjusted in the request body, but not both.
• A successful request returns an HTTP status 200, and the order fulfillment confirmation is sent to your webhook.

curl --location --request PUT 'https://foodora.partner.deliveryhero.io/v2/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 with above request body

4) Modify weight of an item and fulfil 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://foodora.partner.deliveryhero.io/v2/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 with above request body

5) Cancel an order using the PUT endpoint#

Check API Specifications

Purpose:
Used for canceling an order

How It Works:

• If the partner initiates a cancellation, a cancellation object with a valid reason must be sent.
• Valid reasons: CLOSED, ITEM_UNAVAILABLE, TOO_BUSY
• A successful request returns HTTP status 200.

Request:

curl --location --request PUT 'https://foodora.partner.deliveryhero.io/v2/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": "NOT_FOUND"
       },
       {
           "sku": "146344",
           "pricing": {
               "pricing_type": "UNIT",
               "total_price": 14,
               "quantity": 1,
               "min_quantity": 0,
               "max_quantity": 1
           },
           "status": "NOT_FOUND"
       }
   ],
       "cancellation": {
       "reason": "CLOSED", //required 
   },


   "status": "CANCELLED"  
}

Response: 200 with above request body

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

Check API Specifications

Purpose: Replacing an item after checking 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 fulfil 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://foodora.partner.deliveryhero.io/v2/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",			// item.id or item.sku is required
            "sku": "222316",							// item.id or item.sku is required
            "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", 	// item.id or item.sku is required
	     "sku": "146344",						//  item.id or item.sku is required
	     “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 with above request body

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://foodora.partner.deliveryhero.io/v2/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",			// item.id or item.sku is required
            "sku": "222316",							// item.id or item.sku is required
            "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", 	// item.id or item.sku is required
	     "sku": "146344",						//  item.id or 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": "ADDITION" 						// required new status
        }],"status": "READY_FOR_PICKUP"

Response: 200 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://foodora.partner.deliveryhero.io/v2/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",
   "order_id": "807c225f-ac6d-445d-a074-ea960c892ca7", 			// required
    "items": [ 								// required
        {
	    "_id": "796ee50e-2cb5-41ec-8a06-4208fe15dcb3",			// item.id or item.sku is required
            "sku": "222316",							// item.id or item.sku is required
            "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
	     “replaced_id":"null" 					//optional 
            "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://foodora.partner.deliveryhero.io/v2/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 (default: 20).
• page – Page number of results (default: 1).

Request:

curl --location 'https://foodora.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