Placing an order
Ordering is the primary source of balance adjustments within the loyalty platform. Orders help customers both earn and spend currency, and are how the Spoonity platform tracks behaviours and balance adjustments over time.
The ordering workflow
The typical ordering workflow follows a consistent pattern:
- identify the customer
- construct the order
- apply payment(s)
- submit the order
Note that the above elements can sometimes occur in different orders depending on the ordering platform.
The Spoonity API supports several integration points to support different stages of this workflow. Other parts of the workflow are handled externally, such as selecting the items for the order.
Checking a customer in
A necessary step for completing any order is to identify the customer. For in-store environments, this task is typically performed by the cashier working the register, or through customer-facing kiosks or tablets.
If the merchant has a dedicated mobile app or microsite, the customer may also be identified using an on-device identifier such as a barcode or token that can be generated using this API
This checkin process is essential, as it allows the application to review the status of the customer's account, as well as link them to an upcoming order for processing.
The Spoonity API supports this checkin process through it's onscreen APIs.
Create a POS session
The first step of checking in a customer is to create a "POS session" through the POST /onscreen API.
This session is passed to the next step and is used to retrieve balance and rewards information about the customer.
Create a POS session
curl -G https://api.spoonity.com/onscreen?api_key={api_key} \
-d "{
"card_number": "john.smith@example.com"
}"
Retrieve customer details from session
Take the generated pos_session_hash from the previous step, and pass it to the same endpoint as a GET request.
The response will include personal details about the customer, a list of their balances, and information about which rewards they are eligible for.
Note that the response from this request will only include rewards that this customer is eligible for. In cases where the application needs a full list of all rewards, they should make use of the GET /vendor/perk/redemption/list instead.
Retrieve customer details from session
curl -G https://api.spoonity.com/onscreen?api_key={api_key}&pos_session_hash={pos_session_hash}
Applying payments
Optionally, customers can apply payments against orders using one or more balances. The Spoonity platform supports paying for orders using a gift card or quickpay balance, or using a loyalty balance.
Gift card balances are applied using the same POST /order API, but with a different request body. Loyalty balance payments are applied using a dedicated API endpoint.
Pay using a gift card
Gift card payments are processed through a separate POST /order request. This request applies a debit against the customer's gift card balance, which you can then reconcile against the order.
Note that this API can be used for both debiting and crediting gift card balances.
Pay using a gift card
curl -G https://api.spoonity.com/order?api_key={api_key} \
-d '{
"card_number": "john.smith@example.com",
"till": 1,
"amount": -10.00,
"date": 1416240444
}'
Pay using a loyalty balance
Payments can also be applied using a customer's loyalty balance through our Loyalty Pay feature. This process uses a dedicated API which converts a balance of points to a cash-based equivalent at runtime.
Pay using a loyalty balance
curl -G https://api.spoonity.com/order/payments/loyalty?api_key={api_key} \
-d '{
"card_number": "brandin@spoonity.com",
"amount": 10.00
}'
Submitting the loyalty order
Once the order has been completed and resolved inside your application, you can submit it to Spoonity for final processing.
Our platform will automatically apply any relevant loyalty rules as part of the order processing step.
Submit the order
Submit the order using the POST /order request. The platform will perform a final validation of the contents, apply any loyalty rules, and respond with the results.
The Spoonity API is only capable of processing whole orders. When an order is submitted, it is assumed to be in a complete state, and is therefore immutable.
Note that the immutable nature of the order means that loyalty redemption scenarios may fail and return an error (in cases where the customer does not have sufficient balance, for example). Your application must be able to handle these kinds of failures.
Submit the order
curl -G https://api.spoonity.com/order?api_key={api_key}
-d '{
"card_number": "john.smith@example.com",
"till": 1,
"receipt_number": "BC-PROMO-005",
"subtotal": 10,
"taxes": [],
"total": 10,
"payment_method": "CASH",
"date": "1422901482",
"cashier": {
"id": "_tony_",
"name": "Tony"
},
"line_items": [{
"id": "__unknown_id",
"name": "Unknown product",
"categories": [],
"discounts": [],
"price": 10,
"quantity": 1,
"modifiers": []
}],
"discounts": []
}'
Order cleanup
The final stages of the order workflow involve cleanup.
Whenever possible, completed or previously-created POS sessions should be closed.
Finally, in cases where a cashier or customer has made a mistake, orders can be voided to revert any loyalty changes that were created as a consequence of that order.
Close POS session
In most cases, opened POS sessions as part of a customer checkin will be closed automatically by the platform in the background.
This behaviour can be disabled from the Spoonity dashboard. If the system does not automatically clean up a spent session, then your application should take steps to manually close them.
Close POS session
curl -G https://api.spoonity.com/onscreen?api_key={api_key} \
--request DELETE \
-d '{
"pos_session_hash": "{pos_session_hash}"
}'
Void an order
Sometimes, orders must be cancelled. This could be due to an error, a missing item, or as the resolution of a customer complaint.
In any case, the Spoonity API includes a voiding API to mark the order as cancelled, as well as to revert any loyalty changes that were made as a result of that order.
Orders must be voided in the order they are created for each customer, for each location.
Void an order
curl -G https://api.spoonity.com/order?api_key={api_key} \
--request DELETE \
-d '{
"receipt": "{reference_number}"
}'