OnScreen

These APIs are used to support the in-store customer experience, allowing cashiers to "check-in" customers, check their status, and more.

POST/onscreen

Check in a customer

This is the call that occurs when a customer is in store engaging with a cashier, and provides information that can be used to identify this customer. The identification of the customer is crucial for the next step in the workflow, and is made accessible to that request via the hash value that is returned in the response of this request.

Query parameters

Name
api_key
Type
string
Description
An API key linked to the store making the request.

Required attributes

Name
card_number
Type
string
Description
Part of the user's identification which allows us to access details about account holder, can be given as:
- card number
- email address
- mobile phone number
- app token
- cedula
- passport number

Response attributes

Name
pos_session
Type
object
Description
An object that holds information about the current point of sale session that has been created with this request.

Name
vendor
Type
object
Description
An object that contains information about the vendor this order has been created through.

Name
api_key
Type
object
Description
Used for a small subset of point of sale integration, can likely be ignored.

Request

POST

/onscreen

curl -G https://api.spoonity.com/onscreen?api_key={api_key}
-d '{
    "card_number": "{card_number}"
}'

Response

  {
      "pos_session": {
          "id": 23471296,
          "object": "pos_session",
          "hash": "71c61a3b5792027672d010fe5426b92f",
          "date_created": 1557324704,
          "date_updated": 1557324704,
          "status": {
              "id": 1,
              "name": "Active"
          }
      },
      "vendor": {
          "object": "vendor",
          "id": 1,
          "point_of_sale": {
              "object": "pointofsale",
              "id": 5,
              "name": "Manual",
              "status": {
                  "id": 1,
                  "name": "Active"
              }
          },
          "modules": {
              "object": "collection",
                "data": [
                {
                    "object": "middlewaremodule",
                    "id": 1,
                    "name": "Loyalty"
                },
                {
                    "object": "middlewaremodule",
                    "id": 2,
                    "name": "Quick Pay"
                }
                ],
                "page_size": 2,
                "count": 2,
                "page": 1
          }
      },
      "api_key": {
          "workstation_identifier": null
      }
  }

GET/onscreen/queue

Retrieve a list of checked-in customers

This request is used to access a list of users who are already checked in, which can be done by the customer through a mobile application or manually by a cashier.

The request returns an array of sessions of checked in users, each with a unique point of sale hash key which is referenced whenever that session's user information is required.

Query parameters

Name
api_key
Type
string
Description
An API key linked to the store making the request.

Response attributes

Name
pos_session
Type
object
Description
An object that holds information regarding this specific point of sale session.

Request

GET

/onscreen/queue

curl -G https://api.spoonity.com/onscreen/queue?api_key={api_key} \

Response

[
    {
        "pos_session": {
            "id": 23471267,
            "object": "pos_session",
            "hash": "e777c6662bcfa23f327b9a8b07b7e50c",
            "vendor": {
                "vendor_id": 1044093,
                "name": "Store example"
            },
            "user": {
                "user_id": "1000454652113",
                "first_name": "Guest",
                "last_name": "",
                "email_address": "guest_8a732bcec1ed306df35780788648c2ea"
            },
            "table_number": null,
            "redemptions": [],
            "payments": [],
            "date_created": 1556646066,
            "date_updated": 1556646066,
            "status": {
                "id": 1,
                "name": "Active"
            }
        }
    },
...
]

GET/onscreen

Retrieve customer from a checkin

This request uses the point of sale session hash key that was generated with the onscreen_create request to access the identification information that was provided by the user.

This identification information allows us to retrieve the user's account, which gives us information like their first and last names, their birthday, and a list of rewards this user is currently eligible for. The user's loyalty and quick pay balances are also retrieved at this point, which are necessary in the step for the authorization of payments.

Query parameters

Name
pos_session_hash
Type
string
Description
A hash generated as part of the POST /onscreen request.

Name
api_key
Type
string
Description
An API key linked to the store making the request.

Response attributes

Name
pos_session
Type
object
Description
An object that holds information regarding this specific point of sale session.

Name
user
Type
object
Description
An object that holds all information related to the user in the current session.

Name
favourite_items
Type
array
Description
An array that contains information about the user's favourite items.

Name
reload
Type
object
Description
An object that contains information regarding the user's auto-reload configuration.

Name
loyalty_balance
Type
object
Description
An object that contains information about the loyalty balance associated with this user, this object contains.

Name
rules
Type
object
Description
An object that holds information about the rules for this current point of sale.

Name
quick_pay_balance
Type
object
Description
An object that holds information about the quick pay balance a user has linked to their account.

Request

GET

/onscreen

curl -G https://api.spoonity.com/onscreen?pos_session_hash={pos_session_hash}&api_key={api_key} \

Response

