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.

POST/order

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

POST

/order

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
      }
  }

POST/order

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

GET

/order

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
    }
}

POST/order/payments/loyalty

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

GET

/order/payments/loyalty

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
    }
}

DELETE/order

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_number that is found in the response of the order_process (loyalty) request.

Request

DELETE

/order

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

Response

{
    "voided": true
}