FAQ#

Click below to jump to the topics:

• Access to Integrations & Credentials

  • Can I generate API tokens myself?

  • How many tokens can I generate?

  • Which account details required to establish API communication?

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

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

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

• Order payload fields and schema

  • Which order statuses are sent to the webhook for Partner Picking Integrations ?

  • How do I get the best out of the Partner picking integration using my webhook?

  • What are the limitations of the Partner picking integrations?

  • 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 Partner Picking Integration supports retries to our webhook?

• Testing Integrations

  • What are different way for testing the integrations?

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

  • How End to End testing is 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#

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 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

Which account details required to establish API communication?#

• Ensure that you have access to Partner Portal with Integration plugin, check with Account Manager to get access to required users

• Post which API token can be generated and can be used to communicate with our API (Prerequisite: POS integrations to be enabled in Global Catalog & webhook should be configured in Partner Portal )

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

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

You can get it directly Partner Portal>Shop Integrations>Settings>Vendor Identifier section or please 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 and that also impacts your catalog integration.

Order payload fields and schema#

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

For Partner Picking Integrations, the webhook receives notifications for the following order statuses:

• RECEIVED: This is the initial status of an order, indicating that order processing by the partner has not yet started. It is sent by Delivery Hero automation to the vendor's webhook when an order is received.

• READY_FOR_PICKUP: This status signifies that order picking and packing has been completed by the partner, and the order is ready for pickup by a delivery rider. This status is set by the vendor using a PUT endpoint.

• DISPATCHED: The order has been dispatched. For Platform Delivery, this status is sent by Delivery Hero automation to partner webhooks when riders pick up the order from the store.

• CANCELLED: An order is marked as CANCELLED if the order is canceled by the customer, delivery rider, or you. No webhook will be sent on cancellations originating from the Partner Picking solution.

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

• RECEIVED READY_FOR_PICKUP DISPATCHED and CANCELLED order statuses are 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)\

    Note

    Securing your webhook using secret is mandatory

• Leveraging PUT endpoint, ensure that you have covered below use cases with your own picking solution

  1. Complete order fulfilment

  2. Partial order fulfilment

  3. Item replacements

  4. Item additions

  5. Cart updates

  6. Fulfil order containing weighted items i.e pricing_type: "KG"

  7. Modify order quantity on items with pricing_type: "UNIT" (price adjustments are possible to a lower value on either of the fields unit_pice or total_price but not both)

  8. Order cancellation including appropriate cancellation reasons

What are the limitations of the Partner Picking Integration ?#

1. Price modifications are not allowed on weighted items i.e pricing_type: "KG"

2. Platform external_order_id doesn’t work to retrieve the order, while using the get endpoint to retrive single order, you should use the order_id (type uuid) from the order payload.

3. Kindly ensure that your API requests(GET or PUT) to our service do not exceed 60 requests per minute.

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

Customer Data:

In the comments field, the customer’s email is sent in a tokenized format so that you can send the invoice digitally. For security reasons, the email token is valid for 12 hours and only one email can be sent to the shared address. The email you send will be redirected to the customer’s real email.

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: "Si algún producto no está disponible: Elegir reemplazos | Email del Cliente: [email protected]",
items: [			// item level information
{
_id: "796ee50e-2cb5-41ec-8a06-4208fe15dcb3",
sku: "222316",
barcode: [
4710036604597
],
name: "Cuatro Quesos La Serenísima Finlandia Light en Hebras 130 g",
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: "Manzana Red Delicious",
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 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– 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 partner 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.

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 about the integration, you can contact the Integrations Support team via email at [email protected] or by scheduling a meeting through this link.

If you have an issue, contact the Integrations Support team at [email protected] **or report the issue as this link **and provide:

• A clear description of the issue.

• Error details (logs, screenshots, API responses).

• The scale and impact on your business.