{
    "pos_session": {
        "pos_session_id": "23471297",
        "hash": "fd322bcc9364864dabb582dcc6b88fec",
        "status": {
            "id": 1,
            "name": "Active"
        },
        "card": null,
        "card_third_party": null,
        "token": null
    },
    "user": {...},
    "favourite_items": [],
    "reload": {
        "amount": 0,
        "threshold": 0,
        "billing_profile": null
    },
    "favorite": null,
    "last_visit": null,
    "loyalty_balance": {
        "data": [
            {
                "amount": 9696,
                "currency": {
                    "id": 961,
                    "name": "Points",
                    "code": null
                },
                "expiring": {
                    "data": [],
                    "page_size": 0,
                    "count": 0,
                    "page": 1
                }
            },
        ]
    },
    "rules": {
        "earning": {...},
        "spending": {...},
        "tier": {...}
    },
    "quick_pay_balance": {
        "amount": 6.36,
        "currency": {
            "id": 191,
            "name": "Canadian Dollar",
            "code": "CAD"
        },
        "expiring": {
            "data": [],
            "page_size": 0,
            "count": 0,
            "page": 1
        }
    }
}

DELETE/onscreen

End a check-in

This request uses the session hash key that was generated in the first call of this workflow to close the current session so the next user can check in. In most cases, the Spoonity API automatically closes the most recent session once an order is complete, however this request can also be called manually.

Query parameters

Name
api_key
Type
string
Description
An API key linked to the store making the request.

Required attributes

Name
pos_session_hash
Type
string
Description
The hash value for the session that is being closed.

Request

DELETE

/onscreen

curl -G https://api.spoonity.com/onscreen?api_key={api_key} \
--request DELETE \
-d '{
    "pos_session_hash": "{pos_session_hash}"
}'

Response

{}

POST/onscreen/register

Register in-store

This request allows customers to register and create an onscreen session themselves.

Query parameters

Name
api_key
Type
string
Description
An API key linked to the store making the request.

Optional attributes

Name
phone_number
Type
object
Description
An object that contains information about the user's phone number.

Name
email
Type
string
Description
The email the user would like to register with.

Response attributes

Name
pos_session
Type
object
Description
An object that holds information about the current point of sale session that has been created with this request.

Name
vendor
Type
object
Description
An object that contains information about the vendor this order has been created through.

Name
api_key
Type
object
Description
Used for a small subset of point of sale integration, can likely be ignored.

Request

POST

/onscreen/register

curl -G https://api.spoonity.com/onscreen/register?api_key={api_key}
-d '{
    "phone_number": {
        "number": "1234567890",
        "code": "1"
    }
}'

Response

{
    "pos_session": {
        "id": 23471301,
        "hash": "4c3161cfd9c926e6fa17299f916e8435",
        "date_created": 1557338280,
        "date_updated": 1557338280,
        "status": {
            "id": 1,
            "name": "Active"
        }
    },
    "vendor": {
        "id": 1,
        "point_of_sale": {
            "pointOfSale_id": 5,
            "name": "Manual"
        },
        "modules": {
            "data": []
        }
    },
    "api_key": {
        "workstation_identifier": null
    }
}

GET/user/transaction/list

Retrieve customer history

This request returns a list of a specified user's most recent transactions, ordered from newest to oldest. Only transactions that involved spending or earning quickpay or loyalty currencies are returned here. This request allows changes to this user's account balances to be seen.

Query parameters

Name
user
Type
integer
Description
The user_id for the desired customer.

Name
api_key
Type
string
Description
An API key linked to the store making the request.

Response attributes

Name
rating
Type
object
Description
An object that holds information about the rating of this transaction.

Name
tip
Type
object
Description
An object that contains information about the tip on this transaction.

Name
id
Type
integer
Description
The internal reference number for this specific transaction.

Name
date
Type
integer
Description
The date this transaction was completed, listed as a Unix timestamp in seconds from 1970-01-01 00:00:00.

Name
total
Type
float
Description
Usually the same as subtotal, safe to ignore as does not affect the calculation of points.

Name
address
Type
string
Description
The address of the store where this transaction occurred.

Name
name
Type
string
Description
The name of the store where this transaction occurred.

Name
quickpay
Type
object
Description
An object that holds information regarding the changes in quickpay balance for this transaction.

Name
items
Type
array
Description
An array of objects where each object holds information about an item on this order.

Name
receipts
Type
array
Description
Holds the receipt information for this transaction.

Name
reward
Type
array
Description
An array of objects that each contain information regarding the rewards redeemed or earned on this transaction.

Name
status
Type
string
Description
Indicates the status of the transaction in a way that is user friendly.

Request

GET

/user/transaction/list

curl -G https://api.spoonity.com/user/transaction/list?user={user_id}&api_key={api_key} \

Response

{
    "object": "collection",
    "count": 248,
    "page": 1,
    "page_size": 10,
    "total_pages": 25,
    "next_page_url": "http://api-staging.spoonity.com/user/transaction/list?user=582846&api_key=0e5a39f0c70451e900233b689e3445b5&page=2&limit=10",
    "previous_page_url": null,
    "data": [
        {
            "rating": {
                "comment": null,
                "value": -1,
                "window": 0
            },
            "tip": {
                "amount": 0,
                "window": 0
            },
            "object": "virtual\\transaction",
            "id": 20730708,
            "date": 1613057680,
            "total": 0,
            "address": "10 Rockefeller Plaza",
            "name": "Demo Store",
            "quickpay": {
                "object": "virtual\\transaction\\quickpay",
                "used": 0,
                "loaded": 0,
                "balance": 52.43
            },
            "items": [...],
            "taxes": [],
            "receipts": [...],
            "rewards": [...],
            "status": "Complete"
        }
    ]
}