New API, with additional functionality and improved performance
To use the endpoints in this collection you will need the Scheme Id and an API Key. Both of these can be obtained from the scheme owner.
- SchemeId - The Scheme Id must be passed in Guid format using the header 'X-Scheme', this variable is used to choose which scheme you are making the request for.
- ApiKey - The API Key must be passed in string format in the 'X-ApiKey' header. The ApiKey is your way of authenticating that you have the right to make these requests. ApiKeys may be generated by Admins and Owners from the scheme.
This is a new API which replaces the older Transaction endpoints, with improved performance and reliability, as well as new features.
A minimal example of the new API is:
{
"customerBarcode": "3860358623507",
"outletId": "f2a961a7-e420-4742-9e69-1ba4d8ce66d4",
"lineItems": [
{
"quantity": 5,
"sku": "sku-001",
"unitPrice":5
}
]
}
sent to https://api.dev.loyale.io/api/Transaction (POST).
Either customerBarcode or customerId can be used. You can add the simulate=true query parameter to simulate the results of the transaction without processing it.
A more complex example, with more optional parameters filled is:
{
"customerBarcode": "3860358623507",
"outletId": "f2a961a7-e420-4742-9e69-1ba4d8ce66d4",
"date": "2024-09-09T12:54:54.601Z", // Transaction Date
"description":"Sale Transaction",
"uniqueId":"transaction-demo", // Used instead of the autogenerated unique id
"receiptNumber":"12345", // Saved with transaction
"pos": { // Pos details, used for some integrations or for informational purposes
"id":"POS001",
"type":"Terminal App"
},
"lineItems": [
{
"quantity": 5,
"sku": "sku-001",
"unitSalePrice":5.00
}
]
}
A sample response would be:
{
"customerId": "3524f06c-a2e9-4965-9bcf-8e0c9f0e3b08",
"status": "RECEIVED",
"statusUrl": "https://api.beta.loyale.io/api/transaction/status/transaction-demo",
"uniqueId": "transaction-demo",
"pointsEarned": 150,
"pointsRedeemed": 0,
"pointsBefore": 7830,
"pointsAfter": 7980,
"paymentMethods": [
{
"type": "Unspecified",
"amount": 25
}
]
}
More details can be provided for line items. An example is:
{
"customerBarcode": "3860358623507",
"outletId": "f2a961a7-e420-4742-9e69-1ba4d8ce66d4",
"date": "2024-09-09T12:54:54.601Z",
"description":"Sale Transaction",
"uniqueId":"transaction-demo-003",
"receiptNumber":"12345",
"pos": {
"id":"POS001",
"type":"Terminal App"
},
"lineItems": [
{
"quantity": 5,
"sku": "sku-001",
"unitPrice": 12.00, // Original Price
"unitSalePrice":10.00, // Sale Price after any discounts
"unitSalePriceBeforeTax":8.47, // Sale Price before Tax
"promotions": ["10%Off"],
"categories": ["Summer","Clothes"],
"vendor":"Clothes Ltd."
}
]
}
These work with Point Overrides, configurable through Loyale. If one wishes to not award any points for a specific Line Item for example, the override for that Category can be set to 0. Any line item with that Category will not be awarded points.
Coupons used with the transaction can be sent as follows:
{
"customerBarcode": "3860358623507",
"outletId": "f2a961a7-e420-4742-9e69-1ba4d8ce66d4",
"date": "2024-09-09T12:54:54.601Z",
"description":"Sale Transaction",
"uniqueId":"transaction-demo-003",
"receiptNumber":"12345",
"pos": {
"id":"POS001",
"type":"Terminal App"
},
"lineItems": [
{
"quantity": 5,
"description": "Line Item Description",
"sku": "sku-001",
"unitPrice": 12.00,
"unitSalePrice":10.00,
"unitSalePriceBeforeTax":8.47,
"promotions": ["10%Off"],
"categories": ["Clothes", "Summer"],
"vendor":"Clothes Ltd."
}
],
"coupons": [ // Coupons barcode, tracked by Loyale
"7652874580312"
]
}
In the previous example, no details about the Payment Methods were sent to Loyale. Payment Methods define how the customer paid for the item, and can affect how points were awarded.
A very minimal example would be:
{
"customerBarcode": "3860358623507",
"outletId": "f2a961a7-e420-4742-9e69-1ba4d8ce66d4",
"date": "2024-09-09T12:54:54.601Z",
"description": "Sale Transaction",
"uniqueId": "transaction-demo-003",
"receiptNumber": "12345",
"pos": {
"id": "POS001",
"type": "Terminal App"
},
"lineItems": [
{
"quantity": 5,
"sku": "sku-001",
"unitPrice": 12.00,
"unitSalePrice": 10.00,
"unitSalePriceBeforeTax": 8.47,
"promotions": [
"10%Off"
],
"categories": [
"Clothes",
"Summer"
],
"vendor": "Clothes Ltd."
}
],
"paymentMethods": [
{
"type": "Cash"
}
]
}
Since only one paymentMethod was used, Loyale can automatically calculate the amount. Alternatively the amount can be passed explicitly, but it must match the total of the line items.
"paymentMethods": [
{
"type": "Cash",
"amount": 40.00
}
]
Multiple payment methods can be passed:
{
"type": "Cash",
"amount": 40.0
},
{
"type": "Card",
"awardsPoints":false
}
- When passing multiple payment methods, Loyale can auto-fill up a Payment-Method if it can be determined from the other payment methods.
- Note the use of the
awardsPointsproperty. The default for this property istrue. Iffalseis passed then no points will be awarded on the part paid by that payment method.
Payment Methods handled by Loyale have the Loyale prefix. Currently there are 2 types of such payment methods; Loyale Gift Cards and Loyale Redemption
An example of Loyale Gift Cards usage is:
"paymentMethods": [
{
"type": "Cash",
"amount": 40.0
},
{
"type": "Loyale Gift Card",
"reference":"4334603388774",
"amount": 10.0
}
Reference is the barcode associated with that linked Gift Card.
For Redemptions, the following can be used:
"paymentMethods": [
{
"type": "Cash",
"amount": 40.0
},
{
"type": "Loyale Redemption",
"amount": 10.0
}
In this case the 10.00 EUR will be deducted from the point balance. If the customer doesn't have enough points, an error will be returned.
{
"error": "Customer does not have enough points for redemption. Required: 5000000 Current: 7980"
}
Auto-fill can be leveraged when using redemptions. For example:
"paymentMethods": [
{
"type": "Cash"
},
{
"type": "Loyale Redemption"
}
]
This will use the maximum possible Loyale Redemption (which always take priority). If the customer doesn't have enough points available, the remaining will be assigned to the cash payment method.
This is useful if the customer wishes to use all of his remaining balance.
In such case, a possible workflow would be to first call the endpoint with ?simulate=true so Loyale returns how much cash is needed. Once payment is confirmed, the same transaction endpoint is called without simulate.
Returns
Loyale offers 4 types of returns:
In-line Returns
For simple use-cases, using an in-line return might be sufficient. These can be used when a new purchase is being made and the return will be given by a reduced price of the new purchase. The overall points given by the transaction must be greater than or equal to 0.
To use In-line returns, simply pass a line item with a negative quantity.
"lineItems": [
{
"quantity": -5,
"description": "Line Item Description",
"sku": "sku-001",
"unitPrice": 12.00,
"unitSalePrice":10.00,
"unitSalePriceBeforeTax":8.47,
"promotions": ["10%Off"],
"categories": ["Clothes", "Summer"],
"vendor":"Clothes Ltd."
}
],
Full Transaction Returns
https://api.beta.loyale.io/api/Transaction/Return/Full/unique_id} (POST)
Where unique_id is the uniqueId for the past transaction. The customer will automatically be assigned the return of the original transaction.
If the original transaction had points added, the customer will be deducted points. If the original transaction included a points redeem, the customer will be re-awarded those points.
Example response:
{
"pointsDeducted": 150,
"pointsReadded": 0,
"returnType": "Full Transaction: 7993bf4463c8a69e2fbfddd42e524e802555da79bbe1f6c36300b145df555021",
"usedPaymentMethods": [
{
"type": "Cash",
"amount": 25.00
}
],
"pointsBefore": 8130,
"pointsAfter": 7980,
"customerId": "3524f06c-a2e9-4965-9bcf-8e0c9f0e3b08"
}
The simulate query parameter is supported for return endpoints as well.
Line Item Returns
In cases where not the full transaction is being returned, then a line item return can be made:
https://api.beta.loyale.io/api/Transaction/Return/LineItem/unique_id} (POST)
with body:
{
"sku": "sku-001",
"quantity": 1
}
In this case, only the equivalent points for 1 item of sku-001 is returned. Response will be identical to a Full Transaction Return.
Custom Returns
Custom Returns are returns that are dynamically calculated without referencing any existing transaction.
This is useful when performing a return on the fly, where the points and refund details are computed based on the current setup.
https://api.dev.loyale.io/api/Transaction/Return/Custom (POST)
In this case the body will consist of the same model used for transaction. For example:
{
"customerBarcode": "3860358623507",
"outletId": "f2a961a7-e420-4742-9e69-1ba4d8ce66d4",
"lineItems": [
{
"quantity": 5,
"sku": "sku-001",
"unitPrice":5.00
}
]
}
The points will be dynamically calculated and returned using the current setup and line overrides.