Order Pickup Integration

This documentation outlines two options for integrating Order Pickup functionality into e-commerce platforms, enabling a seamless transition from online ordering to curbside pickup. Depending on the level of customization and control available on the e-commerce platform, vendors can choose between a simple link method and a more complex, code-driven link generation approach.

Option 1: Simple Link Integration

Simple link integration is ideal for scenarios where adding code-level logic is not feasible, such as platforms like Shopify that offer limited customization capabilities.

Steps for Integration:

Queue ID Mapping: Ensure there is a mapping stored on the e-commerce side between each store and our provided ‘queue ID’. This ID is essential for generating the correct pickup links.
Creating the Schedule Pickup Link:
- URL Schema: https://queue.{dataResidency}.ombori.com/{organization}/queues/{queueId}/book/curbside-pickup?orderId={orderId}&pickupDuration={numberOfDays}&note={note}
- Query String Parameters:
  - orderId: Required. A string containing the order identifier.
    - Can be used as a unique identifier to retrieve an existing ticket using get position endpoint, helping avoid double bookings.
  - pickupDuration: Specifies how many days in the future a pickup can be booked. Used to calculate the maximum pickup date.
  - note: Optional. Additional information for operational use.

Option 2: Complex Link Integration

Complex link integration provides more control and is suitable for vendors who can incorporate code-level logic into their systems, such as generating links directly from their backend systems.

Steps for Integration:

Queue ID Mapping: Similar to Option 1, ensure there is a correct mapping between each store and the provided ‘queue ID’.
Constructing the Schedule Pickup Link:
- Base URL: https://queue.{dataResidency}.ombori.com/{organization}/queues/{queueId}/book/curbside-pickup?options={options}
- Query String Parameters:
  - options: A Base64-encoded JSON string containing:
    - orderId: Required. The order identifier.
    - minDate: Required. The earliest pickup date as a UTC timestamp.
    - maxDate: Required. The latest pickup date as a UTC timestamp.
    - phoneNumber: Optional. The customer’s phone number in E.164 format.
    - note: Required. Extra information (up to 500 characters) such as an order summary.

Example of Complex Link Generation:

Here's how you might generate a complex link using JavaScript:

// Creating curbside link link
const data = {
  earliestPickup: "2021-07-14T08:40:24.806Z", // earliest pickup date, as ISO string for example purposes
  latestPickup: "2022-07-14T08:40:24.806Z", // latest pickup date, as ISO string for example purposes
  orderId: `XYZ${Math.floor(Math.random() * 100)}`, // internal order identifier
  phoneNumber: "+46000000", // customer phone number
  note: "hello" // optional note to be presented for the staff
};
const curbsideServiceUrlBase = "https://queue.eu.ombori.com"; // base url for link generation, found in Console or provided by Ombori team, depends on data residency
const queueId = "7a37b7e8-4689-4982-8216-262c5e1f1989"; // queue id, found in console
const organization = "aneards"; // organization id, found in console

const { earliestPickup, latestPickup, orderId, phoneNumber, note } = data;

const minDate = Math.floor(new Date(earliestPickup).getTime() / 1000); // utc timestamp in seconds
const maxDate = Math.floor(new Date(latestPickup).getTime() / 1000); // utc timestamp in seconds

const linkOptions = { minDate, maxDate, orderId, phoneNumber, note };
const urlBase = `${curbsideServiceUrlBase}/${organization}/queues/${queueId}/book/curbside-pickup`;
const linkUrl = `${urlBase}?options=${btoa(JSON.stringify(linkOptions))}`;

const a = document.createElement("a");
const link = document.createTextNode(`Book your pickup: ${linkUrl}`);
a.appendChild(link);
a.href = linkUrl;
document.body.appendChild(a);

console.log(linkUrl);