# Q-Commerce Partner API (POS & Assortment APIs)

# Introduction: The Partner API

The Partner API is the name given to two APIs which enable vendors to self-manage and automate the order transmission & item-management process, thereby allowing for a smoother and more reactive purchase experience for end users.

The two elements of the Partner API are as follows:

• Order Transmission API - which governs the POS integration between our vendor partners & Delivery Hero, & allows our partners to receive and manage incoming orders.
• Assortment API - which allows vendors to manage individual (or bulk) purchasable items (amending features such as price/status/quantity) which have been added to the shop.

To reduce complexity for our partners, both of the APIs described above make use of one single ‘Partner API’ token, which is easily accessible via the Shops Integrations page of Vendor Portal.

# How To Get Partner API Credentials (Token Issuance)

Anyone with access to Vendor Portal with their own vendor store or chain configured will be able to access the Partner API token. This token is universal for both APIs within the Partner API, therefore this one set of credentials applies to both the Assortment API & the Order Transmission/POS API. In order to access the token, simply follow these steps (we have also provided an image below):

1. Click on the ‘Shops Integration’ Tab of the Vendor Portal homepage (located on the left-hand side of the screen - please see the image below of the Vendor Portal homepage)
2. Click ‘Token Management’ and ‘Generate New Token’ - you can do this either for an individual vendor, or tokens can be generated at the chain level
3. Copy the token credentials somewhere safe for future reference.

After generating the token for each API, it's time to apply them in practice, using the below information on both the Order Transmission (POS) API, & the Assortment API

# Webhook Configurations

Webhook is a digital notepad to receive the payloads from the Service provider, mostly for events that are not directly initiated by the vendor itself.

Being in the form of the url, webhook can be provided From the domain/url of the vendor Or from any other 3rd party source, such as webhook.site

# What information can be retrieved on webhooks using our Partner APIs?

# Order Transmission API

The vendor that is using Pelican Picking application can follow/receive and store all the changes in the statuses of the order via configuring the webhook. These are the examples of the statuses initiated by the service provider (Delivery Hero):

• Logistics delivery (When the order is delivered by Delivery Hero)

  • RECEIVED - This is the initial status of the order. This status means that the order processing has not yet started by the partner.
  • READY_FOR_PICKUP- Order picking and packing is finished by the partner and is ready for pickup by a delivery rider.
  • CANCELED - Order is canceled by the customer, delivery rider or the partner.
  • DELIVERED - Order is delivered to the customer.

• Vendor delivery (When the order is delivered by the rider of the vendor)

  • RECEIVED - This is the initial status of the order. This status means that the order processing has not yet started by the partner.
  • READY_FOR_PICKUP- Order picking and packing is finished by the partner and is ready for pickup by a delivery rider.
  • DISPATCHED - Order picking and packing is finished, and also is dispatched to the delivery rider for last mile delivery to the customer
  • CANCELED - Order is canceled by the customer, delivery rider or the partner.

# Assortment API

Vendor can export the information about all of its products from Delivery Hero system as a csv file, and for this the webhook to send the url to download the file should be provided. More information can be found here. Also, after each update of the bulk product endpoint, the url of the csv file is sent to the assigned webhook to see the results of the job for product/row level granularity.

# How can a vendor configure the webhook for an Assortment API and Order Transmission API?

Vendor needs access to the Vendor Portal, Shops Integrations plugin to configure the URL in the respective tabs of the plugin. In order to see the URL, the user needs to have an administrator account rights.

# The Order Transmission API (POS)

The Order Transmission API enables our partners to receive and manage incoming orders from Delivery Hero, using the POS API. Potential users of the POS Integration API are the supermarkets and the POS service providers who are technically capable of configuring their own ERP/ POS systems to interact with the Order Transmission API.

# Key Features of the Order Transmission API (POS)

The POS API is highly customisable in order to easily fit into the existing order management flow of any of our partners. In order to use the POS API, partners can select from one of the two following methods of integration:

• Fulfil orders using their own picking solution (known as a ‘Direct Integration’) and then call the Order Transmission API to complete/modify/update the order status
• Fulfil orders using the Delivery Hero Pelican application (known as an ‘Indirect Integration’)

There are a total of four options a vendor can choose for picking & delivery when integrating the Order Transmission API, across either Direct or Indirect integrations. Each of these options are available to vendors who would use Delivery Hero to both pick & deliver ordered items (known as a ‘Logistics Delivery’), or for vendors who wish to deliver items using their own delivery solution (known as ‘Own Delivery’). Each of the four options are demonstrated in the table below:

