Order
Our various order APIs are used to accept both in-store and digital orders from loyalty customers. They also support our gift card and quick pay programs.
Process an order
Here, details about the items in the order, discounts on these items, and discounts on the overall order are sent to our system to complete the sale.
If the user is spending points on this order, this request removes them from the user's account. If there are any points to be gained on this order, this request will also add those points to the user's account.
The appearance of the response of this request may change based on the structure of the loyalty system with each vendor. Once this order is complete, often the DEL onscreen_close request is called immediately to close the session.
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
- Name
till- Type
- integer
- Description
Only used for tracking and information purposes, and is not relevant to the order itself.
- Name
receipt_number- Type
- string
- Description
The invoice id from the point of sale.
- Name
subtotal- Type
- float
- Description
The only value that is used to calculate points earned from this order.
- Name
taxes- Type
- array
- Description
Holds information about what taxes are on the order, not relevant to the calculation of points.
- Name
total- Type
- float
- Description
The amount the customer actually pays, not relevant to the calculation of points.
- Name
payment_method- Type
- string
- Description
How the customer pays for the order.
- Name
date- Type
- integer
- Description
The date this authorization is occurring, listed as a Unix timestamp in seconds from 1970-01-01 00:00:00 in the customer's local time.
- Name
cashier- Type
- object
- Description
Used for tracking and information purposes, not relevant to the order itself.
- Name
line_items- Type
- array
- Description
Holds information about each item in the order.
- Name
discount- Type
- array
- Description
Holds objects that have information about discounts on the overall order.
Response attributes
- Name
reference_number- Type
- string
- Description
The identification number that Spoonity uses to keep track of this order internally.
- Name
success- Type
- boolean
- Description
Indicates if the request was successfully authorized by Spoonity or not.
- Name
receipt_data- Type
- object
- Description
Holds information about the process that just occurred and information about the user indicated in the request.
Request
curl -G https://api.spoonity.com/order?api_key={api_key}
-d '{
"card_number": "brandin@spoonity.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": []
}'
Response
{
"reference_number": "17074524",
"success": "true",
"receipt_data": {
"lines": [
"100 points added"
],
"points": [
{
"currency": {
"id": 961,
"name": "Points"
},
"amount": 100,
"expiryDate": null
}
],
"user": {
"id": "582846",
"balances": [
{
"id": 191,
"currency": "Canadian Dollar",
"balance": 6.36,
"type": "Quick Pay"
},
{
"id": 961,
"currency": "Points",
"balance": 9886,
"type": "Loyalty"
}
]
}
},
"error": {
"errors": [],
"code": null,
"reference_id": null
}
}
Process a gift card
This request is used if the user authorizes payment for the current order with their quick pay balance.
The quick pay balance is retrieved by using a specific means of identification, and is used here to determine if the user has sufficient funds to spend the desired amount in quick pay, or if the user has sufficient funds to load their quick pay balance.
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
- Name
till- Type
- integer
- Description
Only used for tracking and information purposes, and is not relevant to the order itself.
- Name
receipt_number- Type
- string
- Description
The invoice id from the point of sale.
- Name
amount- Type
- float
- Description
Indicates how much is being added to or removed from the user's account, a positive value here adds this amount and a negative value removes this amount.
- Name
date- Type
- integer
- Description
The date this authorization is occurring, listed as a Unix timestamp in seconds from 1970-01-01 00:00:00 in the customer's local time.
- Name
cashier- Type
- object
- Description
Used for tracking and information purposes, not relevant to the order itself.
Response attributes
- Name
reference_number- Type
- string
- Description
The identification number that Spoonity uses to keep track of this order internally.
- Name
success- Type
- boolean
- Description
Indicates if the request was successfully authorized by Spoonity or not.
- Name
receipt_data- Type
- object
- Description
Holds information about the process that just occurred and information about the user indicated in the request.
Request
curl -G https://api.spoonity.com/order?api_key={api_key} \
-d '{
"card_number": "brandin@spoonity.com",
"till": 1,
"amount": 10.00,
"date": 1416240444
}'
Response
{
"success": true,
"reference_number": "17074472",
"receipt_data": {
"lines": [
"Successfully added 10 quick pay balance"
],
"user": {
"id": "582846",
"card_number": "brandin@spoonity.com",
"balances": [
{
"id": 191,
"currency": "Canadian Dollar",
"balance": 16.36,
"type": "Quick Pay"
}
]
}
},
"error": {
"errors": [],
"code": null,
"reference_id": null
}
}
Apply a loyalty pay payment
This request is used if the user authorizes payment for the current order with their loyalty balance. The loyalty balance is retrieved by using a specific means of identification, and is used here to determine if the user has sufficient funds to use the desired amount in loyalty points.
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
- Name
amount- Type
- float
- Description
Indicates how much is being added to or removed from the user's account, a positive value here adds this amount and a negative value removes this amount.
Response attributes
- Name
success- Type
- boolean
- Description
Indicates if the request was successfully authorized by Spoonity or not.
- Name
amount- Type
- float
- Description
Indicates the amount in dollars that was removed from the user's account, amount of points actually removed varies based on individual loyalty systems.
- Name
transaction_id- Type
- integer
- Description
A reference number that only supplements the order, this number only references the payment itself.
Request
curl -G https://api.spoonity.com/order/payments/loyalty?api_key={api_key} \
-d '{
"card_number": "brandin@spoonity.com",
"amount": 10.00
}'
Response
{
"success": true,
"amount": -10,
"transaction_id": "20720675",
"error": {
"errors": [],
"code": null,
"reference_id": null
}
}
Void an order
This request is used to void an order if necessary. Orders can only be voided in order from the most recent sale. To void a sale that was not the most recent, the more recent orders must be voided until the desired order to void is reached, that order must be voided, then the more recent orders must be re-applied in the sequence they occurred.
Query parameters
- Name
api_key- Type
- string
- Description
An API key linked to the store making the request.
Required attributes
- Name
receipt- Type
- integer
- Description
Identifies which order is meant to be voided, matches the
reference_numberthat is found in the response of the order_process (loyalty) request.
Request
curl -G https://api.spoonity.com/order?api_key={api_key} \
--request DELETE \
-d '{
"receipt": "{reference_number}"
}'
Response
{
"voided": true
}