Integrate Orders

To integrate you POS ordering you must implement one endpoint. Flyt will use the type field in the request body to differentiate order type.

Flyt will make a POST request with a request body in one of the below formats, expecting to create an order. Flyt will expect a response with the internal identifier for the order on your system (e.g. OrderId).

Order types

Data types passed in the request

  • created_at / collect_at: Timestamps of when the order was created and is expected to be collected (in Unix time)
  • item: recursive structure - modifiers are also in the item structure as part of the children array
  • plu: unique POS identifier
  • price: an integer, price in cents (no decimal places)
  • channel: the channel/website where the customer made the order
  • third_party_order_reference: id of the third party, can be string or number
  • payment_method: method customer paid for/will be paying for the order, allows values CASH or CARD
  • tender_type: the identifier used by your POS to differentiate orders from Flyt/delivery provider
  • payment: object breaking down payment information (depending on service provider this information may not be available)

    • items_in_cart: the total with tax of all the items in the cart
    • final: the total with tax of all the items plus negative/positive adjustments
    • adjustments: negative and positive adjustments to the order total (e.g. delivery fee, combo discounts)
  • delivery: delivery information for the customer receiving the order (depending on service provider and order type this information may not be available)

Delivery By Delivery Partner Orders

An order where a delivery partner (Just Eat, SkipTheDishes, etc.) will pick up and deliver the order. To implement this order type, your endpoint must support POST requests with request bodies in the following format.

Expand
Body
{
  "type": "delivery-by-delivery-partner",
  "posLocationId": "BBBBBBBBB",
  "driver": {
    "first_name": "John",
    "last_name": "Driver",
    "phone_number": "+447910575785"
  },
  "items": [
    {
      "name": "Fish and Chips",
      "description": "The tastiest Fish in the whole world",
      "plu": "11212121",
      "price": 750,
      "children": [
        {
          "name": "Extra Sauce",
          "description": "The greatest sauce in the world",
          "plu": "11211",
          "price": 150,
          "children": [
            // etc.
          ]
        }
      ]
    }
  ],
  "created_at": "1553495441",
  "channel": {
    "name": "SkipTheDishes",
    "id": 123
  },
  "collect_at": "1553495441",
  "collection_notes": "Notes about the collection",
  "kitchen_notes": "Notes for the kitchen",
  "third_party_order_reference": "SKIP-12345678",
  "total": 900,
  "payment_method": "CARD",
  "tender_type": "SKIP",
  "payment": {
    "items_in_cart": {
      "inc_tax": 1017,
      "tax": 117
    },
    "final": {
      "inc_tax": 1117,
      "tax": 117
    },
    "adjustments": [
      {
        "name": "delivery fee",
        "price": {
          "inc_tax": 100,
          "tax": 0
        }
      }
    ]
  },
  "delivery": {
    "first_name": "Hannah",
    "last_name": "Customer",
    "phone_number": "28 05 2003",
    "line_one": "13/16, Elm St",
    "line_two": "Flyt",
    "city": "London",
    "postcode": "WC1X 0BL",
    "email": "integrations@flyt.io",
    "coordinates": {
      "latitude": 51.509865,
      "longitude": -0.118092,
      "latitude_as_string": "51.509865",
      "longitude_as_string": "-0.118092"
    }
  }
}


response 200 OK
{
    "OrderId": 1234
}

Delivery By Merchant Orders

An order where the restaurant will receive the order from a delivery partner, but will deliver it themselves. To implement this order type, your endpoint must support POST requests with request bodies in the following format.

Expand
Body
{
  "type": "delivery-by-merchant",
  "posLocationId": "BBBBBBBBB",
  "items": [
    {
      "name": "Fish and Chips",
      "description": "The tastiest Fish in the whole world",
      "plu": "11212121",
      "price": 750,
      "children": [
        {
          "name": "Extra Sauce",
          "description": "The greatest sauce in the world",
          "plu": "11211",
          "price": 150,
          "children": [
            // etc.
          ]
        }
      ]
    }
  ],
  "created_at": "1553495441",
  "channel": {
    "name": "SkipTheDishes",
    "id": 123
  },
  "deliver_at": "1553495441",
  "delivery_notes": "Notes about the delivery",
  "kitchen_notes": "Notes for the kitchen",
  "third_party_order_reference": "SKIP-12345678",
  "total": 900,
  "payment_method": "CARD",
  "tender_type": "SKIP",
  "payment": {
    "items_in_cart": {
      "inc_tax": 1017,
      "tax": 117
    },
    "final": {
      "inc_tax": 1117,
      "tax": 117
    },
    "adjustments": [
      {
        "name": "delivery fee",
        "price": {
          "inc_tax": 100,
          "tax": 0
        }
      }
    ]
  },
  "delivery": {
    "first_name": "Hannah",
    "last_name": "Customer",
    "phone_number": "28 05 2003",
    "line_one": "13/16, Elm St",
    "line_two": "Flyt",
    "city": "London",
    "postcode": "WC1X 0BL",
    "email": "integrations@flyt.io",
    "coordinates": {
      "latitude": 51.509865,
      "longitude": -0.118092,
      "latitude_as_string": "51.509865",
      "longitude_as_string": "-0.118092"
    }
  }
}


response 200 OK
{
    "OrderId": 1234
}

Collection By Customer Orders

An order where the customer will pick up their own order. To implement this order type, your endpoint must support POST requests with request bodies in the following format.

Expand
Body
{
  "type": "collection-by-customer",
  "posLocationId": "BBBBBBBBB",
  "collector": {
    "first_name": "John",
    "last_name": "Smith",
    "phone_number": "+447910575785"
  },
  "items": [
    {
      "name": "Fish and Chips",
      "description": "The tastiest Fish in the whole world",
      "plu": "11212121",
      "price": 750,
      "children": [
        {
          "name": "Extra Sauce",
          "description": "The greatest sauce in the world",
          "plu": "11211",
          "price": 150,
          "children": [
            // etc.
          ]
        }
      ]
    }
  ],
  "created_at": "1553495441",
  "channel": {
    "name": "SkipTheDishes",
    "id": 123
  },
  "collect_at": "1553495441",
  "collection_notes": "Notes about the collection",
  "kitchen_notes": "Notes for the kitchen",
  "third_party_order_reference": "SKIP-12345678",
  "total": 900,
  "payment_method": "CARD",
  "tender_type": "SKIP",
  "payment": {
    "items_in_cart": {
      "inc_tax": 1017,
      "tax": 117
    },
    "final": {
      "inc_tax": 1117,
      "tax": 117
    },
    "adjustments": [
      {
        "name": "delivery fee",
        "price": {
          "inc_tax": 100,
          "tax": 0
        }
      }
    ]
  }
}


response 200 OK
{
    "OrderId": 1234
}

Errors

In the case of an error, the endpoint should respond with an errorMessage property describing the error.

Example error messages

Below are examples of informative error messages that will help Flyt troubleshoot POS issues.

if plu was not found

{
  "errorMessage": "Could not find item {plu}"
}

if store is closed

{
  "errorMessage": "The store {storeId} is currently closed"
}

if POS is offline

{
  "errorMessage": "The terminal is off at {storeId} and cannot be connected to at this time"
}

if item is out of stock

{
  "errorMessage": "{storeId} is currently out of stock for {name}: {plu}"
}

Timeout

Your endpoint should respond with 408 TIMEOUT after 20 seconds pass without being able to process the order.