What follows is a detailed overview of both Direct and Indirect Integration methods & their individual benefits & characteristics.

1. Direct Integration - Partners can fulfill orders using their own POS systems. The following illustration explains the overall order flow with Direct Integration. Refer to this API documentation: https://partners-stg.deliveryhero.io/redoc/ for more details and try our API with the test environment provided.

2. Indirect Integration - Partners can fulfill orders using Delivery Hero’s pelican application. Once the order is fulfilled, they will receive a copy of the order in their webhook. The following illustration explains the overall order flow with Indirect Integration. Refer to this API documentation: https://partners-stg.deliveryhero.io/redoc/ for more details and try our API with the test environment provided.

# How to Create a Test Order

In order to create a test order, carry out the following steps:

1. Insert the vendor’s webhook URL
2. Select ‘Test’ (see image below)
3. The vendor will then receive the order and can call Central’s API and start fulfilling the order in Pelican.

# Known Constraints

Known constraints and errors for the Order Transmission API are currently under construction - please check back soon for the latest information on any constraints currently impacting the service.

# Supported Regions & Platforms

The POS API is currently accessible via the platforms and countries listed below. If you don't find the platform you are looking for, please reach out to your local Delivery Hero representative.

# Asia/Pacific

[https://partners-ap.deliveryhero.io/redoc/

Foodpanda (Bangladesh, Cambodia, Hong Kong, Japan, Laos, Malaysia, Myanmar, Pakistan, Philippines, Singapore, Taiwan, Thailand)

# Europe

[https://partners-eu.deliveryhero.io/redoc/

Damejidlo (Czech Republic)
Foodora (Finland, Sweden, Norway)
Mjam (Austria)
Foodpanda (Germany, Hungary, Romania)

# Middle East/ North Africa

[https://partners-me.deliveryhero.io/redoc/]

Hungerstation (Saudi Arabia) Talabat (Bahrain, Egypt, Jordan,Kuwait, Oman, Qatar, United Arab Emirates)

Hungerstation (Saudi Arabia)
Talabat (Bahrain, Egypt, Jordan,Kuwait, Oman, Qatar, United Arab Emirates)

# Introduction: The Assortment API

The Assortment API is used to manage the items which are defined in the Vendor Portal (Catalog & PIM applications). Potential users of the Assortment API are vendors who would like to render the availability, name, price, and other features of a saleable product. Once the items eligible for the sales are added to the PIM and Catalog application, the vendor can maintain its attributes easily through the API. This API can be used by the vendor to automate the following processes:

• Product price
• Barcode (for the bulk update endpoint)
• Status (active/inactive)
• Quantity of the product

The system makes calculations every time it receives quantity info, and the API automatically deactivates a product based on quantity thresholds held within the system logic.

# What is an Assortment API?

The Assortment API is used by vendors to manage product-related information directly through the ERP or POS. The API provides a convenient and efficient way for vendors to retrieve and update information such as product price, barcode, status, and quantity.

# Why do you need an Assortment API?

Reduce the gap between online and offline assortments, this enables vendors to effectively monitor stock levels with high availability

Update the assortment information, an API allows vendors to easily retrieve and update information such as product price, barcode, status, and quantity which reduces out-of-stock and partial fulfillment of products

Improve vendor sales, by ensuring that product information is accurate and up-to-date, vendors can improve the customer experience and can drive higher sales volumes

# What are the use cases for Assortment API?

Product information updates, API allows vendors to update information such as product price, barcode, status, and quantity. This helps to ensure that the product information in the Vendor Portal is always up-to-date and accurate

Bulk update capability, API includes a bulk update feature that enables vendors to efficiently update multiple products at once, reducing the time and effort required to manage their product information

Automated processes, The system makes calculations every time it receives quantity info, and the API automatically deactivates a product based on quantity thresholds held within the system logic

Real-time product availability, API allows vendors to check the availability of products in real-time so that they can quickly and easily inform customers if a product is out of stock

Integration with other systems, API can be integrated with other systems, such as the vendor's ERP system, to streamline product management processes and reduce manual errors

# What are the features of Assortment API?

Assortment API has 3 endpoints, among which /product and /product-bulk are PUT endpoints and /export endpoint is POST

1- /product endpoint is used to update single product information whereas /product-bulk is used to update multiple products information in a single request

2- If a webhook is configured by the Vendor, /product-bulk can provide results asynchronously on the current update at sku level Assortment API - Product level response

3- /export endpoint is used to download the whole assortment data as CSV Assortment API - Export endpoint

4- Limits the number of products that can be ordered in a single order Max sales quantity– product-bulk

# Product Level Response– Assortment API bulk-update

# Why is it important to have product-based visibility?

Currently, Vendors don’t know the status of their updates via Assortment API. This feature will enable the vendors to see the result of the current bulk update job, not only for the command but also for each row/product within the payload. This way the vendor has transparency and visibility to follow the product level changes via Assortment API

# What are the prerequisites for a vendor to use this feature?

• The vendor uses Assortment API to maintain product information (only the Qcommerce flow is considered)
• The vendor should able to provide a webhook URL to receive a link to download a .csv file
• The vendor must have an access to Vendor Portal, where he should configure the webhook
• Any software on the vendor’s side that can open the .csv file (UTF-8 format)

# Where can vendors configure a webhook?

Vendors must have access to the Vendor Portal, inside the Shop Integrations plugin Vendors can configure the webhook in Payload URL and Secret can be anything. See the screenshot below

# How does a vendor get feedback on bulk updates using Assortment API?

The vendor can perform a regular bulk update using the new PUT endpoint with vendor-id, below is the link endpoint /api/assortment/v1/vendors/{vendorId}/products/products-bulk

The Job is processed asynchronously, and eventually, the vendor will receive a notification to their configured webhook with a payload containing a URL to download the CSV file. A sample notification is shown below.

{
"jobId": 276477,
"platformVendorId": "<vendor_id>",
"status": "COMPLETED",
"downloadURL": "<download_url>"
}

The vendor can call GET on the download URL with the Authorization header and retrieve the SKU-level status updates contains(both successes and failures). This content can be downloaded as JSON or CSV depending on the use case.

# What does the downloaded JSON/CSV contain?

The downloaded file contains the vendor's current update results on sku level, which might be a large payload for the vendor-consuming services.

sku, product identifier

code, 

state, the status of product update

new, if there is a new product that is added to the bulk update not available in the catalog yet

unchanged, if the product has no modifications within the current bulk-update  

updated, if the product has been updated in the current bulk-update

errors, any visible errors are shown here  

row_number, shows the row number at which the product was updated 

piece_barcode, the barcode of the product

Below is a sample .csv file with its contents

 "sku", "code", "state", "errors", "row_number", "piece_barcode"
 "AMLXBK, "",   "unchanged", "null, "2", ""
 "NewSku", "",   "new",   "null", "3",  ""
 "OH71AB,  "", "updated",  "null", "4", ""

# Export– Enhancing Visibility on Entire Assortment using Assortment API

# Why is it important to have an export feature?

This feature will provide vendors using Delivery Hero Q-Commerce's Assortment API with visibility into all of the SKUs managed through the API. Currently, vendors who are updating product details using endpoints product-bulk or product (individual) are unable to see the “is situation” of their assortment at the vendor (not chain) level.

To address this issue, our Vendor Partnership Automation team has developed a feature that provides vendors with comprehensive data about their listed products on the platforms, which can be accessed through a CSV file.

# What are the prerequisites for a vendor to use this feature?

Vendor uses Assortment API to maintain product information (only the Qcommerce flow is considered)

• Vendor can provide a source/URL to receive a link to download a .csv file
• Vendor must have an access to Vendor Portal, where he should configure webhook
• Any software on the vendor’s side that can open the .csv file (UTF-8 format)

# Where can vendors configure a webhook?

Vendors must have access to the Vendor Portal, where they should configure the webhook. See the excerpt below

# How does a vendor create an export job using Assortment API?

1. The vendor can create an export job using the new POST endpoint with vendor-id, below is the link endpoint /api/assortment/v1/vendors/{vendorId}/products/export

2. As a response, the vendor receives a job id:

   "job_id": 276477
}

3. The Job is processed asynchronously, and eventually, the vendor will receive a notification to their configured webhook with a payload containing a URL to download the CSV file.

"jobId": 276477, 
"platformVendorId": "<vendor_id>", 
"status": "COMPLETED", 
"downloadURL": "<download_url>" 
}

# What does the downloaded .csv file contain?

The downloaded .csv file contains the vendor's entire assortment data, which may be a large payload for the vendor-consuming services.

SKU (Stock Keeping Unit)

Barcode

Price

Active (1 for active products, 0 for inactive products)

Below is a sample .csv file with its contents

"sku","barcode","price","active"
"11043","9556404120383","3.0","1"
"12357","05449000020055","3.0","1"
"3456","08690624203493","75.0","1"
"FSPHAI","05449000054227","1221.0","1"
"DRWQX2","076840001767","11.0","0"
"HNS937","076840001774","11.0","0"
"HWPF7U","8887500510237","11.0","0"
"XX0HM9","38103195388415","4.0","1"
"HRQZBZ","09556404007059","58.0","1"

# How often is the export feature intended to be used?

The export feature is intended to be used hourly, and it can handle the same throughput as the bulk update POST endpoint.

# Max Sales Quantity– A new field in /product-bulk endpoint of Assortment API

# What is max sales quantity?

Max sales quantity refers to the maximum number of units of a specific product that can be sold by a vendor or store.

# Why is this feature important?

The purpose of setting a maximum sales quantity is to ensure that there is enough product available for all customers who want to purchase it, rather than allowing a few customers to buy large quantities and leaving others with reduced availability. Also, it enables the vendors to comply with government regulations, manage stock availability, or limit the impact of bulk orders.

# How can I use max sales quantity?

Maximum Sales Quantity is an extra field available on the Assortment API /product-bulk PUT endpoint. "maximumSalesQuantity" is an optional field. When this field is defined on an SKU, it limits the number of quantities that a customer can place per order.

Examples: https://www.youtube.com/shorts/GmSKII0Z7m8

# What are the best practices for using Assortment API?

To ensure successful integration with the Assortment API, make sure that the generated Partner API token is valid for the chain, and that the vendor code used in the API request is valid and corresponds to the chain.

# What are the error codes?

These are the expected errors codes with the API

• 400 error, BadRequest– vendor data provided in the 'Authorization' header might not be valid to resolve the error please review the request
• 403 error, Forbidden– Authorisation is not valid– please verify the generated Partner API token of the vendor

# How many SKUs can I send in a product-bulk request?

Our API requests are not based on the number of SKUs but based on the size of the payload. The max API request size is set at 100MB, which means that a vendor can send an update request using API with an assortment/payload size of 100MB and will be consumed by our services. However, We have a Cloudflare limitation which is around 60 requests per minute beyond that Cloudflare assumes requests as DoD and blocks the IP address.

# What is needed to make use of the Assortment API?

In contrast to an Order Transmission API, there is no need to set-up a webhook to use the Assortment API, however there are other steps to follow. The vendor needs to:

• Provide authentication to use the API, via generating the Partner API token
• Develop ‘PUT’ endpoints for both bulk and single product updates
• Sync the Assortment in the POS system with Assortment API (this will allow the vendor to connect the API with the vendor’s ERP system)

# What is the difference between the Assortment API and SFTP?

At first glance, both SFTP and the Assortment API fulfils the same need, eg. providing the most up-to-date information about the items to be offered.

The structure of SFTP is dependent on the EXPORT to CSV/TXT functionality of the ERP system. There must be a periodical extraction & push of data for SFTP to work.

The benefit of SFTP is that it requires little development on the partner side; usually SFTP can be implemented in 2 weeks (with the fact that SFTP server connection is also established). However, the disadvantage is that it is not an event-triggered process.

On the other hand, the Assortment API requires development work by the ERP/POS team of the vendor. The process of integrating the API can take up to one month. The key benefit of this route however is that once the assortment information is updated in the core POS/ERP system, the various item status information is then sent automatically to the middleware of the Assortment API.

# How do I integrate the Assortment API in Staging?

1. Go to the Swagger UI documentation to copy the header URL of the PUT request, either for Bulk or Individual Item updates
2. Configure the parameters of the PUT request, specifying vendor ID, SKU, price &/or active status of each item, or of the single item in the case of individual item amendments

# How do I access the Production URL for the Assortment API?

After testing in staging, you are free to access the Assortment API URL for your region, which you can see below:

# APAC

• Please see the APAC Production URL linked here

# MENA

• Please see the MENA Production URL linked here

# EU

• Please see the EU Production URL linked here

# LATAM

• Please see the LATAM Production URL linked here

# Benefits of the Assortment API Update

There are two primary benefits for our partner vendors of integrating the newer version of the API over the older version; they can be understood in the following terms:

• Speed of updating item status in Catalogue - vendors are now able to update item availability in bulk, using a Swagger UI endpoint, rather than sending individual calls to update items one-by-one (individual items can still be amended as before using the individual item Swagger UI endpoint, located here
• Less complicated, more reactive API logic - Due to the fact that one single token can be used for both the POS API & Assortment API, rather than multiple tokens for each API

# How to Make Use of the Assortment API's 'Bulk Update' Feature

Please see the below process flow for integration of the bulk/Individual item PUT request, and a step by step description:

1. Click on the Shops Integration Tab of the Vendor Portal homepage
2. Click ‘Token Management’ and ‘Generate New Token’ - this takes place at the chain level, meaning there is no requirement to generate a new token for new vendors assigned to a chain, as the same token will automatically function with all vendors in that chain.
3. Copy the token credentials somewhere safe
4. Go to the Swagger UI documentation to copy the header URL of the PUT request, either for Bulk or Individual Item updates
5. Configure the parameters of the PUT request, specifying vendor ID, SKU, price &/or active status of each item, or of the single item in the case of individual item amendments
6. Execute the PUT call; the callback payload will consist of either a 200 or 400 response, (see below for an example callback response), with a 200 code being a successful response; 400 (i.e. 400, ‘bad request’, 403, ‘forbidden’) responses indicate a failure.

# Testing Bulk or Individual Item edit functionality

Vendors are encouraged to test the new API functionality; the Swagger UI for the Assortment API has a ‘try it out’ feature which generates test SKU information within the ‘request body’ payload, as you can see below:

# Known Constraints

• Use of barcodes is supported in the item update functionality for Catalogue offered, but not encouraged - please only use item SKUs as item identifiers.
• If you are amending individual products, please use only the single product endpoint (see here) rather than the bulk product endpoint in order to avoid lag errors. If as a vendor, you are using event-based systems to bulk update orders, use the bulk update endpoint.

# Supported Regions & Platforms

The Assortment API is currently accessible via the platforms and countries listed below. If you don't find the platform you are looking for, please reach out to your local Delivery Hero representative.

# Latin America

PedidosYa (Guatamala, Chile, Honduras, Argentina, Peru, Paraguay, El Salvador, Nicaragua, Bolivia, Dominican Republic, Venezuela, Panama, Ecuador, Uruguay, Costa Rica)

# Asia/Pacific

Foodpanda (Bangladesh, Cambodia, Hong Kong, Japan, Laos, Malaysia, Myanmar, Pakistan, Philippines, Singapore, Taiwan, Thailand)

# Europe

Damejidlo (Czech Republic) Foodora (Finland, Sweden, Norway) Mjam (Austria) Foodpanda (Hungary, Romania)

# Middle East/ North Africa

Hungerstation (Saudi Arabia) Talabat (Bahrain, Egypt, Jordan,Kuwait, Oman, Qatar, United Arab Emirates)

# Delivery Hero IP Addresses to Whitelist

If your application is behind a secure firewall, and you're having trouble making requests to the Delivery Hero Q-Commerce API, you might need to whitelist our IPs in order to successfully make those requests.

Please see a list of our most recently updated IP addresses here. These IP addresses are subjected to change and will be regularly updated. When we change the IP addresses, the API users will be informed via email in advance and also be given a 2 week timeline to update the whitelist.

We highly recommend whitelisting the entire list of Delivery Hero IPs for seamless access.

# Handling API Errors

Nothing is perfect - as a partner you must implement a client-side retry-mechanism to handle unforeseen API errors. Please use an exponential backoff during retries and at the very least:

• retry 10 times with a maximum backoff of 32 seconds. e.g.:
• Retry #1: time: 00:01, delay: 1s
• Retry #2: time: 00:02 delay: 2s
• Retry #3: time: 00:04 delay: 2s
• Retry #4: time: 00:08, delay: 4s
• Retry #5: time: 00:16, delay: 8s
• Retry #6: time: 00:32, delay: 16s
• Retry #7: time: 01:04, delay: 32s <– max delay reached
• Retry #8: time: 01:36, delay: 32s
• Retry #9: time: 02:08, delay: 32s
• Retry #10: time: 02:40, delay: 32s

# Terms and Conditions

After Integrating with us, partners should inform Delivery Hero about any instances of upcoming system maintenance. It’s possible to do this by sending an email to [email protected] at least 24 hours in advance; this is compulsory for both Direct and Indirect flows.

The integration may be disabled by Delivery Hero whenever orders are not reaching the webhook and the relevant contact is not responding. The integration will be reactivated once the issue is fixed by the webhook developer.

If you have any questions regarding the API documentation, or if you face any issues with the API, please reach out to [email protected].