Requirements - Contact Us To Get Onboarded - Example Order Packet - Order Object Schema - Order Status Updates

Introduction

Most Checkmate Partnerships are with Point of Sale (i.e. POS) companies, and Ordering Platform (i.e. OP) companies. However, the restaurant technology ecosystem also contains companies that do not neatly fall into either of those categories, even if their business model does overlap with Checkmate's purview to a great extent. With a new initiative to implement Order Receiver (i.e. OR) Partnerships we're offering a new service aimed at this cohort.

One obvious example for a potential Order Receiver Partnership would be a "Last Mile Delivery" company. "Last Mile Delivery" companies act as delivery contractors for Ordering Platforms and may, for any given geographic area, be providing that service for multiple Ordering Platforms. In such cases, an OR Partnership with Checkmate will provide these companies with a standardized payload format that their servers can ingest via endpoints configured to receive REST API calls from Checkmate. Additionally, OR Partnership companies should soon be able to send Order Status Updates back to those Ordering Platforms via a standardized payload format that Checkmate can ingest via endpoints configured to receive REST API calls.

Requirements

We encourage ORs to prepare for integration with Checkmate by reviewing the information contained herein, and preparing their systems to receive JSON order packets to match the provided specifications. The URL endpoint Target for Relayed Orders on the OR Server should be configured for POST requests and require an Authorization Token in the Header as such:

Authorization: Basic <token>

API calls to this endpoint meeting the above denoted requirements and conforming to the JSON payload described below should return return a 200 Success response. If the Authorization Token check fails a 401 Unauthorized Error should get returned. All other issues with the payload structure, content, etc, should cause the return of a 400 Bad Request Error.

You may set the URL endpoint Target for Relayed Orders after you get your log-in information for https://platform.itsacheckmate.com . After logging in - navigate to the "Order Management" Tab, then the "Configuration" Tab: https://platform.itsacheckmate.com/order_receivers#config . The "Target URL" and the "Authorization Token" may be set there. Also - you can retrieve the IACM Token required for sending us Order Status Updates (see bottom of page).

How To Get Started

If you would like to become an Order Receiver and you have reviewed the specifications in this document, you can fill out this onboarding form. Our team will then review your submission and, if approved, we will contact your team and provide you with further instructions and access to our sandbox Developer Portal to begin development and testing. If you have any questions you can contact us at [email protected].

Example Order Packet

{
  "order": {
    "order_id": "5aq9f8w7v3f0ajp",
    "vanity_order_id": "f0ajp",
    "order_created_at": "2023-11-09T09:13:52Z",
    "order_source": "uber",
    "location": {
      "location_id": 502262,
      "name": "Luigi's Pizza",
      "timezone": "Eastern Time (US & Canada)"
    },
    "meta": {
      "type": "restaurant_delivery",
      "notes": "Please include plastic utensils, napkins, forks, etc.",
      "requested_at": "2023-11-09T12:13:51+00:00"
    },
    "customer": {
      "first_name": "toon",
      "last_name": "test",
      "phone": "0984873344",
      "email": "[email protected]",
      "address": {
        "street": "123 Anywhere St",
        "street2": "Unit 456",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001"
      }
    },
    "items": [
      {
        "name": "Hamburger",
        "price": 800,
        "quantity": 1,
        "special_request": "",
        "modifiers": [
          {
            "name": "Cheddar",
            "price": 50,
            "quantity": 1,
            "modifiers": [

            ],
            "group_name": "Cheese"
          }
        ]
      },
      {
        "name": "Bacon Cheeseburger",
        "price": 1000,
        "quantity": 1,
        "special_request": "",
        "modifiers": [
          {
            "name": "Mustard",
            "price": 50,
            "quantity": 1,
            "modifiers": [

            ],
            "group_name": "Sauce"
          }
        ]
      }
    ],
    "payment": {
      "cash_payment": false,
      "tip": "3000",
      "service_fees": [
        {
          "name": "long distance",
          "amount": "2000"
        }
      ],
      "discounts": [

      ]
    }
  }
}

Order (object)

If a field is denoted as "required" - it should be considered as something guaranteed to always be included.

