HomeGuidesAPI Reference
Guides

Build a POS Integration

Start here if you want to learn how to integrate your POS system with Flipdish

Suggest Edits

Introduction

This guide is intended for POS companies who wish to integrate their system with Flipdish.

We will cover

Creating and mapping the menu

  • Mapping the Flipdish menu to your products in your POS
  • Updating the Flipdish menu when changes are made in the POS
  • Getting notified of changes on the Flipdish menu so that you can update the products on the POS

Understanding the Order data

  • Vouchers (aka discounts or coupons)
  • Customers
  • Store
  • Other order data
  • Order items

Receiving and accepting orders

  • Getting notified of new orders
  • Marking orders as accepted (or rejected 😒 )

This guide presumes that you have

Mapping

In some cases a Flipdish menu will already be created and you will need to map these existing items to the products in your POS.

In other cases you will create the items in the Flipdish menu based on the products in your POS.

This guide presumes that in all cases there will already be products created in your POS, but there is nothing preventing you from generating the products in your POS based on the items in the Flipdish menu.

Mapping existing POS products to existing Flipdish menu entities

📘

Metadata

In an effort to make life easy for people to create POS integrations, we allow you to store metadata alongside entities in the Flipdish menu. This means you can, if you wish, create a fully functional integration without creating any new datastore on your side.

The intended use case is that you will save your associated product IDs/references as metadata for each MenuSectionItem or MenuOptionSetItem. This metadata will then be returned to you in each order notification webhook, and you can use it to create the correct order in the POS.

Alternatively you can use the PublicId property on the menu entities and store these in your own database.

CAUTION: Do not store sensitive information as Metadata. Metadata is not encrypted at rest and can be exposed to users who have access to the menu.

Step 1: Retrieve the menu

API reference: https://developers.flipdish.com/reference#getmenubyid
Retrieve the full menu and view the items.

Step 2: Store references to your products as metadata at Flipdish.
Example API reference: https://developers.flipdish.com/reference#menusectionitems
Then store your product IDs / references as metadata for each entity in the menu.

Step 3: Retrieve the menu entities and ensure that you are receiving your metadata back correctly for all menu entities.
API Reference: https://developers.flipdish.com/v1.0/reference#getmenuitemmetadata-1

Updating Flipdish menu items when something changes in the POS

Learn how to change menu entities.

👍

Example use case

You want to change the price of an item in the POS and have it automatically update on Flipdish.

Use the relevant update API endpoints to update an existing menu entity. For example, to update a MenuSectionItem, use the endpoint described at https://developers.flipdish.com/reference#updatemenusectionitem

Creating new Flipdish menu items from existing POS products

👍

Example use case

A user adds a new item to your POS and you want it to automatically become available on their Flipdish menu.

Use the relevant update API endpoints to create a new menu entity. For example, to create a MenuSectionItem, use the endpoint described at https://developers.flipdish.com/reference#createmenusectionitem

Getting notified when the Flipdish menu changes

👍

Example use case

  1. You want to allow users change the price of items on Flipdish and to automatically chagne the price in your POS
  2. You want to allow users add new items to their online menu via the Flipdish portal and to automatically add these items to your POS.
  3. You want to get notfied so that you can manually make a change to the POS if something changes on the online menu.

We recommend that you subscribe to a webhook to get notified of changes to the menu.
You will want to subscribe to the menu.updated webhook. You can learn how to subscribe to webhooks at https://developers.flipdish.com/v1.0/docs/using-webhooks

Can't use webhooks?
If you cannot receive webhooks then you can rely on polling our API.

You can poll the endpoint described at
https://developers.flipdish.com/reference#getmenubyid
and check the menu version number. If it increases then a change has been made and you can then retrieve the full menu.

Do not retrieve the full menu frequently to check for changes as this endpoint this is an expensive operation and therefore highly rate limited.

We recommend that you poll the menu version number once per minute or less frequently.

Voucher

Every order will contain a Voucher property, which will be NULL if no voucher is applied to the order. The Voucher looks like this:

"Voucher": {
    "Name": "-€5 (abc123)",
    "Description": "abc123",
    "Code": "abc123",
    "Amount": 0,
    "Type": "PercentageDiscount",
    "SubType": "None"
  }

We recommend that you pay attention only to the Amount property and deduct this amount from the order.

You can add metadata to vouchers that you create. Doing this is outside the scope of this document. You cannot add metadata to system generated vouchers (such as those created the lotalty or retention systems).

Customer

Every order will contain a Customer property, which looks like this:

"Customer": {
    "Id": 1234,
    "Name": "John Doe",
    "EmailAddress": "[email protected]",
    "PhoneNumberLocalFormat": "0818204488",
    "PhoneNumber": "+353818204488"
  }

It is not currently possible to add metadata to Customers.

Store

Every order will contain a Store property, which looks like this.

"Store": {
    "Id": 123,
    "Name": "Restaurant",
    "MenuId": 123,
    "Metadata": {
      "foo": "bar"
    },
    "Currency": "EUR"
  }

If you are receiving orders for multiple stores then you will probably want to check the Store.Id value and route the order accordingly.

Order Items

The OrderItems array contains information on what the customer ordered.

"OrderItems": [
    {
      "OrderItemOptions": [
        {
          "Metadata": {
            "foo": "bar"
          },
          "MenuItemOptionId": 654645,
          "IsMasterOptionSetItem": false,
          "Name": "Option 1",
          "Price": 0,
          "MenuItemOptionDisplayOrder": 1,
          "MenuItemOptionSetDisplayOrder": 1
        }
      ],
      "Metadata": {
        "foo": "bar"
      },
      "MenuSectionName": "Section 1",
      "MenuSectionDisplayOrder": 1,
      "Name": "Item 1",
      "Description": "First order item",
      "Price": 0,
      "PriceIncludingOptionSetItems": 0,
      "MenuItemId": 5545,
      "MenuItemDisplayOrder": 1,
      "IsAvailable": true
    }
  ],

Each OrderItem element can have an OrderItemOptions array.

You will want to pay attention to the metadata on the OrderItems and the OrderItemOptions as well as the price.

Other order properties

DeliveryLocation Delivery orders will have a value for this property. It will contain the customer address and coordinates.

"DeliveryLocation": {
    "Coordinates": {
      "Latitude": 0,
      "Longitude": 0
    },
    "Building": "38",
    "Street": "Pearse Street",
    "Town": "Dublin",
    "PostCode": "xx xxx",
    "DeliveryInstructions": "building is on the right",
    "PrettyAddressString": "38 Parse Street, Dublin, xx xxx"
  }

OrderId: this is the unique identifier for the order. We recommend printing this on the receipt given to customers and to display it on screen to staff. Flipdish staff will need this ID to locate any order.

PaymentAccountType: this can have multiple values, including Cash, Card, Ideal etc. All results other than Cash will mean that the order is pre-paid online.

OrderState: If this is in the state ReadyToProcess then the order is ready to be accepted or rejected. Orders must be accepted before 13 minutes* past the OrderCreatedTime or they will be automatically rejected.
*If a store is closed at the time the order was created, the timer to auto-reject the order won't start until the store opens.

RequestedForTime: this is the time that the customer has requested the order for. If the customer requested ASAP then this will be the current time.

ChefNote: this contains any notes that the customer entered for the person preparing the order.

IsPreOrder: this is a boolean and will be true if the customer has ordered for a time in the future and false if the customer expects immediate preparation of their order.

You may find more useful information about the various data returned by the API in the definitions section: https://developers.flipdish.com/v1.0/docs/definitions

Receiving orders

We recommend that you subscribe to the order.created webhook to get notified of new orders.

You can receive full information about an order using the GET Order API endpoint described at
https://developers.flipdish.com/reference#getorderbyid

If you cannot rely on webhooks to receive order notifications, you can poll our API for orders using the API endpoint described at
https://developers.flipdish.com/v1.0/reference#getorders

You should set the state filter to ReadyToProcess

curl --request GET \
  --url 'https://api.flipdish.co/api/v1.0/orders?state=ReadyToProcess'

We recommend that you poll for new orders at most every 20 seconds and at least every 60 seconds.

Accepting and rejecting orders

When a customer places an order, it will have an OrderState ReadyToProcess. Orders must be accepted within 13 minutes* of the OrderCreatedTime or they will be automatically rejected.
*Within the opening hours. If a store opens later they will have till 13 minutes past the opening time for the store to accept the order, after which it will be auto-rejected.

Orders can be accepted using the API endpoint described at https://developers.flipdish.com/reference#acceptorder

When an order is accepted the customer will receive a notification by SMS to let them know.

If the order cannot be accepted for some reason, then it should be promptly rejected using the API endpoint described at
https://developers.flipdish.com/reference#rejectorder

👍

Tips

We recommend also reading the integration tips.

Updated over 2 years ago

What’s Next

We recommend perusing our API documentation to learn about other useful operations that can be performed via the API.