Loyalty Receipts Core API
API Endpoint
api.receipts.wlloyalty.net/v1Introduction
White Label Loyalty Core Receipts API.
Authorization
All requests to the API must contain a X-Api-Key header to identify your
tenant account. In addition to the API key, some methods additionally require
a Authorization header to identify the user or entity accessing the API, and
ensure the requester has sufficient permissions for the requested operation.
This means that there are three levels of authorization which you should be aware when using this API:
-
🔑 Anonymous (API key only)
-
👤 User (API key + end-user auth token)
-
🔐 Admin (API key + administrative auth token)
Each API method described in this documentation will advise which type of authorization is requried.
Receipts ¶
Receipts Collection ¶
POST api.receipts.wlloyalty.net/v1/receipts
Requests
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_tokenBody
{
"useParser": true,
"submitter": {
"authIdentifier": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
},
"pictureUrl": "https://example.com/receiptImage.jpg",
"submissionPosition": {
"longitude": 170.9021,
"latitude": 80.9021
},
"metadata": {
"source": "API",
"campaignId": "ExampleCampaign",
"key": "value"
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"useParser": {
"type": "boolean"
},
"submitter": {
"type": "object",
"properties": {
"authIdentifier": {
"type": "string"
}
},
"required": [
"authIdentifier"
]
},
"pictureUrl": {
"type": "string"
},
"submissionPosition": {
"type": "object",
"properties": {
"longitude": {
"type": "number"
},
"latitude": {
"type": "number"
}
},
"required": [
"longitude",
"latitude"
]
},
"metadata": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"campaignId": {
"type": "string"
},
"key": {
"type": "string"
}
},
"required": [
"source"
]
}
},
"required": [
"useParser",
"pictureUrl"
]
}Responses
Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "success",
"data": {
"id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50",
"status": "PENDING",
"paramountReview": {
"id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50",
"verdict": "ABSTAIN",
"reason": "OTHER",
"createdAt": "2017-11-11T06:00:00.000Z",
"isAutomated": true,
"reviwer": {
"authIssuer": "auth.wlloyalty.net",
"authIdentifier": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50",
"name": "Jane Doe"
},
"comment": "Hello, world!"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"PENDING",
"AUTHORIZED",
"REJECTED"
]
},
"paramountReview": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string"
},
"verdict": {
"type": "string",
"enum": [
"ABSTAIN",
"REJECT",
"AUTHORIZE"
]
},
"reason": {
"type": "string",
"enum": [
"OTHER",
"VERIFIED",
"VALID_DATA",
"FLAGGED_FOR_SPOT_CHECK",
"DUPLICATE",
"INVALID_MERCHANT",
"INVALID_DATE",
"INSUFFICIENT_DATA",
"SUSPICIOUS",
"SUSPICIOUS_CONTEXT",
"RULE_ENGINE_THREW_ERROR",
"INVALID_VENUE",
"FORMAT_SUBMISSION_LIMIT_EXCEEDED",
"MERCHANT_SUBMISSION_LIMIT_EXCEEDED",
"NO_QUALIFYING_PRODUCTS",
"INVALID_MULTIPAGE_CLAIM",
"TEST"
]
},
"createdAt": {
"type": "string"
},
"isAutomated": {
"type": "boolean"
},
"reviwer": {
"type": [
"object",
"null"
],
"properties": {
"authIssuer": {
"type": "string"
},
"authIdentifier": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"authIssuer",
"authIdentifier"
]
},
"comment": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"verdict",
"reason"
]
}
},
"required": [
"id",
"status",
"paramountReview"
]
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"name": "InvalidApiKeyError",
"httpCode": 403
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"httpCode": {
"type": "number"
}
}
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"name": "UnauthorizedError",
"httpCode": 401
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"httpCode": {
"type": "number"
}
}
}
}
}Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_tokenBody
{
"useParser": false,
"submitter": {
"authIdentifier": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
},
"pictureUrl": "https://example.com/receiptImage.jpg",
"ocrConfidence": 0.76,
"serviceDate": {
"value": "2019-08-28",
"confidence": 0.89
},
"serviceTime": {
"value": "22:34",
"confidence": 0.89
},
"lineItems": [
{
"quantity": 2,
"description": "Banana",
"identifier": "SKU123",
"unit": "Bunch",
"unitPrice": 1.99,
"totalPrice": 3.98,
"metadata": {
"key": "value"
}
}
],
"subtotal": {
"value": "Hello, world!",
"confidence": 0.89
},
"total": {
"value": "Hello, world!",
"confidence": 0.89
},
"barcode": {
"value": "Hello, world!",
"confidence": 0.89
},
"locationIdentifier": {
"value": "Hello, world!",
"confidence": 0.89
},
"locationAddress": {
"value": "Hello, world!",
"confidence": 0.89
},
"submissionPosition": {
"longitude": 170.9021,
"latitude": 80.9021
},
"formatSlug": "format-name",
"merchantName": {
"value": "Hello, world!",
"confidence": 0.89
},
"language": {
"value": "en",
"confidence": 0.89
},
"metadata": {
"source": "API",
"campaignId": "ExampleCampaign",
"key": "value"
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"useParser": {
"type": "boolean"
},
"submitter": {
"type": "object",
"properties": {
"authIdentifier": {
"type": "string"
}
},
"required": [
"authIdentifier"
]
},
"pictureUrl": {
"type": "string"
},
"ocrConfidence": {
"type": "number"
},
"serviceDate": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"confidence": {
"type": "number"
}
},
"required": [
"value",
"confidence"
]
},
"serviceTime": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"confidence": {
"type": "number"
}
},
"required": [
"value",
"confidence"
]
},
"lineItems": {
"type": "array"
},
"subtotal": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"confidence": {
"type": "number"
}
},
"required": [
"value",
"confidence"
]
},
"total": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"confidence": {
"type": "number"
}
},
"required": [
"value",
"confidence"
]
},
"barcode": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"confidence": {
"type": "number"
}
},
"required": [
"value",
"confidence"
]
},
"locationIdentifier": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"confidence": {
"type": "number"
}
},
"required": [
"value",
"confidence"
]
},
"locationAddress": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"confidence": {
"type": "number"
}
},
"required": [
"value",
"confidence"
]
},
"submissionPosition": {
"type": "object",
"properties": {
"longitude": {
"type": "number"
},
"latitude": {
"type": "number"
}
},
"required": [
"longitude",
"latitude"
]
},
"formatSlug": {
"type": "string"
},
"merchantName": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"confidence": {
"type": "number"
}
},
"required": [
"value",
"confidence"
]
},
"language": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"confidence": {
"type": "number"
}
},
"required": [
"value",
"confidence"
]
},
"metadata": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"campaignId": {
"type": "string"
},
"key": {
"type": "string"
}
},
"required": [
"source"
]
}
},
"required": [
"useParser",
"ocrConfidence",
"lineItems"
]
}Responses
Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "success",
"data": {
"id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50",
"status": "PENDING",
"paramountReview": {
"id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50",
"verdict": "ABSTAIN",
"reason": "OTHER",
"createdAt": "2017-11-11T06:00:00.000Z",
"isAutomated": true,
"reviwer": {
"authIssuer": "auth.wlloyalty.net",
"authIdentifier": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50",
"name": "Jane Doe"
},
"comment": "Hello, world!"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"PENDING",
"AUTHORIZED",
"REJECTED"
]
},
"paramountReview": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string"
},
"verdict": {
"type": "string",
"enum": [
"ABSTAIN",
"REJECT",
"AUTHORIZE"
]
},
"reason": {
"type": "string",
"enum": [
"OTHER",
"VERIFIED",
"VALID_DATA",
"FLAGGED_FOR_SPOT_CHECK",
"DUPLICATE",
"INVALID_MERCHANT",
"INVALID_DATE",
"INSUFFICIENT_DATA",
"SUSPICIOUS",
"SUSPICIOUS_CONTEXT",
"RULE_ENGINE_THREW_ERROR",
"INVALID_VENUE",
"FORMAT_SUBMISSION_LIMIT_EXCEEDED",
"MERCHANT_SUBMISSION_LIMIT_EXCEEDED",
"NO_QUALIFYING_PRODUCTS",
"INVALID_MULTIPAGE_CLAIM",
"TEST"
]
},
"createdAt": {
"type": "string"
},
"isAutomated": {
"type": "boolean"
},
"reviwer": {
"type": [
"object",
"null"
],
"properties": {
"authIssuer": {
"type": "string"
},
"authIdentifier": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"authIssuer",
"authIdentifier"
]
},
"comment": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"verdict",
"reason"
]
}
},
"required": [
"id",
"status",
"paramountReview"
]
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"name": "InvalidApiKeyError",
"httpCode": 403
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"httpCode": {
"type": "number"
}
}
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"name": "UnauthorizedError",
"httpCode": 401
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"httpCode": {
"type": "number"
}
}
}
}
}Claim a ReceiptPOST/receipts
This endpoint can be used to submit a claim for a receipt/invoice by a user or on behalf of a user. The endpoint can be operated in two modes Default or Preparsed. The request payload differs between these two modes, use the buttons on the right to show the request example for either mode.
Default Mode
The default mode is intended for use when you want to submit only an image of a receipt and let the API handle both parsing and claim management. For this request the only required data is a URL to the publically accessible image.
This can be called either with the user’s own authentication token or otherwise an admin token can be provided in which case the user who is making the claim must be specified in the submitter property.
Preparsed Mode
The preparsed mode can be used in cases where you have already obtained the parsed receipt data and just want to register it with the claim management system.
Only admin tokens are accepted in this mode so the user who is making the claim must be specified in the submitter property.
Response Codes
Status
-
PENDING- No definite automated decision could be made and so it has been sent for manual review. -
REJECTED- It has been automatically rejected for the reason given inparamountReview.reason. -
AUTHORIZED- It has been automatically authorized and is considered a valid submission.
Reason
-
OTHER -
VERIFIED -
VALID_DATA -
FLAGGED_FOR_SPOT_CHECK -
DUPLICATE -
INVALID_MERCHANT -
INVALID_DATE -
INSUFFICIENT_DATA -
SUSPICIOUS -
SUSPICIOUS_CONTEXT -
RULE_ENGINE_THREW_ERROR -
INVALID_VENUE -
FORMAT_SUBMISSION_LIMIT_EXCEEDED -
MERCHANT_SUBMISSION_LIMIT_EXCEEDED -
NO_QUALIFYING_PRODUCTS -
INVALID_MULTIPAGE_CLAIM -
TEST
🔐 Multiple authorization modes
Requests to this method require either:
👤 User Authorization
🔒 Admin Authorization with admin:receipts scope
Details are explained above. Non-compliant requests will be rejected.
GET api.receipts.wlloyalty.net/v1/receipts?limit=10&skip=0&sort=createdAt&order=ASC&filter=total:(gt:100)
Responses
Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "success",
"data": [
{
"id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50",
"createdAt": "2017-11-11T06:00:00.000Z",
"updatedAt": "2017-11-11T06:00:00.000Z",
"status": "PENDING",
"notionallyServedAt": "2017-11-11T06:00:00.000Z",
"serviceDate": "2017-11-11",
"serviceTime": "06:00:00",
"ocrConfidence": "0.75",
"total": 110.99,
"subtotal": 110.99,
"correctedTotal": 110.99,
"barcode": "012318432"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "array"
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"name": "InvalidApiKeyError",
"httpCode": 403
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"httpCode": {
"type": "number"
}
}
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"name": "UnauthorizedError",
"httpCode": 401
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"httpCode": {
"type": "number"
}
}
}
}
}List ReceiptsGET/receipts{?limit,skip,sort,order,filter}
Get a list of all receipts which have been claimed by users for your tenant.
🔐 Admin authorization required
Requests to this method must provide an Authorization header containing a valid administrative token with admin:receipts scope. Non-compliant requests will be rejected.
Filtering
It is possible to apply basic filter conditions to the result set using the filter query parameter. This parameter accepts an O-Rison encoded JSON object expressing the set of conditions to be applied.
The general format of this filter object (expressed in JSON) is as follows:
{
"field1": { "operator": "value" },
"field2": { "operator": "value" }
}Where field1 and field2 are field names of this entity, operator is one of [eq, neq, gt, lt, in, has, like], and "value" is the exact value to compare against. The like operator accepts a wild card % which means it will accept any value in place of it e.g %App% will find Web App, the like operator also isn’t case sensitive. The value need not necessarily be a string, the type appropriate for the field should be used. See the O-Rison documentation for help on how to format other types. Dates and datetimes should be passed as ISO 8601 strings.
The same filter encoded as O-Rison would be as follows:
field1:(operator:'value'),field2:(operator:'value')When using the in operator the value should be an array.
Arrays are expressed by enclosing a comma separated list of elements within !().
For example:
field3:(in:!('value1','value2'))URI Parameters
- limit
number(optional) Example: 10The number of items to retrieve.
- skip
number(optional) Example: 0The number of items to skip before selecting.
- sort
string(optional) Example: createdAtThe property to use for sorting.
Choices:
createdAtupdatedAtnotionallyServedAttotalsubtotal- order
string(optional) Example: ASCThe order to sort items.
Choices:
ASCDESC- filter
string(optional) Example: total:(gt:100)O-Rison encoded filter string
Individual Receipt ¶
GET api.receipts.wlloyalty.net/v1/receipts/99afedd5-75de-4833-88cc-a0caf485e354
Responses
Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "success",
"data": {
"id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50",
"status": "PENDING",
"paramountReview": {
"id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50",
"verdict": "ABSTAIN",
"reason": "OTHER",
"createdAt": "2017-11-11T06:00:00.000Z",
"isAutomated": false,
"reviwer": {
"authIssuer": "auth.wlloyalty.net",
"authIdentifier": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50",
"name": "Jane Doe"
},
"comment": null
},
"createdAt": "2017-11-11T06:00:00.000Z",
"updatedAt": "2017-11-11T06:00:00.000Z",
"submitter": {
"authIdentifier": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
},
"ocrConfidence": "0.75",
"total": 110.99,
"subtotal": 110.99,
"barcode": "012318432",
"transactionId": "012318432",
"lineItems": [
{
"quantity": 2,
"description": "Banana",
"identifier": "SKU123",
"unit": "Bunch",
"unitPrice": 1.99,
"totalPrice": 3.98,
"metadata": {
"key": "value"
},
"productId": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
}
],
"pictureUrl": "https://example.com/receiptImage.jpg",
"locationIdentifier": "1235",
"locationAddress": "123 Road Street, Leeds",
"submissionPosition": {
"longitude": 170.9021,
"latitude": 80.9021
},
"formatSlug": "example-format",
"merchantName": "Burger King",
"language": "en",
"timezone": "Europe/London",
"serviceDate": "2017-11-11",
"serviceTime": "06:00:00",
"servedAt": "2017-11-11T06:00:00.000Z",
"metadata": {
"source": "API",
"campaignId": "ExampleCampaign",
"key": "value"
}
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"PENDING",
"AUTHORIZED",
"REJECTED"
]
},
"paramountReview": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string"
},
"verdict": {
"type": "string",
"enum": [
"ABSTAIN",
"REJECT",
"AUTHORIZE"
]
},
"reason": {
"type": "string",
"enum": [
"OTHER",
"VERIFIED",
"VALID_DATA",
"FLAGGED_FOR_SPOT_CHECK",
"DUPLICATE",
"INVALID_MERCHANT",
"INVALID_DATE",
"INSUFFICIENT_DATA",
"SUSPICIOUS",
"SUSPICIOUS_CONTEXT",
"RULE_ENGINE_THREW_ERROR",
"INVALID_VENUE",
"FORMAT_SUBMISSION_LIMIT_EXCEEDED",
"MERCHANT_SUBMISSION_LIMIT_EXCEEDED",
"NO_QUALIFYING_PRODUCTS",
"INVALID_MULTIPAGE_CLAIM",
"TEST"
]
},
"createdAt": {
"type": "string"
},
"isAutomated": {
"type": "boolean"
},
"reviwer": {
"type": [
"object",
"null"
],
"properties": {
"authIssuer": {
"type": "string"
},
"authIdentifier": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"authIssuer",
"authIdentifier"
]
},
"comment": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"verdict",
"reason"
]
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"submitter": {
"type": "object",
"properties": {
"authIdentifier": {
"type": "string"
}
},
"required": [
"authIdentifier"
]
},
"ocrConfidence": {
"type": "string"
},
"total": {
"type": "number"
},
"subtotal": {
"type": "number"
},
"barcode": {
"type": "string"
},
"transactionId": {
"type": "string"
},
"lineItems": {
"type": "array"
},
"pictureUrl": {
"type": "string"
},
"locationIdentifier": {
"type": "string"
},
"locationAddress": {
"type": "string"
},
"submissionPosition": {
"type": "object",
"properties": {
"longitude": {
"type": "number"
},
"latitude": {
"type": "number"
}
},
"required": [
"longitude",
"latitude"
]
},
"formatSlug": {
"type": "string"
},
"merchantName": {
"type": "string"
},
"language": {
"type": "string"
},
"timezone": {
"type": "string"
},
"serviceDate": {
"type": "string"
},
"serviceTime": {
"type": "string"
},
"servedAt": {
"type": "string"
},
"metadata": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"campaignId": {
"type": "string"
},
"key": {
"type": "string"
}
},
"required": [
"source"
]
}
},
"required": [
"id",
"status",
"paramountReview",
"createdAt",
"updatedAt",
"submitter",
"ocrConfidence",
"timezone",
"serviceDate",
"serviceTime",
"servedAt"
]
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"name": "InvalidApiKeyError",
"httpCode": 403
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"httpCode": {
"type": "number"
}
}
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"name": "UnauthorizedError",
"httpCode": 401
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"httpCode": {
"type": "number"
}
}
}
}
}Retrieve a ReceiptGET/receipts/{id}
Retrieve the details of a single receipt.
🔐 Admin authorization required
Requests to this method must provide an Authorization header containing a valid administrative token with admin:receipts scope. Non-compliant requests will be rejected.
URI Parameters
- id
uuid(required) Example: 99afedd5-75de-4833-88cc-a0caf485e354ID of the Receipt to retrieve
Receipt Reviews ¶
POST api.receipts.wlloyalty.net/v1/receipts/99afedd5-75de-4833-88cc-a0caf485e354/reviews
Requests
Headers
Content-Type: application/jsonBody
{
"verdict": "ABSTAIN",
"reason": "OTHER"
}Responses
Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "success",
"data": {
"id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50",
"verdict": "ABSTAIN",
"reason": "OTHER"
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"verdict": {
"type": "string",
"enum": [
"ABSTAIN",
"REJECT",
"AUTHORIZE"
]
},
"reason": {
"type": "string",
"enum": [
"OTHER",
"VERIFIED",
"VALID_DATA",
"FLAGGED_FOR_SPOT_CHECK",
"DUPLICATE",
"INVALID_MERCHANT",
"INVALID_DATE",
"INSUFFICIENT_DATA",
"SUSPICIOUS",
"SUSPICIOUS_CONTEXT",
"RULE_ENGINE_THREW_ERROR",
"INVALID_VENUE",
"FORMAT_SUBMISSION_LIMIT_EXCEEDED",
"MERCHANT_SUBMISSION_LIMIT_EXCEEDED",
"NO_QUALIFYING_PRODUCTS",
"INVALID_MULTIPAGE_CLAIM",
"TEST"
]
}
},
"required": [
"id",
"verdict",
"reason"
]
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"name": "InvalidApiKeyError",
"httpCode": 403
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"httpCode": {
"type": "number"
}
}
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"name": "UnauthorizedError",
"httpCode": 401
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"httpCode": {
"type": "number"
}
}
}
}
}Submit a Receipt ReviewPOST/receipts/{id}/reviews
Submit a new receipt review.
🔐 Admin authorization required
Requests to this method must provide an Authorization header containing a valid administrative token with admin:receipts scope. Non-compliant requests will be rejected.
URI Parameters
- id
uuid(required) Example: 99afedd5-75de-4833-88cc-a0caf485e354ID of the Receipt for which to submit a Review
GET api.receipts.wlloyalty.net/v1/receipts/99afedd5-75de-4833-88cc-a0caf485e354/reviews
Responses
Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "success",
"data": [
{
"id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50",
"verdict": "ABSTAIN",
"reason": "OTHER",
"createdAt": "2017-11-11T06:00:00.000Z",
"isAutomated": true,
"reviwer": {
"authIssuer": "auth.wlloyalty.net",
"authIdentifier": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50",
"name": "Jane Doe"
},
"comment": "Hello, world!"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "array"
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"name": "InvalidApiKeyError",
"httpCode": 403
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"httpCode": {
"type": "number"
}
}
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"name": "UnauthorizedError",
"httpCode": 401
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"httpCode": {
"type": "number"
}
}
}
}
}List Receipt ReviewsGET/receipts/{id}/reviews
List all Reviews for a given Receipt.
🔐 Admin authorization required
Requests to this method must provide an Authorization header containing a valid administrative token with admin:receipts scope. Non-compliant requests will be rejected.
URI Parameters
- id
uuid(required) Example: 99afedd5-75de-4833-88cc-a0caf485e354ID of the Receipt for which to submit a Review
Transactions Rule Engine ¶
Introduction
The White Label Loyalty (WLL) Transactions Rule Engine API enables developers to do advanced post-processing operations after the submission of a Transaction to the WLL platform.
A Transaction can be submitted in the form of a Receipt, an entity from a CSV dump of all orders from a POS system, etc.
Use case:
Each Tenant can have multiple Rule Sets. Each Rule Set consists of a list of Rules, that work together to form a decision tree.
Whenever a Transaction (eg Receipt) is submitted to the WLL system, the Rule Engine is used to do some post-processing checks on the Transaction.
These checks result in JSON data as the final output, which can then be used by the system that invoked the Rule Engine for its own domain specific use-case. (Example, in the Receipt module, the ReceiptReviewer uses the RuleEngine to do some automated checks, uses the result to give an automated Review verdict, and then sends the output as a payload in an Event to the Rewards module.
Basic logic and additional features:
The engine first gets the most appropriate active RuleSet for the incoming Transaction, and then runs all the valid Rules of the set.
-
The core rule engine is a 3rd party library: https://github.com/cachecontrol/json-rules-engine
-
Each Rule has
RulePropertiesfield, which defines the conditions that the Transaction is checked for. -
After the ‘success’ or ‘failure’ of the Rule, the RuleEngine appends the appropriate
ResultParamsdefined for this Rule, into aRuleEngineResponseJSON object. -
Rules can be run parallely or serially, based on the
priorityset. -
Chaining of rules:
Rules can also be chained together by using a key set in a higher order Rule’s
resultParams, as a part of the next Rule’sruleProperties.conditions. -
Custom Rules:
CUSTOMrules are defined directly usingrulePropertieswhich is typed out by the admin manually. This provides a lot of flexibility in the kind of rules that can be added to the systems. -
Pre-defined Rules:
For rules that handle common use-cases, the rule making logic is abstracted away by some pre-defined rules. Eg: BASKET rules are used for product matching checks.
-
Custom Operators:
Additional flexibility for creating more advanced rules is possible, by creating Custom
RuleOperators. Example, thevenueMatchesoperator checks whether a transaction was made in a given venue. -
Special
RuleResultParamskeys:There are two special keys which provide specific functionalities after a Rule is executed:
- `stopRuleEngine` (boolean): After executing a Rule, if the Rule Engine finds that the ResultParams has this key and the value set to true, the Rule Engine first appends the other valid ResultParams of this Rule to the response, and then exits out of execution immediately, without running any other rule of lower priority. NOTE: It may still execute rules of the same priority. - `verdict` (enum): This is a special key, which is used by the ReceiptReviewer to either Reject the receipt or Abstain the receipt. If the rule engine Authorizes or doesn't set the Verdict, the final Review's verdict isn't influenced by the rule engine.
Example of a Custom rule’s RuleProperties:
Refer to https://github.com/cachecontrol/json-rules-engine for more details. For more details regarding parsing the path, refer to https://github.com/s3u/JSONPath
{
conditions: {
all: [
{
any: [
{
fact: "request",
operator: "contains",
value: "9ad8c892-5c08-42c3-a7d8-dcb325d3c1e9",
path: "$.transaction.lineItems[*].productId"
},
{
fact: "request",
operator: "equal", // To handle a single lineitems matching. HACK.
value: "9ad8c892-5c08-42c3-a7d8-dcb325d3c1e9",
path: "$.transaction.lineItems[*].productId"
}
]
},
{
any: [
{
path:
"$.transaction.lineItems[?(@.productId==='9ad8c892-5c08-42c3-a7d8-dcb325d3c1e9')].unitPrice",
fact: "request",
operator: "contains", // To handle an array of lineitems matching.
// NOTE: If any one of the filtered line items matches, the answer is true.
value: 12.2
},
{
path:
"$.transaction.lineItems[?(@.productId==='9ad8c892-5c08-42c3-a7d8-dcb325d3c1e9')].unitPrice",
fact: "request",
operator: "equal", // To handle a single lineitems matching. HACK.
value: 12.2
}
]
}
]
},
event: { type: "prawns-present" },
priority: 10 // IMPORTANT! Set a high priority for this, if you want it to run first
};Rule Sets ¶
POST api.receipts.wlloyalty.net/v1/transactions-rule-engine/rule-sets
Requests
Headers
Content-Type: application/jsonBody
{
"name": "Deeset Rules",
"isActive": true,
"ruleDefinitions": [
{
"type": "CUSTOM",
"name": "prawns-present",
"priority": 10,
"resultParams": {
"success": [
{
"key": "prawnsPresent",
"value": true
}
],
"failure": [
{
"key": "prawnsPresent",
"value": false
}
]
},
"ruleProperties": {
"conditions": {
"all": [
{
"any": [
{
"fact": "request",
"operator": "contains",
"value": "c1417eb1-ff83-4027-a5ae-b5bde2984ef6",
"path": "$.transaction.lineItems[*].productId"
},
{
"fact": "request",
"operator": "equal",
"value": "c1417eb1-ff83-4027-a5ae-b5bde2984ef6",
"path": "$.transaction.lineItems[*].productId"
}
]
},
{
"any": [
{
"path": "$.transaction.lineItems[?(@.productId==='c1417eb1-ff83-4027-a5ae-b5bde2984ef6')].unitPrice",
"fact": "request",
"operator": "contains",
"value": 12.2
},
{
"path": "$.transaction.lineItems[?(@.productId==='c1417eb1-ff83-4027-a5ae-b5bde2984ef6')].unitPrice",
"fact": "request",
"operator": "equal",
"value": 12.2
}
]
}
]
},
"event": {
"type": "prawns-present"
},
"priority": 10
}
}
]
}Responses
Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "success",
"data": {
"tenant": {
"name": "Wehner - Rice",
"slug": "sit-cupiditate-et",
"authentication": {
"issuer": "https://wll-restaurant.eu.auth0.com/",
"jwksUrl": "https://wll-restaurant.eu.auth0.com/.well-known/jwks.json",
"algorithm": "RS256"
},
"key": "9QqcmiHBUs3ydSeca70nU2CdOBUCDmdS71OapD4y",
"eventSecrets": {},
"configuration": {},
"id": "4d72ea9c-9830-41f0-9614-64d9b7ca1c33"
},
"name": "Deeset Rules",
"isActive": true,
"createdAt": "2020-02-10T00:18:09.714Z",
"updatedAt": "2020-02-10T00:18:09.714Z",
"id": "c30a7b53-8c01-41a5-85c6-e3f3fe514677",
"rules": [
{
"name": "prawns-present",
"ruleProperties": {
"conditions": {
"all": [
{
"any": [
{
"fact": "request",
"operator": "contains",
"value": "c1417eb1-ff83-4027-a5ae-b5bde2984ef6",
"path": "$.transaction.lineItems[*].productId"
},
{
"fact": "request",
"operator": "equal",
"value": "c1417eb1-ff83-4027-a5ae-b5bde2984ef6",
"path": "$.transaction.lineItems[*].productId"
}
]
},
{
"any": [
{
"path": "$.transaction.lineItems[?(@.productId==='c1417eb1-ff83-4027-a5ae-b5bde2984ef6')].unitPrice",
"fact": "request",
"operator": "contains",
"value": 12.2
},
{
"path": "$.transaction.lineItems[?(@.productId==='c1417eb1-ff83-4027-a5ae-b5bde2984ef6')].unitPrice",
"fact": "request",
"operator": "equal",
"valuse": 12.2
}
]
}
]
},
"event": {
"type": "prawns-present"
},
"priority": 10
},
"resultParams": {
"success": [
{
"key": "prawnsPresent",
"value": true
}
],
"failure": [
{
"key": "prawnsPresent",
"value": false
}
]
},
"configuration": null,
"createdAt": "2020-02-10T00:18:09.714Z",
"priority": 10,
"updatedAt": "2020-02-10T00:18:09.714Z",
"type": "CUSTOM",
"id": "8bb331ce-548c-4896-9675-40afc300f8ba"
}
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"name": {
"type": "string",
"description": "Optional."
},
"isActive": {
"type": "boolean",
"description": "Required."
},
"rules": {
"type": "array",
"description": "Optional. A Rule Set can be created without any Rules defined at first."
}
},
"required": [
"id",
"createdAt",
"updatedAt",
"isActive"
]
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"name": "InvalidApiKeyError",
"httpCode": 403
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"httpCode": {
"type": "number"
}
}
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"name": "UnauthorizedError",
"httpCode": 401
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"httpCode": {
"type": "number"
}
}
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"httpCode": 400,
"name": "BadRequestError",
"message": "The priority must match the ruleProperties.priority!"
}
}Create a RuleSetPOST/transactions-rule-engine/rule-sets
Create a new rule set. It takes a JSON object containing info about the RuleSet and a collection of Rules in the form of RuleDefinitions.
RuleSetDefinition contains
-
name: (string) - Optional. Example : ‘January Rules’ -
isActive: true (boolean, required) - Required. -
ruleDefinitions(array[RuleDefinition]) - Optional. A Rule Set can be created without any Rules defined at first.
Each RuleDefinition contains:
-
type:CUSTOM,BASKET(enum, required) - Required. Enum used to specificy if this is a custom rule or a predefined one. -
name(string, required) - Required. In case of rule type =CUSTOM, make sure that this is the same asruleProperties.event.type. -
priority(number, required) - Required. In case of rule type =CUSTOM, make sure that this is the same asruleProperties.priority. Rules with higher priority are run first. Rules with the same priority are run parallely. -
ruleProperties(RuleProperties) - Required only forCUSTOMrule types.Where
RulePropertiesconsists of:-
conditions(object, required) - Required. Defines the criteria that the rule engine evaluates the Transaction against. -
event(Event, required) - Defines the event that is fired when the rule is run. Should be the same asrule.name.Where
Eventconsists of:- type (string, required) -
priority(number) - Should be the same asrule.priority.
-
-
configuration(RuleConfiguration) - Required only for predefined rule types, egBASKETtype. This is used to inflate the ruleProperties, internally. Defines the properties of the rule, depending on thetype.BasketRuleConfiguration(RuleConfiguration). Used forBASKETtype of rules, and is used to check for product related business logic.- `productId` (string, required) - Defines the productId to check for the presence of. - `isUnitPriceCheckNeeded` (boolean, required) - `true` if the rule should also check for a matching price. - `overridingUnitPriceToCheckAgainst` (number) - Used in conjunction with `isUnitPriceCheckNeeded`. If provided, the rule engine tries to match against this price. -
resultParams(RuleResultParams, required) - Required. Used to define the fields that get added to the rule engine response, on eithersuccessorfailureresult of the rule.RuleResultParamsis defined as:-
success(array[KeyValuePair], required) - Defines what key values get returned by the Rule Engine when the rule passes. -
failure(array[KeyValuePair], required) - Defines what key values get returned by the Rule Engine when the rule fails.KeyValuePairis defined as:key(string, required) - Name of the key. Example:isPepsiAvailable.value(required) - Can be ofanytype.
-
GET api.receipts.wlloyalty.net/v1/transactions-rule-engine/rule-sets
Responses
Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "success",
"data": [
{
"name": "Deeset Rules",
"isActive": true,
"createdAt": "2020-02-10T02:27:51.084Z",
"updatedAt": "2020-02-10T02:27:51.084Z",
"id": "2375f2e4-20ab-4cba-8b31-8e3a2634734a",
"rules": [
{
"name": "prawns-present",
"ruleProperties": {
"event": {
"type": "prawns-present"
},
"priority": 10,
"conditions": {
"all": [
{
"any": [
{
"fact": "request",
"path": "$.transaction.lineItems[*].productId",
"value": "837eec03-74ff-4758-8cb8-e58ee28c2612",
"operator": "contains"
},
{
"fact": "request",
"path": "$.transaction.lineItems[*].productId",
"value": "837eec03-74ff-4758-8cb8-e58ee28c2612",
"operator": "equal"
}
]
},
{
"any": [
{
"fact": "request",
"path": "$.transaction.lineItems[?(@.productId==='837eec03-74ff-4758-8cb8-e58ee28c2612')].unitPrice",
"value": 12.2,
"operator": "contains"
},
{
"fact": "request",
"path": "$.transaction.lineItems[?(@.productId==='837eec03-74ff-4758-8cb8-e58ee28c2612')].unitPrice",
"value": 12.2,
"operator": "equal"
}
]
}
]
}
},
"resultParams": {
"failure": [
{
"key": "prawnsPresent",
"value": false
},
{
"key": "verdict",
"value": "FAIL"
}
],
"success": [
{
"key": "prawnsPresent",
"value": true
},
{
"key": "verdict",
"value": "SUCCESS"
}
]
},
"configuration": null,
"createdAt": "2020-02-10T02:27:58.072Z",
"priority": 10,
"updatedAt": "2020-02-10T02:27:58.072Z",
"type": "CUSTOM",
"id": "211d230e-66bf-49a1-90ea-8cb70ab5232c"
},
{
"name": "pepsi-present",
"ruleProperties": {
"event": {
"type": "pepsi-present"
},
"priority": 9,
"conditions": {
"all": [
{
"any": [
{
"fact": "request",
"path": "$.transaction.lineItems[*].productId",
"value": "c94074f6-42e2-413a-a803-edff365b1b62",
"operator": "contains"
},
{
"fact": "request",
"path": "$.transaction.lineItems[*].productId",
"value": "c94074f6-42e2-413a-a803-edff365b1b62",
"operator": "equal"
}
]
},
{
"any": [
{
"fact": "request",
"path": "$.transaction.lineItems[?(@.productId==='c94074f6-42e2-413a-a803-edff365b1b62')].unitPrice",
"value": 10.2,
"operator": "contains"
},
{
"fact": "request",
"path": "$.transaction.lineItems[?(@.productId==='c94074f6-42e2-413a-a803-edff365b1b62')].unitPrice",
"value": 10.2,
"operator": "equal"
}
]
}
]
}
},
"resultParams": {
"failure": [
{
"key": "pepsiPresent",
"value": false
}
],
"success": [
{
"key": "pepsiPresent",
"value": true
}
]
},
"configuration": {
"productId": "c94074f6-42e2-413a-a803-edff365b1b62",
"isUnitPriceCheckNeeded": true,
"overridingUnitPriceToCheckAgainst": 10.2
},
"createdAt": "2020-02-10T02:27:58.072Z",
"priority": 9,
"updatedAt": "2020-02-10T02:27:58.072Z",
"type": "BASKET",
"id": "65f5d7f8-20d0-4714-8f32-155c4b07c281"
},
{
"name": "venue-is-corn-exchange",
"ruleProperties": {
"event": {
"type": "venue-is-corn-exchange"
},
"priority": 5,
"conditions": {
"all": [
{
"fact": "request",
"value": "bfc3b90e-c05a-487c-ab70-03ff9ea0caaf",
"operator": "venueMatches"
}
]
}
},
"resultParams": {
"failure": [
{
"key": "verdict",
"value": "REJECT"
},
{
"key": "stopRuleEngine",
"value": true
},
{
"key": "inCornExchange",
"value": false
}
],
"success": [
{
"key": "verdict",
"value": "ABSTAIN"
},
{
"key": "stopRuleEngine",
"value": false
},
{
"key": "inCornExchange",
"value": true
}
]
},
"configuration": null,
"createdAt": "2020-02-10T02:27:58.072Z",
"priority": 5,
"updatedAt": "2020-02-10T02:27:58.072Z",
"type": "CUSTOM",
"id": "f04fc511-7025-4bb8-81d7-cc0bd39f5b2e"
},
{
"name": "final-check",
"ruleProperties": {
"event": {
"type": "final-check"
},
"priority": 4,
"conditions": {
"all": [
{
"fact": "inCornExchange",
"value": true,
"operator": "equal"
},
{
"fact": "pepsiPresent",
"value": true,
"operator": "equal"
},
{
"fact": "prawnsPresent",
"value": true,
"operator": "equal"
}
]
}
},
"resultParams": {
"failure": [
{
"key": "finalCheckPass",
"value": false
}
],
"success": [
{
"key": "finalCheckPass",
"value": true
}
]
},
"configuration": null,
"createdAt": "2020-02-10T02:27:58.072Z",
"priority": 4,
"updatedAt": "2020-02-10T02:27:58.072Z",
"type": "CUSTOM",
"id": "fff1318b-7ba5-4948-8d93-a1f0c922c748"
}
]
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "array"
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"name": "InvalidApiKeyError",
"httpCode": 403
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"httpCode": {
"type": "number"
}
}
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"name": "UnauthorizedError",
"httpCode": 401
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"httpCode": {
"type": "number"
}
}
}
}
}List RuleSetsGET/transactions-rule-engine/rule-sets
It returns a list of all RuleSets for the given Tenant, each with a collection of Rules.
RuleSet contains
-
id:
8d68cb91-202a-4c62-a867-asd(required) -
name: (string) - Optional. Example : ‘January Rules’ -
isActive: true (boolean, required) - Required. -
rules(array[Rule]) - Optional. A Rule Set can be created without any Rules defined at first.
Each Rule contains:
-
type:CUSTOM,BASKET(enum, required) - Required. Enum used to specificy if this is a custom rule or a predefined one. -
name(string, required) - Required. In case of rule type =CUSTOM, make sure that this is the same asruleProperties.event.type. -
priority(number, required) - Required. Rules with higher priority are run first. Rules with the same priority are run parallely. -
ruleProperties(RuleProperties, required) - Required for all rule types, since even predefined rules’ configurations are inflated to createRulePropertiesWhere
RulePropertiesconsists of:-
conditions(object, required) - Required. Defines the criteria that the rule engine evaluates the Transaction against. -
event(Event, required) - Defines the event that is fired when the rule is run. Should be the same asrule.name.Where
Eventconsists of:- type (string, required) -
priority(number) - Should be the same asrule.priority.
-
-
configuration(RuleConfiguration) - Required only for predefined rule types, egBASKETtype. This is used to inflate the ruleProperties, internally. Defines the properties of the rule, depending on thetype.BasketRuleConfiguration(RuleConfiguration). Used forBASKETtype of rules, and is used to check for product related business logic.- `productId` (string, required) - Defines the productId to check for the presence of. - `isUnitPriceCheckNeeded` (boolean, required) - `true` if the rule should also check for a matching price. - `overridingUnitPriceToCheckAgainst` (number) - Used in conjunction with `isUnitPriceCheckNeeded`. If provided, the rule engine tries to match against this price. -
resultParams(RuleResultParams, required) - Required. Used to define the fields that get added to the rule engine response, on eithersuccessorfailureresult of the rule.RuleResultParamsis defined as:-
success(array[KeyValuePair], required) - Defines what key values get returned by the Rule Engine when the rule passes. -
failure(array[KeyValuePair], required) - Defines what key values get returned by the Rule Engine when the rule fails.KeyValuePairis defined as:key(string, required) - Name of the key. Example:isPepsiAvailable.value(required) - Can be ofanytype.
-
Individual Rule Set ¶
GET api.receipts.wlloyalty.net/v1/transactions-rule-engine/rule-sets/8d68cb91-202a-4c62-a867-8f9a8a1e2f50
Responses
Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "success",
"data": {
"name": "Deeset Rules",
"isActive": true,
"createdAt": "2020-02-10T02:27:51.084Z",
"updatedAt": "2020-02-10T02:27:51.084Z",
"id": "2375f2e4-20ab-4cba-8b31-8e3a2634734a",
"rules": [
{
"name": "prawns-present",
"ruleProperties": {
"event": {
"type": "prawns-present"
},
"priority": 10,
"conditions": {
"all": [
{
"any": [
{
"fact": "request",
"path": "$.transaction.lineItems[*].productId",
"value": "837eec03-74ff-4758-8cb8-e58ee28c2612",
"operator": "contains"
},
{
"fact": "request",
"path": "$.transaction.lineItems[*].productId",
"value": "837eec03-74ff-4758-8cb8-e58ee28c2612",
"operator": "equal"
}
]
},
{
"any": [
{
"fact": "request",
"path": "$.transaction.lineItems[?(@.productId==='837eec03-74ff-4758-8cb8-e58ee28c2612')].unitPrice",
"value": 12.2,
"operator": "contains"
},
{
"fact": "request",
"path": "$.transaction.lineItems[?(@.productId==='837eec03-74ff-4758-8cb8-e58ee28c2612')].unitPrice",
"value": 12.2,
"operator": "equal"
}
]
}
]
}
},
"resultParams": {
"failure": [
{
"key": "prawnsPresent",
"value": false
},
{
"key": "verdict",
"value": "FAIL"
}
],
"success": [
{
"key": "prawnsPresent",
"value": true
},
{
"key": "verdict",
"value": "SUCCESS"
}
]
},
"configuration": null,
"createdAt": "2020-02-10T02:27:58.072Z",
"priority": 10,
"updatedAt": "2020-02-10T02:27:58.072Z",
"type": "CUSTOM",
"id": "211d230e-66bf-49a1-90ea-8cb70ab5232c"
},
{
"name": "pepsi-present",
"ruleProperties": {
"event": {
"type": "pepsi-present"
},
"priority": 9,
"conditions": {
"all": [
{
"any": [
{
"fact": "request",
"path": "$.transaction.lineItems[*].productId",
"value": "c94074f6-42e2-413a-a803-edff365b1b62",
"operator": "contains"
},
{
"fact": "request",
"path": "$.transaction.lineItems[*].productId",
"value": "c94074f6-42e2-413a-a803-edff365b1b62",
"operator": "equal"
}
]
},
{
"any": [
{
"fact": "request",
"path": "$.transaction.lineItems[?(@.productId==='c94074f6-42e2-413a-a803-edff365b1b62')].unitPrice",
"value": 10.2,
"operator": "contains"
},
{
"fact": "request",
"path": "$.transaction.lineItems[?(@.productId==='c94074f6-42e2-413a-a803-edff365b1b62')].unitPrice",
"value": 10.2,
"operator": "equal"
}
]
}
]
}
},
"resultParams": {
"failure": [
{
"key": "pepsiPresent",
"value": false
}
],
"success": [
{
"key": "pepsiPresent",
"value": true
}
]
},
"configuration": {
"productId": "c94074f6-42e2-413a-a803-edff365b1b62",
"isUnitPriceCheckNeeded": true,
"overridingUnitPriceToCheckAgainst": 10.2
},
"createdAt": "2020-02-10T02:27:58.072Z",
"priority": 9,
"updatedAt": "2020-02-10T02:27:58.072Z",
"type": "BASKET",
"id": "65f5d7f8-20d0-4714-8f32-155c4b07c281"
},
{
"name": "venue-is-corn-exchange",
"ruleProperties": {
"event": {
"type": "venue-is-corn-exchange"
},
"priority": 5,
"conditions": {
"all": [
{
"fact": "request",
"value": "bfc3b90e-c05a-487c-ab70-03ff9ea0caaf",
"operator": "venueMatches"
}
]
}
},
"resultParams": {
"failure": [
{
"key": "verdict",
"value": "REJECT"
},
{
"key": "stopRuleEngine",
"value": true
},
{
"key": "inCornExchange",
"value": false
}
],
"success": [
{
"key": "verdict",
"value": "ABSTAIN"
},
{
"key": "stopRuleEngine",
"value": false
},
{
"key": "inCornExchange",
"value": true
}
]
},
"configuration": null,
"createdAt": "2020-02-10T02:27:58.072Z",
"priority": 5,
"updatedAt": "2020-02-10T02:27:58.072Z",
"type": "CUSTOM",
"id": "f04fc511-7025-4bb8-81d7-cc0bd39f5b2e"
},
{
"name": "final-check",
"ruleProperties": {
"event": {
"type": "final-check"
},
"priority": 4,
"conditions": {
"all": [
{
"fact": "inCornExchange",
"value": true,
"operator": "equal"
},
{
"fact": "pepsiPresent",
"value": true,
"operator": "equal"
},
{
"fact": "prawnsPresent",
"value": true,
"operator": "equal"
}
]
}
},
"resultParams": {
"failure": [
{
"key": "finalCheckPass",
"value": false
}
],
"success": [
{
"key": "finalCheckPass",
"value": true
}
]
},
"configuration": null,
"createdAt": "2020-02-10T02:27:58.072Z",
"priority": 4,
"updatedAt": "2020-02-10T02:27:58.072Z",
"type": "CUSTOM",
"id": "fff1318b-7ba5-4948-8d93-a1f0c922c748"
}
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"name": {
"type": "string",
"description": "Optional."
},
"isActive": {
"type": "boolean",
"description": "Required."
},
"rules": {
"type": "array",
"description": "Optional. A Rule Set can be created without any Rules defined at first."
}
},
"required": [
"id",
"createdAt",
"updatedAt",
"isActive"
]
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"name": "InvalidApiKeyError",
"httpCode": 403
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"httpCode": {
"type": "number"
}
}
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"name": "UnauthorizedError",
"httpCode": 401
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"httpCode": {
"type": "number"
}
}
}
}
}Retrieve a Rule SetGET/transactions-rule-engine/rule-sets/{id}
Retrieve the details of a single rule set. The data schema returned is similar to the GET list of RuleSets API, expect this returns a single object.
URI Parameters
- id
uuid(required) Example: 8d68cb91-202a-4c62-a867-8f9a8a1e2f50ID of the Rule Set to retrieve
PATCH api.receipts.wlloyalty.net/v1/transactions-rule-engine/rule-sets/8d68cb91-202a-4c62-a867-8f9a8a1e2f50
Requests
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_tokenBody
{
"ruleDefinitions": [
{
"name": "prawns-present",
"priority": 10,
"ruleProperties": {
"event": {
"type": "prawns-present"
},
"priority": 10,
"conditions": {
"all": [
{
"any": [
{
"fact": "request",
"path": "$.transaction.lineItems[*].productId",
"value": "837eec03-74ff-4758-8cb8-e58ee28c2612",
"operator": "contains"
},
{
"fact": "request",
"path": "$.transaction.lineItems[*].productId",
"value": "837eec03-74ff-4758-8cb8-e58ee28c2612",
"operator": "equal"
}
]
},
{
"any": [
{
"fact": "request",
"path": "$.transaction.lineItems[?(@.productId==='837eec03-74ff-4758-8cb8-e58ee28c2612')].unitPrice",
"value": 12.2,
"operator": "contains"
},
{
"fact": "request",
"path": "$.transaction.lineItems[?(@.productId==='837eec03-74ff-4758-8cb8-e58ee28c2612')].unitPrice",
"value": 12.2,
"operator": "equal"
}
]
}
]
}
},
"resultParams": {
"failure": [
{
"key": "prawnsPresent",
"value": false
},
{
"key": "verdict",
"value": "FAIL"
}
],
"success": [
{
"key": "prawnsPresent",
"value": true
},
{
"key": "verdict",
"value": "SUCCESS"
}
]
},
"type": "CUSTOM"
},
{
"name": "pepsi-present",
"resultParams": {
"failure": [
{
"key": "pepsiPresent",
"value": false
}
],
"success": [
{
"key": "pepsiPresent",
"value": true
}
]
},
"configuration": {
"productId": "c94074f6-42e2-413a-a803-edff365b1b62",
"isUnitPriceCheckNeeded": true,
"overridingUnitPriceToCheckAgainst": 10.2
},
"priority": 9,
"type": "BASKET"
},
{
"name": "venue-is-corn-exchange",
"priority": 5,
"ruleProperties": {
"conditions": {
"all": [
{
"operator": "venueMatches",
"value": "bfc3b90e-c05a-487c-ab70-03ff9ea0caaf",
"fact": "request"
}
]
},
"event": {
"type": "venue-is-corn-exchange"
},
"priority": 5
},
"resultParams": {
"failure": [
{
"key": "verdict",
"value": "REJECT"
},
{
"key": "stopRuleEngine",
"value": true
},
{
"key": "inCornExchange",
"value": false
}
],
"success": [
{
"key": "verdict",
"value": "ABSTAIN"
},
{
"key": "stopRuleEngine",
"value": false
},
{
"key": "inCornExchange",
"value": true
}
]
},
"type": "CUSTOM"
},
{
"name": "final-check",
"ruleProperties": {
"conditions": {
"all": [
{
"operator": "equal",
"value": true,
"fact": "inCornExchange"
},
{
"operator": "equal",
"value": true,
"fact": "pepsiPresent"
},
{
"operator": "equal",
"value": true,
"fact": "prawnsPresent"
}
]
},
"event": {
"type": "final-check"
},
"priority": 4
},
"priority": 4,
"resultParams": {
"failure": [
{
"key": "finalCheckPass",
"value": false
}
],
"success": [
{
"key": "finalCheckPass",
"value": true
}
]
},
"type": "CUSTOM"
}
]
}Responses
Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "success",
"data": {
"name": "Deeset Rules",
"isActive": true,
"createdAt": "2020-02-10T02:27:51.084Z",
"updatedAt": "2020-02-10T02:27:51.084Z",
"id": "2375f2e4-20ab-4cba-8b31-8e3a2634734a",
"rules": [
{
"name": "prawns-present",
"ruleProperties": {
"event": {
"type": "prawns-present"
},
"priority": 10,
"conditions": {
"all": [
{
"any": [
{
"fact": "request",
"path": "$.transaction.lineItems[*].productId",
"value": "837eec03-74ff-4758-8cb8-e58ee28c2612",
"operator": "contains"
},
{
"fact": "request",
"path": "$.transaction.lineItems[*].productId",
"value": "837eec03-74ff-4758-8cb8-e58ee28c2612",
"operator": "equal"
}
]
},
{
"any": [
{
"fact": "request",
"path": "$.transaction.lineItems[?(@.productId==='837eec03-74ff-4758-8cb8-e58ee28c2612')].unitPrice",
"value": 12.2,
"operator": "contains"
},
{
"fact": "request",
"path": "$.transaction.lineItems[?(@.productId==='837eec03-74ff-4758-8cb8-e58ee28c2612')].unitPrice",
"value": 12.2,
"operator": "equal"
}
]
}
]
}
},
"resultParams": {
"success": [
{
"key": "prawnsPresent",
"value": true
},
{
"key": "verdict",
"value": "SUCCESS"
}
],
"failure": [
{
"key": "prawnsPresent",
"value": false
},
{
"key": "verdict",
"value": "FAIL"
}
]
},
"configuration": null,
"createdAt": "2020-02-10T02:27:58.072Z",
"priority": 10,
"updatedAt": "2020-02-10T02:27:58.072Z",
"type": "CUSTOM",
"id": "211d230e-66bf-49a1-90ea-8cb70ab5232c"
},
{
"name": "pepsi-present",
"ruleProperties": {
"conditions": {
"all": [
{
"any": [
{
"fact": "request",
"operator": "contains",
"value": "c94074f6-42e2-413a-a803-edff365b1b62",
"path": "$.transaction.lineItems[*].productId"
},
{
"fact": "request",
"operator": "equal",
"value": "c94074f6-42e2-413a-a803-edff365b1b62",
"path": "$.transaction.lineItems[*].productId"
}
]
},
{
"any": [
{
"path": "$.transaction.lineItems[?(@.productId==='c94074f6-42e2-413a-a803-edff365b1b62')].unitPrice",
"fact": "request",
"operator": "contains",
"value": 10.2
},
{
"path": "$.transaction.lineItems[?(@.productId==='c94074f6-42e2-413a-a803-edff365b1b62')].unitPrice",
"fact": "request",
"operator": "equal",
"value": 10.2
}
]
}
]
},
"event": {
"type": "pepsi-present"
},
"priority": 9
},
"resultParams": {
"success": [
{
"key": "pepsiPresent",
"value": true
}
],
"failure": [
{
"key": "pepsiPresent",
"value": false
}
]
},
"configuration": {
"productId": "c94074f6-42e2-413a-a803-edff365b1b62",
"isUnitPriceCheckNeeded": true,
"overridingUnitPriceToCheckAgainst": 10.2
},
"createdAt": "2020-02-10T02:27:58.072Z",
"priority": 9,
"updatedAt": "2020-02-10T02:27:58.072Z",
"type": "BASKET",
"id": "65f5d7f8-20d0-4714-8f32-155c4b07c281"
},
{
"name": "venue-is-corn-exchange",
"ruleProperties": {
"conditions": {
"all": [
{
"operator": "venueMatches",
"value": "bfc3b90e-c05a-487c-ab70-03ff9ea0caaf",
"fact": "request"
}
]
},
"event": {
"type": "venue-is-corn-exchange"
},
"priority": 5
},
"resultParams": {
"success": [
{
"key": "verdict",
"value": "ABSTAIN"
},
{
"key": "stopRuleEngine",
"value": false
},
{
"key": "inCornExchange",
"value": true
}
],
"failure": [
{
"key": "verdict",
"value": "REJECT"
},
{
"key": "stopRuleEngine",
"value": true
},
{
"key": "inCornExchange",
"value": false
}
]
},
"configuration": null,
"createdAt": "2020-02-10T02:27:58.072Z",
"priority": 5,
"updatedAt": "2020-02-10T02:27:58.072Z",
"type": "CUSTOM",
"id": "f04fc511-7025-4bb8-81d7-cc0bd39f5b2e"
},
{
"name": "final-check",
"ruleProperties": {
"conditions": {
"all": [
{
"operator": "equal",
"value": true,
"fact": "inCornExchange"
},
{
"operator": "equal",
"value": true,
"fact": "pepsiPresent"
},
{
"operator": "equal",
"value": true,
"fact": "prawnsPresent"
}
]
},
"event": {
"type": "final-check"
},
"priority": 4
},
"resultParams": {
"success": [
{
"key": "finalCheckPass",
"value": true
}
],
"failure": [
{
"key": "finalCheckPass",
"value": false
}
]
},
"configuration": null,
"createdAt": "2020-02-10T02:27:58.072Z",
"priority": 4,
"updatedAt": "2020-02-10T02:27:58.072Z",
"type": "CUSTOM",
"id": "fff1318b-7ba5-4948-8d93-a1f0c922c748"
}
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"name": {
"type": "string",
"description": "Optional."
},
"isActive": {
"type": "boolean",
"description": "Required."
},
"rules": {
"type": "array",
"description": "Optional. A Rule Set can be created without any Rules defined at first."
}
},
"required": [
"id",
"createdAt",
"updatedAt",
"isActive"
]
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"name": "InvalidApiKeyError",
"httpCode": 403
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"httpCode": {
"type": "number"
}
}
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"name": "UnauthorizedError",
"httpCode": 401
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"httpCode": {
"type": "number"
}
}
}
}
}Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "fail",
"data": {
"httpCode": 400,
"name": "BadRequestError",
"message": "The priority must match the ruleProperties.priority!"
}
}Update a Rule SetPATCH/transactions-rule-engine/rule-sets/{id}
Update the details of a single Rule Set. Also used to update the just a single Rule contained in the Rule Set.
NOTE
In order to update even a single Rule in a Rule Set, the entire Rules array needs to be send again (in the form of RuleDefinitions array), after the change has been handled at the API caller side.
This API replaces the entire Rules array everytime it is called.
URI Parameters
- id
uuid(required) Example: 8d68cb91-202a-4c62-a867-8f9a8a1e2f50ID of the Tier to update.
Orders ¶
Our orders API allows you to create and manage orders for your users. Orders can be linked to products using our products module in order to track transactions across multiple SKU’s that are related to the same product.
This is useful where an e-commerce or POS system can directly invoke WLL’s order creation APIs via an integration. More manual ‘order’ creation requires the end-user to upload a receipt. This is where the WLL receipt system is more useful.
Orders Collection ¶
GET api.receipts.wlloyalty.net/v1/orders
Requests
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_tokenResponses
Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "success",
"data": [
{
"id": "8d68cb91-202a-4c62-a867-asd",
"type": "ORDER",
"createdAt": "2025-01-11T06:00:00.000Z",
"updatedAt": "2025-01-11T06:00:00.000Z",
"serviceDate": "2025-01-09",
"serviceTime": "06:00:00",
"total": 110.99,
"subtotal": 110.99,
"totalTax": 20.99,
"transactionId": "012318432",
"lineItems": [
{
"quantity": 2,
"description": "Banana",
"identifier": "SKU123",
"unit": "Bunch",
"unitPrice": 1.99,
"totalPrice": 3.98,
"metadata": {
"key": "value"
},
"productId": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
}
],
"locationIdentifier": "1235",
"locationAddress": "123 Road Street, Leeds",
"submissionPosition": {
"longitude": 170.9021,
"latitude": 80.9021
},
"metadata": {
"source": "API",
"campaignId": "ExampleCampaign",
"key": "value"
},
"paymentTenders": [
{
"type": "CASH",
"id": "8d68cb91-202a-4c62-a867-asd",
"value": 110.99
}
],
"status": "AUTHORIZED"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "array"
}
}
}List OrdersGET/orders
Get a list of all orders which have been created for your tenant.
👤 Admin authorization required
🔒 Admin Authorization with admin:receipts scope
GET api.receipts.wlloyalty.net/v1/orders/9cb2cc08-e033-4200-86a7-95a03ba09462
Requests
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_tokenResponses
Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "success",
"data": {
"id": "8d68cb91-202a-4c62-a867-asd",
"type": "ORDER",
"createdAt": "2025-01-11T06:00:00.000Z",
"updatedAt": "2025-01-11T06:00:00.000Z",
"serviceDate": "2025-01-09",
"serviceTime": "06:00:00",
"total": 110.99,
"subtotal": 110.99,
"totalTax": 20.99,
"transactionId": "012318432",
"lineItems": [
{
"quantity": 2,
"description": "Banana",
"identifier": "SKU123",
"unit": "Bunch",
"unitPrice": 1.99,
"totalPrice": 3.98,
"metadata": {
"key": "value"
},
"productId": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
}
],
"locationIdentifier": "1235",
"locationAddress": "123 Road Street, Leeds",
"submissionPosition": {
"longitude": 170.9021,
"latitude": 80.9021
},
"metadata": {
"source": "API",
"campaignId": "ExampleCampaign",
"key": "value"
},
"paymentTenders": [
{
"type": "CASH",
"id": "8d68cb91-202a-4c62-a867-asd",
"value": 110.99
}
],
"status": "AUTHORIZED"
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"ORDER",
"RECEIPT",
"ORDER"
]
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"serviceDate": {
"type": "string"
},
"serviceTime": {
"type": "string"
},
"total": {
"type": "number"
},
"subtotal": {
"type": "number"
},
"totalTax": {
"type": "number"
},
"transactionId": {
"type": "string"
},
"lineItems": {
"type": "array"
},
"locationIdentifier": {
"type": "string"
},
"locationAddress": {
"type": "string"
},
"submissionPosition": {
"type": "object",
"properties": {
"longitude": {
"type": "number"
},
"latitude": {
"type": "number"
}
},
"required": [
"longitude",
"latitude"
]
},
"metadata": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"campaignId": {
"type": "string"
},
"key": {
"type": "string"
}
},
"required": [
"source"
]
},
"paymentTenders": {
"type": "array"
},
"status": {
"type": "string",
"enum": [
"AUTHORIZED"
]
}
},
"required": [
"id",
"type",
"createdAt",
"updatedAt",
"serviceDate",
"serviceTime"
]
}
}
}Get OrderGET/orders/{id}
Get a specific order by its ID.
👤 Admin authorization required
🔒 Admin Authorization with admin:receipts scope
URI Parameters
- id
uuid(required) Example: 9cb2cc08-e033-4200-86a7-95a03ba09462ID of the order.
POST api.receipts.wlloyalty.net/v1/orders
Requests
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_tokenBody
{
"submitter": {
"authIdentifier": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
},
"serviceDate": "2025-01-09",
"serviceTime": "06:00:00",
"lineItems": [
{
"quantity": 2,
"description": "Banana",
"identifier": "SKU123",
"unit": "Bunch",
"unitPrice": 1.99,
"totalPrice": 3.98,
"metadata": {
"key": "value"
}
}
],
"paymentTenders": [
{
"type": "CASH",
"id": "8d68cb91-202a-4c62-a867-asd",
"value": 110.99
}
],
"subtotal": 1000.99,
"total": 1234.99,
"totalTax": 20.99,
"transactionId": "012318432",
"locationIdentifier": "1235",
"locationAddress": "123 Road Street, Leeds",
"submissionPosition": {
"longitude": 170.9021,
"latitude": 80.9021
},
"metadata": {
"source": "API",
"campaignId": "ExampleCampaign",
"key": "value"
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"submitter": {
"type": "object",
"properties": {
"authIdentifier": {
"type": "string"
}
},
"required": [
"authIdentifier"
]
},
"serviceDate": {
"type": "string"
},
"serviceTime": {
"type": "string"
},
"lineItems": {
"type": "array"
},
"paymentTenders": {
"type": "array"
},
"subtotal": {
"type": "number"
},
"total": {
"type": "number"
},
"totalTax": {
"type": "number"
},
"transactionId": {
"type": "string"
},
"locationIdentifier": {
"type": "string"
},
"locationAddress": {
"type": "string"
},
"submissionPosition": {
"type": "object",
"properties": {
"longitude": {
"type": "number"
},
"latitude": {
"type": "number"
}
},
"required": [
"longitude",
"latitude"
]
},
"metadata": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"campaignId": {
"type": "string"
},
"key": {
"type": "string"
}
},
"required": [
"source"
]
}
},
"required": [
"serviceDate",
"serviceTime",
"lineItems"
]
}Responses
Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "success",
"data": {
"id": "8d68cb91-202a-4c62-a867-asd",
"type": "ORDER",
"createdAt": "2025-01-11T06:00:00.000Z",
"updatedAt": "2025-01-11T06:00:00.000Z",
"serviceDate": "2025-01-09",
"serviceTime": "06:00:00",
"total": 110.99,
"subtotal": 110.99,
"totalTax": 20.99,
"transactionId": "012318432",
"lineItems": [
{
"quantity": 2,
"description": "Banana",
"identifier": "SKU123",
"unit": "Bunch",
"unitPrice": 1.99,
"totalPrice": 3.98,
"metadata": {
"key": "value"
},
"productId": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
}
],
"locationIdentifier": "1235",
"locationAddress": "123 Road Street, Leeds",
"submissionPosition": {
"longitude": 170.9021,
"latitude": 80.9021
},
"metadata": {
"source": "API",
"campaignId": "ExampleCampaign",
"key": "value"
},
"paymentTenders": [
{
"type": "CASH",
"id": "8d68cb91-202a-4c62-a867-asd",
"value": 110.99
}
],
"status": "AUTHORIZED"
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"ORDER",
"RECEIPT",
"ORDER"
]
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"serviceDate": {
"type": "string"
},
"serviceTime": {
"type": "string"
},
"total": {
"type": "number"
},
"subtotal": {
"type": "number"
},
"totalTax": {
"type": "number"
},
"transactionId": {
"type": "string"
},
"lineItems": {
"type": "array"
},
"locationIdentifier": {
"type": "string"
},
"locationAddress": {
"type": "string"
},
"submissionPosition": {
"type": "object",
"properties": {
"longitude": {
"type": "number"
},
"latitude": {
"type": "number"
}
},
"required": [
"longitude",
"latitude"
]
},
"metadata": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"campaignId": {
"type": "string"
},
"key": {
"type": "string"
}
},
"required": [
"source"
]
},
"paymentTenders": {
"type": "array"
},
"status": {
"type": "string",
"enum": [
"AUTHORIZED"
]
}
},
"required": [
"id",
"type",
"createdAt",
"updatedAt",
"serviceDate",
"serviceTime"
]
}
}
}Create OrderPOST/orders
👤 Admin authorization required
🔒 Admin Authorization with admin:receipts scope
For general cases, prefer the POST /orders API. POST /orders/asyncly can be used for specific use-cases.
OrderDefinition contains
-
submitter: (object,Submitter) - Required for Admin Authorization.Here
Submitterobject consists of:authIdentifier: (string, required) The authIdentifier of the user, ideally a user that already exists in WLL user system. It’s the API invoker’s responsibility to ensure this matches an existing WLL user’s authIdentifier. Otherwise, the receipts/order system creates a ‘shell’ user without a link to WLL users.
-
serviceDate:"2025-12-31"(string, optional) - ISO 8601 date format in local timezone. Denotes the local date when the order was created/user was served. Ensure that the WLL tenant in receipts system is configured with the timezone. Default to UTC timezone without the configuration. -
serviceTime:"06:00:00"(string, optional) - ISO 8601 time format in local timezone. Denotes the local time when the order was created/user was served. Ensure that the WLL tenant in receipts system is configured with the timezone. Default to UTC timezone without the configuration. -
lineItems(array[LineItemDefinition], required) - Where each line item is of the type:LineItemDefinitionquantity:2(number, required)description:"Banana"(string, required). Useful for finding matches in WLL’sProductsystemidentifier:"SKU123"(string, optional). Typically Barcode ID or a unique SKU. Useful for finding matches in WLL’sProductsystem.unit:"Bunch"(string, optional)unitPrice:1.99(number, optional)totalPrice:3.98(number, optional)metadata(object, optional). Optional key-value pairs, useful as metadata for the line item. This is propagated in the ORDER_PLACED event if used along with WLL’s reward system and can be used for setting up reactions. Eg, this can be used to signify a deep discount or an offer applied on the line item.- key:
value(string, optional) Eg:{ "deepDiscount" true, "overriddenPrice": true}
- key:
-
paymentTenders(array[PaymentTender], optional). Used to add a list of payment methods used. Where each payment tender is:PaymentTender- type :
CASH(string, required) - Type of payment tender (e.gCASH,CARD, etc.). Not an enum. - id:
8d68cb91-202a-4c62-a867-asd(string, optional). For tenant’s internal reference, useful for non-CASH type. - value:
110.99(number, required)
- type :
-
subtotal:1000.99(number, optional) -
total:1234.99(number, optional) -
totalTax:20.99(number, optional) -
transactionId:"012318432A"(string, optional). Highly recommended. Used for deduplication (along with submitter Id) over a 5 minute window when using CREATE orders/asyncly API. Can be a tenant specific unique transaction/orderId (eg generated via POS). -
locationIdentifier:"1235"(string, optional). Optional, but recommended. Tenant’s internal store/venue ID, which can also be used to createvenuesin WLL venue system. NOTE: Can be useful for analytics, but isn’t auto-linked to WLL venues (yet). -
locationAddress:"123 Road Street, Leeds"(string, optional). Not really needed if locationIdentifier is used. -
submissionPosition(GeoPoint, optional). Not really needed if locationIdentifier is used. -
metadata(object,ReceiptMetadata, optional). Used for metadata at Order level (vs LineItemMetadata above). A key-value pair of metadata.Example key-value pairs in
ReceiptMetadata- source:
"API"(enum, required) [APP,WEB,API,EMAIL,OTHER]. “API” is the most appropriate for most cases. - campaignId:
"JulyCampaign2"(string, optional). For specific marketing use-cases. Not really needed for orders. - anyKey: anyValue (string, boolean, number) (Eg, cashierId: 1001). Can be used for analytics. Also passed down to ORDER_PLACED event if WLL rewards system is used.
- source:
POST api.receipts.wlloyalty.net/v1/orders/asyncly
Requests
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_tokenBody
{
"submitter": {
"authIdentifier": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
},
"serviceDate": "2025-01-09",
"serviceTime": "06:00:00",
"lineItems": [
{
"quantity": 2,
"description": "Banana",
"identifier": "SKU123",
"unit": "Bunch",
"unitPrice": 1.99,
"totalPrice": 3.98,
"metadata": {
"key": "value"
}
}
],
"paymentTenders": [
{
"type": "CASH",
"id": "8d68cb91-202a-4c62-a867-asd",
"value": 110.99
}
],
"subtotal": 1000.99,
"total": 1234.99,
"totalTax": 20.99,
"transactionId": "012318432",
"locationIdentifier": "1235",
"locationAddress": "123 Road Street, Leeds",
"submissionPosition": {
"longitude": 170.9021,
"latitude": 80.9021
},
"metadata": {
"source": "API",
"campaignId": "ExampleCampaign",
"key": "value"
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"submitter": {
"type": "object",
"properties": {
"authIdentifier": {
"type": "string"
}
},
"required": [
"authIdentifier"
]
},
"serviceDate": {
"type": "string"
},
"serviceTime": {
"type": "string"
},
"lineItems": {
"type": "array"
},
"paymentTenders": {
"type": "array"
},
"subtotal": {
"type": "number"
},
"total": {
"type": "number"
},
"totalTax": {
"type": "number"
},
"transactionId": {
"type": "string"
},
"locationIdentifier": {
"type": "string"
},
"locationAddress": {
"type": "string"
},
"submissionPosition": {
"type": "object",
"properties": {
"longitude": {
"type": "number"
},
"latitude": {
"type": "number"
}
},
"required": [
"longitude",
"latitude"
]
},
"metadata": {
"type": "object",
"properties": {
"source": {
"type": "string"
},
"campaignId": {
"type": "string"
},
"key": {
"type": "string"
}
},
"required": [
"source"
]
}
},
"required": [
"serviceDate",
"serviceTime",
"lineItems"
]
}Responses
Headers
Content-Type: application/json; charset=utf-8Body
{
"status": "success",
"data": "Success:Accepted"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string"
},
"data": {
"type": "string"
}
}
}Create Order AsynclyPOST/orders/asyncly
👤 Admin authorization required
🔒 Admin Authorization with admin:receipts scope
Using the sync version (POST /orders) above is recommended. However, there are use-cases where using the asyncly order creation API is more appropriate. This is useful if the API invoking system needs to create orders in a fire-and-forget manner (eg if waiting for a response isn’t practical).
For general cases, prefer the POST /orders API.
When using this endpoint we recommend that you also pass a transactionId in the body which will be used for de-duplication within a 5 minute window.
Generated by aglio on 23 Feb 2026