order_id: example_thirdparty7877561 (string, required) - unique order identifier / number - Since we can't guarantee that these will be unique between Third Party Platforms we will pre-pend the order-source name to the identifier, such that an order identifier / number like '7877561' would become 'example_thirdparty-7877561'
vanity_order_id: B12CB (string, optional) - (Display ID from Uber) this information is only available for Uber
order_created_at: "2020-05-18T21:35:48:50Z"(string, required) - ISO8601 formatting
order_source (enum, required) - a name that represents the Third Party Platform - e.g. "uber" for Uber
- uber
- postmates
- doordash
location (object, required)
- location_id: 9016527 (string, required) - Checkmate's unique identifier for this store
- name: Luigi's Pizza - NYC (string, required) - the specific location's name. after initial setup, the provided name will, most likely but not guaranteed, continue to match the id (i.e. unique identifier) provided for the location.
- timezone: America/New York (string, required) - only TZ database names (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), and their Rails "ActiveSupport::TimeZone" class friendly name equivalents, are supported. Full list: https://gist.github.com/ray-checkmate/436b4b414c48a90a228a72284451b100
meta (object, required)
- type (enum, required) - what sort of order the restaurant should see this as
  - pick_up
  - driver_delivery
  - restaurant_delivery
- notes (string, optional) - any general order notes, as well as delivery instructions, will be consolidated here
- requested_at (string, optional) - ISO8601 formatting (e.g. "2019-08-21T22:16:23.914+00:00"). will be null when the order is ASAP. otherwise, will be time of restaurant pick up when the order is of type Pick Up (see note) or Driver Delivery (see note). Otherwise, should be time expected to arrive at customer home/office when the order is of type Restaurant Delivery (see note). (note: see order["meta"]["type"] acceptable values description above.)
customer (object, required)
- first_name (string, optional) - this information's availability may vary by Third Party Platform
- last_name (string, optional) - this information's availability may vary by Third Party Platform
- phone: +1 (800) 876-5309 or (212) 555-5555 (string, optional) - we take any reasonably formatted phone number for its locality, and discard any phone numbers we can't make sense of and submit the order without one.
- email (string, optional)
- address (object, optional) - required when order_type is restaurant_delivery
  - street (string, required)
  - street2 (string, optional)
  - city (string, required)
  - state (string, required)
  - postal_code (string, required)
items (array, required)
- (item object - singular)
  - group_name (string, optional) - the menu section an item belongs to, such as Burgers or Drinks
  - name (string, required)
  - id (string, optional) - mostly this is vestigial, and mapping is done by item name, but may be used in the future when included
  - price: 2343 (number, optional) - (per single unit) - if sent, this will be sent in cents (i.e. for item worth $23.43, this would be sent as 2343)
  - quantity (number, required)
  - special_request (string, optional) - will include customer supplied requests, as well as consolidate any extraneous properties selected by the user via checkboxes, etc
  - name_label (string, optional) - for group orders, when items are labeled for individual guests
  - modifiers (array, optional)
    - (modifier object - singular)
      - group_name (string, optional) - the modifier group a modifier belongs to, such as Size or Side Item
      - name (string, required)
      - price (number, optional) - (per single unit) - as with items, this will be an integer, the price in cents (i.e. for a modifier that costs $1.25, should be 125)
      - quantity (number, required) - this is the quantity PER ITEM, so burger quantity of 2 with cheese quantity of 2 means that we want 2 slices of cheese PER BURGER
      - modifiers (array, optional) - we allow for nested modifiers, but this is not a commonly used feature
        
        (object)
        
        see_above (string, optional) - look at above modifiers chart for matching attributes
payment (object, optional)
- cash_payment (boolean)
- tip (number, optional) - as in items, all currency amounts will be sent using cents (i.e. with an integer, not a float)
- service_fees (array, optional) - delivery fee, etc
  - (object)
    - name (string, required)
    - amount (number, required)
- discounts (array, optional)
  - (discount object - singular)
    - name (string, required)
    - amount (number, required)

Order Status Updates

We have already implemented an endpoint (e.g. POST https://app.itsacheckmate.com/or_status_transition) on our server wherein Order Status Updates (e.g. Accepted, Delayed, Delivered, etc.) may be sent back to Checkmate - and we intend to eventually implement a relay of that information back to the Ordering Platforms. This should happen soon - and all in progress and operational Order Receivers will be notified when the functionality becomes available.

For Authentication, put an "API_KEY" value in the Headers that matches what you have set for IACM Token under the Order Management Tab in Platform:

https://platform.itsacheckmate.com/order_receivers#config

Status values: e.g. "accepted", "driver_assigned", "order_picked_up", "order_delivered", "order_cancelled"

Format of the Order Receiver Status Transition POST payload packet:

{  
  "unique_id": 5, # What we sent to you previously  
  "status": "accepted", # See Status Values list above  
  "notes": "Lorem Ipsum"  
}