FAQ#

Click below to jump to the topics:

• Access to Integrations & Credentials

  • How do I generate credentials to use Partner API/Orders?

  • How many tokens can I generate?

  • If an existing chain wants to onboard new outlets, how can we integrate them?

  • Can I generate API tokens myself?

  • How do I find my Foodpanda Vendor/store ID?

  • What If I already have internal Vendor IDs and I don’t want to use Delivery Hero IDs for Store Identifiers?

• Order payload fields and schema

  • How do I get the best out of the Pelican picking integration?

  • What are the limitations of the Partner API/Orders (Pelican)?

  • What are the fields in the order payload and how can I use them?

  • Should I validate the client details provided in the order payload?

  • What is the difference between "order_id", "external_order_id" and "order_code" and which one shall the Partner use for reconciliation purposes?

  • What is the difference between "sub_total" and "order_total" ? Which is the final order total Partner should consider?

  • What if the item has weight-based pricing?

  • How to identify the items with finite quantity and items with KG / weighted quantities in order payload?

  • How can I tell if an order was actually picked up after being cancelled? I need to know whether it should be treated as a final sale.

  • How do I validate order cancellation? Should I use the same webhook or a different endpoint?

  • What happens if my webhook service is not reachable does pelican picking integration support retries to our webhook?

• Testing Integrations

  • What are different way for testing the integrations?

  • How can I use a testing environment for order management integrations?

  • How End to End testing performed?

• Access to Partner Portal

  • What is Partner Portal and how do I get access?

  • How do I access the Shops Integrations Plugin?

  • Where can I go for further support?

Integrations Access & Credentials#

How do I generate credentials to use Partner API/Orders?#

Please see the token management section here

How many tokens can I generate?#

You can generate up to 11 API tokens in the Partner Portal. These are bearer tokens which don’t have an expiry date and are applicable at the chain level, meaning a single API key can manage all outlets in a chain

If an existing chain wants to onboard new outlets or scale, what is the process to integration?#

To scale the integration at chain level, following things are to be considered from your side

• Verify access to your new stores in Partner Portal and review webhook configurations

• (Optional) If you have any internal mapping for your store, it is possible for you to configure directly from the Shop Integrations plug-in. Use the new configured store-id or vendor id in your API requests.

Can I generate API tokens myself?#

Yes, you can generate tokens on your own. You are required to have access to the Shop Integrations plug-in in Partner Portal.

How do I find my Foodpanda Vendor/store ID?#

You can get it directly Partner Portal>Shop Integrations>Settings>Vendor Identifier section or check with your Account manager.

What If I already have internal storeID and I don’t want to use Platform storeID?#

You can configure your internal storeID in Partner Portal>Shop Integrations>Settings>Vendor Identifier section. Please note to use the newly mapped storeID in your API requests.

Order payload fields and schema#

Which order statuses are sent to the webhook for Pelican Picking Integrations ?#

For Pelican Picking Integrations, the following order statuses are sent to the webhook:

• READY_FOR_PICKUP: This status indicates that order picking and packing has been completed and the order is ready for pickup by a delivery rider.

• CANCELLED: An order is marked as CANCELLED if it is canceled by the customer, delivery rider, or by you.

How do I get the best out of the Pelican picking integration using my webhook?#

• READY_FOR_PICKUP and CANCELLED order statuses to be consumed by your webhook

• Configurations: To secure your webhook configurations in Partner Portal, secrets can be utilised for the purpose it can be any string, we also accommodate basic authentication mechanism.

  • For example, if the webhook service uses partner as the username and randompassword as the password, then the value in Base64 encoding of partner: *randompassword, is cmFuZG9tcGFzc3dvcmQ=

  • Then the Authorization header field will appear as: Basic cmFuZG9tcGFzc3dvcmQ= (this needs to be added to the secret field in the Partner Portal)

What are the limitations of the Partner API/Orders (Pelican)?#

• New orders created by customers on the Platform App are not forwarded to the webhook directly, only orders fulfilled and checkout by pickers are transmitted to the webhook with READY_FOR_PICKUP status

• You can expect to receive only READY_FOR_PICKUP and CANCELLED as order status

What are the fields in the order payload and how can I use them?#

sample order payload

