OnScreen
These APIs are used to support the in-store customer experience, allowing cashiers to "check-in" customers, check their status, and more.
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
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
}
}
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
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"
}
}
},
...
]
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
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
}
}
}
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
curl -G https://api.spoonity.com/onscreen?api_key={api_key} \
--request DELETE \
-d '{
"pos_session_hash": "{pos_session_hash}"
}'
Response
{}
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
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
}
}
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
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"
}
]
}