{
order_id: "807c225f-ac6d-445d-a074-ea960c892ca7",// used in GET endpoint
external_order_id: "qktu-ul1p", 		// visible on pelican 
order_code: "546",
client: { 					//contains store information 
id: "22438",
chain_id: "0aa64dc1-280b-4d1c-972a-28a15a14382a",
name: "qktu - chainname",
country_code: "tw",
store_id: "qktu",
external_partner_config_id: "462"  //internal mapping for your stores
},
customer: {					// customer information is masked
_id: "twxqg33o",
national_id: "",
tax_id: "",
first_name: "于**",
last_name: "**",
phone_number: "+88693****651",
delivery_address: {
country: "",
city: "",
street: "",
number: "",
latitude: 0,
longitude: 0,
company: "",
block: "",
building: "",
apartment: "",
entrance: "",
intercom: "",
floor: "",
suburb: "",
zipcode: "",
instructions: "",
formattedAddress: ""
}
},
comment: "",
items: [			// item level information
{
_id: "796ee50e-2cb5-41ec-8a06-4208fe15dcb3",
sku: "222316",
barcode: [
4710036604597
],
name: "#222316 | 靠得住冰爽棉28cm | 15 片 | #4710036604597",
pricing: {            // contains information of fulfilled items
pricing_type: "UNIT",
unit_price: 85,
vat_percent: 0,
total_price: 170,
quantity: 2,
min_quantity: 0,
max_quantity: 2
},
original_pricing: { // contain information of item at order placement
pricing_type: "UNIT", // fo UNIT quatity hold information of any changes
unit_price: 85,
vat_percent: 0,
total_price: 170,
quantity: 2,
min_quantity: 0,
max_quantity: 2
},
container_deposit: 0,
discount: 0,
instructions: "",
status: "NOT_PROCESSED"          // item level status
},
{
_id: "a5e42c90-351f-4c64-be7a-7dace4b96033",
sku: "146344",
barcode: [
4710098163773
],
name: "#146344 | 77脆可穀麥巧克力 | 36 g | #4710098163773",
pricing: {
pricing_type: "KG",–> // when pricing type is KG, weight field is availble in the pricing object, qunatity defualts to 1
unit_price: 7,
vat_percent: 0,
total_price: 14,
weight: 2.0,
quantity: 1,
min_quantity: 0,
max_quantity: 1
},
original_pricing: {
pricing_type: "KG",
unit_price: 7,
vat_percent: 0,
total_price: 14,
weight: 2.0,
quantity: 1,
min_quantity: 0,
max_quantity: 2
},
container_deposit: 0,
discount: 0,
instructions: "",
status: "NOT_PROCESSED" // item level status
}
],
order_type: "DELIVERY",
transport_type: "LOGISTICS_DELIVERY", // type delivery flow 
payment: {
sub_total: 184,  // sum of total items 
order_total: 177, // amount paid by the customer contains fees,discounts 
delivery_fee: 0,
service_fee: 2.39,
difference_to_minimum: 0,
discounts: [
{
name: "vh8o1buy",
value: -9.2
}
],
discount: -9.2,
container_charge: 0,
total_taxes: 8.32,
additional_fees: {
PriorityDeliveryFee: 0
},
type: "PAID"
},
cancellation: {
reason: "",
cancelled_by: "",
post_pickup: true			// only visible for cancelled orders post order fulfilment
},
status: "CANCELLED", // order status 
sys: {
created_at: "2023-09-01T07:41:17.733Z",
created_by: "Order Fulfilment",
updated_at: "2023-09-01T07:45:45.863Z",
updated_by: "Order Fulfilment",
webhook_status: ""
},
promised_for: "2023-09-01T08:06:11Z",
isPreorder: false
}

Should I validate the client details provided in the order payload?#

Depending on how you intend to route orders to a specific store, you can use the following field information to accurately identify and validate the store.
store_id: xxxx, – Identifier of the store on Platform systems external_partner_config_id: xxxx– if the Partner store/outlet has any internal identifier it must be mapped to this field.
Depending on how you want to direct the orders to specific store you can use below field information to validate the store

What is the difference between "order_id", "external_order_id" and "order_code" and which one shall the Partner use for reconciliation purposes?#

order_id: 7384a9e4-c4e1-4820-873e-2cc637acec78– Unique identifier for order used in our backend services. If you want to query a single order using the GET endpoint you should use order_id

external_order_id: mxuv-2439-9sa5– platform order id, shown on Pelican device, external_order_id could be used in your reconciliation process

order_code: its an incremental value(resets after 9999) on orders used by riders for picking orders from store

What is the difference between "sub_total" and "order_total" ? Which is the final order total Partner should consider?#

• sub_total:Refers to the total value of the order items, including item-level taxes but excluding any order-level discounts (such as coupon codes or discounts applied at the overall order level). You should use sub_total when you want to validate the cumulative value of all items in the order

• order_total: This is the final amount paid by the customer for the order. It includes all item prices, delivery fees, and discounts(such as coupon codes or discounts applied at the overall order level)

What if the item has weight-based pricing?#

When an item has weight-based pricing, pricing_type will be "KG" at item level in the order payload. For such items, the quantity field will always have a default value of 1, and a weight field will be present with a decimal value to indicate the item's weight.

How do I access the shop Integrations Plugin?#

• All current Shops partners of any size can access the Shops Integrations plugin in Partner Portal, you will be given access by your account manager or during registration with us.

• It is advised to limit the access to Shops plugins in Partner Portal to only those who need to perform a function for your business - this is because Partner Portal can contain sensitive information i.e. webhook configurations

• Please reach out to your account manager if you do not know how to gain access to Partner Portal

How to identify the items with finite quantity and items with KG / weighted quantities in order payload?#

• Each item in the order has pricing and original_pricing objects, & both objects have quantity field

• pricing object contain picked quantity (adjusted by the picker) refer to the field Items.pricing.quantity

• original_pricing object contains ordered quantity by the customer, refer to the field Items.original_pricing.quantity

• For items with finite quantity, pricing_type will be UNIT, sharing both pricing and original_pricing objects. The pricing object contains the picked quantity by the picker. Items.pricing.quantity

{
  "pricing": {
    "pricing_type": "UNIT",
    "unit_price": 0.69,
    "vat_percent": 0,
    "total_price": 0.69,
    "quantity": 1,
    "min_quantity": 0,
    "max_quantity": 2
  },
  "original_pricing": {
    "pricing_type": "UNIT",
    "unit_price": 0.69,
    "vat_percent": 0,
    "total_price": 1.38,
    "quantity": 2,
    "min_quantity": 0,
    "max_quantity": 2
  },
}

For items with weight, pricing_type will be KG, sharing both pricing and original_pricing objects. The pricing object contains the actual picked/fulfilled weight(decimal value) by the picker i.e Items.pricing.weight. We also share quantity for weighted items however this will be default value 1 (can be ignored if you find it not useful)

{
  "pricing": {
    "pricing_type": "KG",
    "unit_price": 0.69,
    "vat_percent": 0,
    "total_price": 0.69,
    "quantity": 1,
    "weight": 1.0,
    "min_quantity": 0,
    "max_quantity": 2
  },
  "original_pricing": {
    "pricing_type": "KG",
    "unit_price": 0.69,
    "vat_percent": 0,
    "total_price": 0.69,
    "quantity": 1,
    "weight": 1.0,
    "min_quantity": 0,
    "max_quantity": 2
  }
}

How can I tell if an order was actually picked up after being cancelled? I need to know whether it should be treated as a final sale.#

Request to Account Manager to enable the post_pick_up field. This is an addition to the existing cancellation object specific to the usecase for order cancellation after rider pickup. For all other cancelations scenarios– NO CHANGE, post_pick_up field is not visible.

Scenario: order cancelation after rider pickup:
…
"cancellation": {
    "reason": "TECHNICAL_PROBLEM",
    "cancelled_by": "CUSTOMER",
    "post_picked_up": true
  },
..


For other cancelation scenarios:
…
"cancellation": {
    "reason": "TECHNICAL_PROBLEM",
    "cancelled_by": "CUSTOMER",
  },
..

How do I validate order cancellation? Should I use the same webhook or a different endpoint?#

Cancellation can occur from customer, vendor and logistics. When the cancellation event occurs during the life cycle of order. CANCELLED status will be sent to the same webhook configured in the Partner Portal

What happens if my webhook service is not reachable does pelican picking integration support retries to our webhook?#

We support retry mechanisms in cases where your webhook service does not respond within 10 seconds. The system will attempt up to 5 retries, each spaced 10 seconds apart. It is important that you implement appropriate handling on your end to manage potential duplicate order payloads, so that repeated webhook deliveries don't result in processing the same order multiple times

Testing Integrations#

What are different way for testing the integrations?#

1. Sandbox testing: During development stage Partner can utilise this environment to test directly from Partner Portal. To be used only for testing the communication between Partner API and your webhook

2. E2E testing: After Partner completes the development they can perform live End to End integration testing coordinating with Platform teams. We have list of test cases which can be covered

How can I use a testing environment for order management integrations?#

• We have a sandbox environment which will be enabled automatically when a webhook is configured in the Partner Portal(Prerequisite: store POS integrations to be enabled & webhook should be configured in Partner Portal ).

• Orders created from the sandbox environment can also be retrived via GET endpoint.

• You can support the AM by identifying a test store or onboarding a new test store that can be utilised for testing purposes before going Live.

• The Sandbox environment will push simulated statues i.e. expect to receive RECEIVED, READY_FOR_PICKUP, CANCELLED and DISPATCHED statuses.

• However, in E2E testing for Pelican Picking scope you will receive only either statuses READY_FOR_PICKUP & CANCELLED

How End to End live testing performed?#

In order to perform E2E live integration testing, you’ll need to do the following: 

1. Identify a test store and enable the integration configurations 

2. Coordinate with KAIT, AM & Partner teams, to place an new order on platform and fulfill it from Pelican picking device  

3. Follow the Integration Test cases document to test the integration usecases

Access to Partner Portal#

What is Partner Portal and how do I get access?#

Partner Portal is a back office tool by which you can manage your stores. When you are onboarded to our platform our Account Management team will be providing you the access. Depending on your use privileges you can also manage the webhook and token configurations.

Following activities can be managed from Partner portal:

• Integration configurations

  • Store operations

  • Create promotions

  • Update product availability & prices

  • Review orders across your stores

  • Identify issues and perform initial troubleshooting

How do I access the Shops Integrations Plugin?#

1. All current Shops Partners of any size can access the Shops Integrations plugin in Partner Portal, you will be given access by your Account Manager or during registration with us.

2. It is advised to limit the access to Shops plugins in Partner Portal to only those who need to perform a function for your business - this is because Partner Portal can contain sensitive information i.e webhook configurations 

3. Please reach out to your account manager if you do not know how to gain access to Partner Portal

Where can I go for further support?#

If you have any questions regarding the integration or if you are facing errors, please contact your Account Manager or drop an email to Key Account integration Team: keyaccountsQC@deliveryhero.com