How-to Guide - Rest API - Customers, Loyalty, and Account Balances
Introduction
The purpose of this guide is to provide an understanding of the REST Customers, Loyalty and Account Balances APIs provided by Enactor for use with external Web Sites and for Customer integration. It is separated out into functional areas, with each section related to a specific service. Note that the final URL used to access the service will be determined based on how the Enactor REST Promotions API is deployed.
Following are Enactor REST Customers, Loyalty and Account Balances APIs areas covered in this document:
-
Customer API
-
Customer Transaction History API
-
Loyalty API
-
Account Balance API
Customer API
The Customer API will provide the ability to retrieve and update Customer details. This includes details about Customer contact and loyalty information. Following is the list of Customer APIs covered in this section:
-
Get the Customer’s Details.
-
Update the Customer’s Name.
-
Add a new Phone Number.
-
Update a Phone Number.
-
Remove a Phone Number.
-
Add a new Email Address.
-
Update an Email Address.
-
Remove an Email Address.
-
Add a new Customer Address.
-
Update a Customer Address.
-
Remove a Customer Address.
Get the Customer’s Details
This service can retrieve details about the customer, including their name and contact details. It can also return their current loyalty tier and balance. Note that the customer number cannot be specified, it must come from the information included in the access token.
Request
Request Service URL
GET /customers
Request Tokens
There are no request tokens.
Request Parameters
There are no request parameters.
Request Body
There is no request body.
Response
Response Headers
There are no response headers.
Response Body
ICustomerResponse
| Element | Type | Description |
|---|---|---|
| customer | ICustomer | The details of the customer to return. |
Request & Response Examples
Request:
GET http://[SWARM_LEADER_IP]/WebRestApi/rest/customers
Response:
Status: 200 OK
{
"@entity": "retail:customerResponse",
"customer": {
"@entity": "retail:customer",
"addresses": {
"list": [
{
"country": "",
"countryCodeId": {
"@entity": "retail:countryCodeKey",
"id": ""
},
"isPreferred": true,
"organisation": "Enactor",
"restrictedReason": "",
"isActive": false,
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"county": "Hertfordshire",
"postCode": "SG141PB",
"street1": "1 Enactor House",
"street2": "Bluecoats Avenue",
"street3": "Street 3",
"town": "Hertford",
"isTemplate": false,
"referenceId": "",
"lastUpdated": 1518626282000,
"addressReferenceId": "c637-:19f34d5d541:4780d454:e6018e477d3b5ada",
"province": ""
},
{
"country": "UK",
"countryCodeId": {
"@entity": "retail:countryCodeKey",
"id": "GB"
},
"isPreferred": false,
"organisation": "Enactor Limited (work)",
"restrictedReason": "",
"isActive": false,
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": "ADDRESS_WORK"
},
"county": "Hertfordshire",
"postCode": "SG14 1PB",
"street1": "Enactor House",
"street2": "1 Bluecoats Avenue",
"street3": "",
"town": "Hertford",
"isTemplate": false,
"referenceId": "",
"lastUpdated": 1518626282000,
"addressReferenceId": "77a7-:374a487ba51:489e4565:28f3b2913cf5213c",
"province": ""
}
]
},
"contactMethod": "",
"contactable": false,
"dateCreated": 1397580687000,
"maritalStatus": "",
"nationality": "",
"noChildren": 0,
"customerNumber": "1",
"emailAddresses": [
{
"@entity": "retail:emailAddress",
"emailAddress": "markneilharrison@hotmail.co.uk",
"lastUpdated": 1518626282000,
"preferred": true,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": true
},
{
"@entity": "retail:emailAddress",
"emailAddress": "john.doe@enactor.co.uk",
"lastUpdated": 1518626282000,
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": true
},
{
"@entity": "retail:emailAddress",
"emailAddress": "john.doe@enactor.co.uk",
"lastUpdated": 1518626282000,
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": true
},
{
"@entity": "retail:emailAddress",
"emailAddress": "john.doe@enactor.co.uk",
"lastUpdated": 1518626282000,
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": true
},
{
"@entity": "retail:emailAddress",
"emailAddress": "john.doe@enactor.co.uk",
"lastUpdated": 1518626282000,
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": true
},
{
"@entity": "retail:emailAddress",
"emailAddress": "john.doe@enactor.co.uk",
"lastUpdated": 1518626282000,
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": true
},
{
"@entity": "retail:emailAddress",
"emailAddress": "john.doe@enactor.co.uk",
"lastUpdated": 1518626282000,
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": true
},
{
"@entity": "retail:emailAddress",
"emailAddress": "john.doe@enactor.co.uk",
"lastUpdated": 1518626282000,
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": true
},
{
"@entity": "retail:emailAddress",
"emailAddress": "john.doe@enactor.co.uk",
"lastUpdated": 1518626282000,
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": true
},
{
"@entity": "retail:emailAddress",
"emailAddress": "john.doe@enactor.co.uk",
"lastUpdated": 1518626282000,
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": true
},
{
"@entity": "retail:emailAddress",
"emailAddress": "john.doe@enactor.co.uk",
"lastUpdated": 1518626282000,
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": true
},
{
"@entity": "retail:emailAddress",
"emailAddress": "john.doe@enactor.co.uk",
"lastUpdated": 1518626282000,
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": true
},
{
"@entity": "retail:emailAddress",
"emailAddress": "john.doe@enactor.co.uk",
"lastUpdated": 1518626282000,
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": true
},
{
"@entity": "retail:emailAddress",
"emailAddress": "john.doe@enactor.co.uk",
"lastUpdated": 1518626282000,
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": true
},
{
"@entity": "retail:emailAddress",
"emailAddress": "john.doe@enactor.co.uk",
"lastUpdated": 1518626282000,
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": true
},
{
"@entity": "retail:emailAddress",
"emailAddress": "john.doe@enactor.co.uk",
"lastUpdated": 1518626282000,
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": true
},
{
"@entity": "retail:emailAddress",
"emailAddress": "john.doe@enactor.co.uk",
"lastUpdated": 1518626282000,
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": true
},
{
"@entity": "retail:emailAddress",
"emailAddress": "john.doe@enactor.co.uk",
"lastUpdated": 1518626282000,
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": true
}
],
"phoneNumbers": [
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01295768256",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": true,
"phoneNumberReferenceId": "b637-:19f34d5d541:4780d454:e6018e477d3b5ada"
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01992546873",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": true,
"phoneNumberReferenceId": "a637-:19f34d5d541:4780d454:e6018e477d3b5ada"
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": true,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
},
{
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1518626282000,
"number": "01707991122",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "",
"active": false,
"phoneNumberReferenceId": ""
}
],
"customerName": {
"@entity": "retail:name",
"surname": "Hanson",
"forename": "James"
},
"businessContactMethod": "",
"preferredContactTime": "",
"allowInternalMarketing": true,
"allowExternalMarketing": true,
"privacyLevel": 25,
"employeeKey": {
"@entity": "retail:employeeKey",
"id": ""
},
"lastUpdated": 1518626282000,
"contactInfoLinks": [
{
"@entity": "retail:contactInfoLink",
"addressReferenceId": "77a7-:374a487ba51:489e4565:28f3b2913cf5213c",
"phoneNumberReferenceId": "a637-:19f34d5d541:4780d454:e6018e477d3b5ada",
"lastUpdated": 1489141901000
}
],
"customerType": {
"@entity": "retail:customerTypeKey",
"id": ""
},
"organisation": "",
"taxIdentification": "",
"companyNumber": "",
"createdBy": {
"@entity": "retail:userKey",
"id": ""
},
"createdAt": {
"@entity": "retail:deviceKey",
"id": ""
},
"status": "",
"source": "",
"password": ""
}
}
Update the Customer’s Name
This service can change the name for the customer.
Request
Request Service URL
PATCH /customers/name
Request Tokens
There are no request tokens.
Request Parameters
There are no request parameters.
Request Body
IAddBasketItemRequest
| Element | Required / Optional | Type | Description |
|---|---|---|---|
| customerName | Required | ICustomerName | The new name for the customer. |
Response
Response Headers
There are no response headers.
Response Body
There is no response body.
Request & Response Examples
Request:
PATCH: http://[SWARM_LEADER_IP]/WebRestApi/rest/customers/name
Content-Type: application/json
{
"@entity": "retail:updateCustomerNameRequest",
"customerName": {
"@entity": "retail:customerName",
"surname": "Baldwin",
"forename": "Amelia"
}
}
Response:
Status: 200 OK
Customer Name Search
This service allows to get a list of customers matching the search name criteria.
The response consists of a paged array list. The contents of the response include a list of values for each customer record, comprising the name, address and customer number.
At the end of the response is a list of the property names returned, in the same sequence as the value lists.
Request
Request Service URL
GET /customers/search?name={nameValue}
Request Tokens
There are no request tokens.
Request Parameters
There are no request parameters.
Request Body
There is no request body.
Response
Response Headers
There are no response headers.
Response Body
| Element | Type | Description |
|---|---|---|
| accountList | Complex Type | Includes a list of accounts for the requested name searched |
Request & Response Examples
Request:
Search for customers with name starting with 'a':
GET: http://{{SWARM_LEADER_IP}}//WebRestApi/rest/customers/search?name=a
Response:
The example response includes two customer records - Miss Amelia and Mr Aspen:
Body: {
"customerList" : \[ {
"customerNumber" : "100",
"customerForename" : "Amelia",
"customerSurname" : "Baldwin",
"addressStreet1" : "137 Newport Road",
"addressTown" : "Hertford",
"addressPostCode" : "SG14 3AG",
"hasLoyaltyAccounts" : "TRUE",
"additionalData" : {
"mapImplClass" : "java.util.LinkedHashMap"
}
}, {
"customerNumber" : "7004",
"customerForename" : "Aspen",
"customerSurname" : "Green",
"addressStreet1" : "Rynkebyvej 3",
"addressTown" : "Sallested",
"addressPostCode" : "4920",
"hasLoyaltyAccounts" : "FALSE",
"additionalData" : {
"mapImplClass" : "java.util.LinkedHashMap"
}
} ]
}
Add a new Phone Number
This service can add a phone number to a customer. In this service, the phone number is associated with the customer and not a particular address. The ID for the new phone number is returned in the response headers. If the new phone number is marked as the preferred number, the existing preferred phone number is also updated to remove the preferred flag.
Request
Request Service URL
POST /customers/phoneNumbers
Request Tokens
There are no request tokens.
Request Parameters
There are no request parameters.
Request Body
| Element | Required / Optional | Type | Description |
|---|---|---|---|
| phoneNumberDetails | Required | IPhoneNumber | The new phone number details for the customer. |
Response
Response Headers
Location: /customers/phoneNumbers/{phoneNumberId}
Response Body
There is no response body.
Request & Response Examples
Request:
POST http://[SWARM_LEADER_IP]/WebRestApi/rest/customers/phoneNumbers
Content-Type: application/json
{
"@entity": "retail:addCustomerPhoneNumberRequest",
"phoneNumberDetails": {
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 1521045610000,
"number": "01295768256",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "C4DR673J6ZCQREFKJJ7M6GDOBQ",
"active": true
}
}
Response:
Status: 201 Created
Location: http://[SWARM_LEADER_IP]/WebRestApi/rest/customers/phoneNumbers/47
Update a Phone Number
This service can update a phone number on the customer. If the new details set the preferred phone number, the existing preferred phone number is changed to remove the preferred flag.
Request
Request Service URL
PUT /customers/phoneNumbers/{phoneNumberId}
Request Tokens
- phoneNumberId: The phoneNumberReferenceId of the phone number that is to be updated.
Request Parameters
There are no request parameters.
Request Body
| Element | Required / Optional | Type | Description |
|---|---|---|---|
| phoneNumberDetails | Required | IPhoneNumber | The new phone details for the customer. |
Response
Response Headers
There are no response headers.
Response Body
There is no response body.
Request & Response Examples
Request:
PUT http://[SWARM_LEADER_IP]/WebRestApi/rest/customers/phoneNumbers/C4DR673J6ZCQREFKJJ7M6GDOBQ
Content-Type: application/json
{
"@entity": "retail:updateCustomerPhoneNumberRequest",
"phoneNumberDetails": {
"@entity": "retail:phoneNumber",
"countryCode": "",
"lastUpdated": 15210456111111,
"number": "01295768256",
"preferred": false,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "C4DR673J6ZCQREFKJJ7M6GDOBQ",
"active": true
}
}
Response:
Status: 200 OK
Remove a Phone Number
This service can remove a phone number from the customer. The preferred phone number cannot be removed.
Request
Request Service URL
DELETE /customers/phoneNumbers/{phoneNumberId}
Request Tokens
- phoneNumberId: The phoneNumberReferenceId of the phone number that is to be deleted.
Request Parameters
There are no request parameters.
Request Body
There is no request body.
Response
Response Headers
There are no response headers.
Response Body
There is no response body.
Request & Response Examples
Request:
DELETE http://[SWARM_LEADER_IP]/WebRestApi/rest/customers/phoneNumbers/C4DR673J6ZCQREFKJJ7M6GDOBQ
Response:
Status: 200 OK
Add a new Email Address
This service can add a new email address for the customer. This service can also change the preferred email address for the customer. If so, the existing preferred email address is updated to clear the preferred flag.
Request
Request Service URL
POST /customers/emailAddresses
Request Tokens
There are no request tokens.
Request Parameters
There are no request parameters.
Request Body
| Element | Required / Optional | Type | Description |
|---|---|---|---|
| emailAddressDetails | Required | IEmailAddress | The new email address details for the customer. |
Response
Response Headers
Location: /customers/emailAddresses/{emailAddressId}
Response Body
There is no response body.
Request & Response Examples
Request:
POST http://[SWARM_LEADER_IP]/WebRestApi/rest/customers/emailAddresses
Content-Type: application/json
{
"@entity": "retail:addCustomerEmailAddressRequest",
"emailAddress": {
"@entity": "retail:emailAddress",
"emailAddress": "markneilharrison@hotmail.co.uk",
"lastUpdated": 1521048023000,
"preferred": true,
"restrictedReason": "",
"status": "",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": ""
},
"referenceId": "QCRT3GLPXBBG3BTBW64CBORJXI",
"active": true
}
}
Response:
Status: 200 Created
Update an Email Address
This service can update an existing email address for the customer. This service can also change the preferred email address for the customer. If so, the existing preferred email address is updated to clear the preferred flag.
Request
Request Service URL
PUT /customers/emailAddresses/{emailAddressId}
Request Tokens
- emailAddressId: The emailAddressReferenceId of the email address that is to be updated.
Request Parameters
There are no request parameters.
Request Body
| Element | Required / Optional | Type | Description |
|---|---|---|---|
| emailAddressDetails | Required | IEmailAddress | The new email address details for the customer. |
Response
Response Headers
There are no response headers.
Response Body
There is no response body.
Request & Response Examples
Request:
PUT http://[SWARM_LEADER_IP]/WebRestApi/rest/customers/emailAddresses/QCRT3GLPXBBG3BTBW64CBORJXI
Content-Type: application/json
{
"@entity": "retail:updateCustomerEmailAddressRequest",
"emailAddress": {
"@entity": "retail:emailAddress",
"emailAddress": "john.smith@example.co.uk",
"preferred": false,
"typeId": {
"@entity": "retail:contactTypeKey",
"id": "EMAIL_HOME"
},
"active": true
}
}
Response:
Status: 200 OK
Remove an Email Address
This service can remove an email address from the customer. The preferred email address cannot be removed.
Request
Request Service URL
DELETE /customers/emailAddresses/{emailAddressId}
Request Tokens
- emailAddressId: The emailAddressReferenceId of the email address that is to be deleted.
Request Parameters
There are no request parameters.
Request Body
There is no request body.
Response
Response Headers
There are no response headers.
Response Body
There is no response body.
Request & Response Examples
Request:
DELETE http://[SWARM_LEADER_IP]/WebRestApi/rest/customers/emailAddresses/QCRT3GLPXBBG3BTBW64CBORJXI
Response:
Status: 200 OK
Add a new Customer Address
This service is used to add a new address associated with the customer. The address may include a phone number and mobile phone number. This service can also be used to change the preferred contact and delivery addresses, in which case the existing preferred contact and delivery address is changed to not have the preferred flag.
Request
Request Service URL
POST /customers/addresses
Request Tokens
There are no request tokens.
Request Parameters
There are no request parameters.
Request Body
| Element | Required / Optional | Type | Description |
|---|---|---|---|
| addressAndContact | Required | IAddressAndContact | The new email address details for the customer. |
Response
Response Headers
Location: /customers/addresses/{addressId}
Response Body
There is no response body.
Request & Response Examples
Request:
POST http://[SWARM_LEADER_IP]/WebRestApi/rest/customers/addresses
Content-Type: application/json
{
"@entity": "retail:addCustomerAddressRequest",
"address": {
"@entity": "retail:address",
"country": "UK",
"countryCodeId": {
"@entity": "retail:countryCodeKey"
},
"organisation": "Enactor Limited",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": "ADDRESS WORK"
},
"county": "Hertfordshire",
"street1": "1 Bluecoats Avenune",
"town": "Hertord",
"isTemplate": false
}
}
Response:
Status: 201 Created
Location: http://[SWARM_LEADER_IP]/WebRestApi/rest/customers/addresses/JOKSCHVO5JC7ZJ36GL5BCEPTR4
Update a Customer Address
This service is used to update an existing address associated with the customer. The address may include a phone number and mobile phone number. This service can also be used to change the preferred contact and delivery addresses, in which case the existing preferred contact and delivery address is changed to not have the preferred flag.
Request
Request Service URL
PUT /customers/addresses/{addressId}
Request Tokens
- addressId: The ID of the address that is to be updated.
Request Parameters
There are no request parameters.
Request Body
| Element | Required / Optional | Type | Description |
|---|---|---|---|
| addressAndContact | Required | IAddressAndContact | The address with associated contact details to add to the customer. |
Response
Response Headers
There are no response headers.
Response Body
There is no response body.
Request & Response Examples
Request:
PUT http://[SWARM_LEADER_IP]/WebRestApi/rest/customers/addresses/JOKSCHVO5JC7ZJ36GL5BCEPTR4
Content-Type: application/json
{
"@entity": "retail:updateCustomerAddressRequest",
"address": {
"@entity": "retail:address",
"country": "UK",
"countryCodeId": {
"@entity": "retail:countryCodeKey"
},
"organisation": "Enactor Limited Work",
"typeId": {
"@entity": "retail:contactTypeKey",
"id": "ADDRESS WORK"
},
"county": "Hertfordshire",
"street1": "1 Bluecoats Avenune",
"town": "Hertord",
"isTemplate": false
}
}
Response:
Status: 200 OK
Remove a Customer Address
This service is used to remove an existing address associated with the customer. The 'default' address cannot be removed.
Request
Request Service URL
DELETE /customers/addresses/{addressId}
Request Tokens
- addressId: The ID of the address that is to be deleted.
Request Parameters
There are no request parameters.
Request Body
There is no request body.
Response
Response Headers
There are no response headers.
Response Body
There is no response body.
Request & Response Examples
Request:
DELETE http://[SWARM_LEADER_IP]/WebRestApi/rest/customers/addresses/JOKSCHVO5JC7ZJ36GL5BCEPTR4
Response:
Status: 200 OK
Customer Postcode Search
This service allows to get a list of customers matching the search postcode criteria.
The response consists of a paged array list. The contents of the response include a list of values for each customer record, comprising the name, address and customer number.At the end of the response is a list of the property names returned, in the same sequence as the value lists
Request
Request Service URL
GET /customers/search?postcode={postcodeValue}
Request Tokens
- postcode - Value of the postcode to be searched.
Request Parameters
There are no request parameters.
Request Body
There is no request body.
Response
Response Headers
There are no response headers.
Response Body
| Element | Type | Description |
|---|---|---|
| accountList | Complex Type | Includes a list of accounts for the requested name searched |
Request & Response Examples
Request
Search for customers with name starting with 'sg14':
GET:
http://{{SWARM_LEADER_IP}}//WebRestApi/rest/customers/search?postcode=sg14
Response:
The example response includes two customer records - Mr Ricky and Miss Amelia:
Body: {
{
"customerNumber" : "00100",
"customerForename" : "Ricky",
"customerSurname" : "Gervais",
"addressStreet1" : "137 Newport Road",
"addressTown" : "Hertford",
"addressPostCode" : "SG14 3AG",
"hasLoyaltyAccounts" : "FALSE",
"additionalData" : {
"mapImplClass" : "java.util.LinkedHashMap"
}
}, {
"customerNumber" : "100",
"customerForename" : "Amelia",
"customerSurname" : "Baldwin",
"addressStreet1" : "137 Newport Road",
"addressTown" : "Hertford",
"addressPostCode" : "SG14 3AG",
"hasLoyaltyAccounts" : "TRUE",
"additionalData" : {
"mapImplClass" : "java.util.LinkedHashMap"
}
}
}
Customer Transaction History API
The Customer Transaction History API provides the ability to list and retrieve a customer’s transaction history.
Following is the list of Promotions APIs covered in this section:
-
List Customer Transaction History.
-
Get a Customer’s Transaction History.
List Customer Transaction History
This API will list the transactions associated with the customer.
Request
Request Service URL
GET /customers/transactions
Request Tokens
There are no request tokens.
Request Parameters
There are no request parameters.
Request Body
There is no request body.
Response
Response Headers
There are no response headers.
Response Body
ICustomerTransactionSearchResponse
| Element | Type | Description |
|---|---|---|
| customerTransactionList | ICustomerTransactionList | This contains a list of 'CustomerTransactionListElement'. |
Request & Response Examples
Request:
GET http://[SWARM_LEADER_IP]/WebRestApi/rest/customers/transactions
Response:
Status: 200 OK
{
"customerTransactionList": [
{
"customerNumber": "1",
"applicationId": "POS",
"transactionId": "00010001000062008281556502",
"transactionTypeId": "Sale",
"locationId": "0001",
"transactionDate": 1598627791000,
"value": 12780,
"description": "Women's Dresses",
"loyaltyPoints": 0
},
{
"customerNumber": "1",
"applicationId": "POS",
"transactionId": "00010001000052008281555563",
"transactionTypeId": "Sale",
"locationId": "0001",
"transactionDate": 1598626606000,
"value": 17040,
"description": "Women's Dresses",
"loyaltyPoints": 0
},
{
"customerNumber": "1",
"applicationId": "POS",
"transactionId": "00010001000042008271257173",
"transactionTypeId": "Sale",
"locationId": "0001",
"transactionDate": 1598529760000,
"value": 8520,
"description": "Women's Dresses",
"loyaltyPoints": 0
},
{
"customerNumber": "1",
"applicationId": "POS",
"transactionId": "00010001000032008271252408",
"transactionTypeId": "Sale",
"locationId": "0001",
"transactionDate": 1598529434000,
"value": 8520,
"description": "Women's Dresses",
"loyaltyPoints": 0
}
]
}
Get a Customer’s Transaction History
This API will retrieve a customer's transaction for a given a transaction ID. The search can be filtered by assigning the Transactions Type ID parameter in the request.
Request
Request Service URL
GET /customers/transactions/{transactionId}
Request Tokens
- transactionId: The ID of the transaction to retrieve.
Request Parameters
- transactionTypeId: String. Can filter the type of transactions to be returned such as Sale. Eg: transactionTypeId=sale
Request Body
There is no request body.
Response
Response Headers
There are no response headers.
Response Body
ICustomerTransactionEnquiryResponse
| Element | Type | Description |
|---|---|---|
| customerTransactionDetailsList | ICustomerTransactionDetailsList | This contains the List of Customer Transaction Details. |
| criteria | ICustomerTransactionEnquiryListCriteria | This contains the criteria for the retrieved transaction. |
| transactionDate | Date | This contains the date of the transaction. |
Request & Response Examples
Request:
GET http://[SWARM_LEADER_IP]/WebRestApi/rest/customers/transactions/0001000100000045381
Response:
Status: 200 OK
{
"customerTransactionDetailsList": [
{
"lineNumber": "2",
"quantity": 1.0,
"effectiveNetValue": 4260,
"salesPerson": "1",
"productId": "MB709SN-2",
"description": "Rose Print Tea Dress",
"loyaltyPoints": 0
},
{
"lineNumber": "1",
"quantity": 1.0,
"effectiveNetValue": 4260,
"salesPerson": "1",
"productId": "MB709SN-2",
"description": "Rose Print Tea Dress",
"loyaltyPoints": 0
},
{
"lineNumber": "3",
"quantity": 0.0,
"effectiveNetValue": -8520,
"salesPerson": "1",
"description": "Cash UK",
"loyaltyPoints": 0
}
],
"criteria": {
"maxRows": 0,
"suppressDefaultOrderBy": false,
"distinct": false
}
}
Loyalty API
The Loyalty API is used to get loyalty details about a customer. It is not used to edit customer details, and only provides information about Loyalty aspects of the customer relationship.
Following is the list of Loyalty APIs covered in this section:
-
List Loyalty Accounts.
-
Get Loyalty Details.
-
Get Vouchers.
-
Get Voucher Details.
List Loyalty Accounts
This service is used to find all loyalty accounts that a customer is associated with. The customer is derived from the access token and cannot be directly specified.
Request
Request Service URL
GET /loyalty
Request Tokens
There are no request tokens.
Request Parameters
There are no request parameters.
Request Body
There is no request body.
Response
Response Headers
There are no response headers.
Response Body
IListLoyaltyAccountsResponse
| Element | Type | Description |
|---|---|---|
| accountList | List <ICustomerLoyaltyAccount> | A list of accounts associated with the customer, including the Account ID. |
Request & Response Examples
Request:
GET http://[SWARM_LEADER_IP]/WebRestApi/rest/loyalty
Response:
Status: 200 OK
{
"accountList": [
{
"customerLoyaltyAccount": {
"loyaltySchemeId": {
"id": "LOYALTY_UK"
},
"tierCode": "UK3",
"manualTierReview": false,
"accountId": "1",
"accountType": "customerLoyaltyAccount",
"accountOpenedDate": 1397516400000,
"status": "ACTIVE",
"customerNumber": "1",
"currencyId": {
"id": "GBP"
}
}
}
]
}
Get Loyalty Details
This service is used to find details about a specific Loyalty Account that the customer is associated with.
Note: Although an Account ID can be specified, it must be associated with the customer on the access token before it can be returned.
Request
Request Service URL
GET /loyalty/{accountId}
Request Tokens
- accountId: The ID of the Account to return.
Request Parameters
There are no request parameters.
Request Body
There is no request body.
Response
Response Headers
There are no response headers.
Response Body
CustomerLoyaltyDetailResponse
| Element | Type | Description |
|---|---|---|
| accountId | String | The loyalty account ID of the customer. |
| customerNumber | Integer | The customer account ID of the customer. |
| lastTransactionDate | DateTime | The date and time of the last transaction performed by the customer. |
| lastTransactionValue | Integer | The value of the last transaction performed by the customer. |
| rewardNumber | String | The loyalty card number of the customer. |
| accountStatusId | String | The status ID of the loyalty account of the customer. |
| accountStatusDesc | String | The status description of the loyalty account of the customer. |
| rewardTier | String | The loyalty tier ID that the customer is in. |
| rewardTierDesc | String | The loyalty tier description that the customer is in. |
| pointsBalance | Integer | The loyalty points balance of the customer. |
| redemptionBalance | Integer | The redemption balance of the customer. |
| pointsDate | DateTime | The date and time that the points were last updated. |
| loyaltySchemeId | String | The loyalty scheme ID of the customer. |
| loyaltySchemeDesc | String | The loyalty scheme description of the customer. |
Request & Response Examples
Request:
GET : http://[SWARM_LEADER_IP]/WebRestApi/rest/loyalty/200
Response:
Status: 200 OK
{
"accountId": "200",
"customerNumber": "100",
"lastTransactionDate": 1725552089000,
"lastTransactionDesc": "Womens Dresses",
"lastTransactionValue": 15000,
"rewardNumber": "14420000",
"accountStatusId": "ACTIVE",
"accountStatusDesc": "ACTIVE",
"rewardTier": "UK3",
"rewardTierDesc": "Gold",
"pointsBalance": 2691,
"redemptionBalance": 538200,
"pointsDate": 1725517899000,
"loyaltySchemeId": "LOYALTY_UK",
"loyaltySchemeDesc": "Loyalty Scheme UK"
}
Get Vouchers
This service is used to supply the list of vouchers issued to the customer associated with the access token. The customer is set in the header where the key is subject and the value is the customer ID.
Response
Response Headers
There are no response headers.
| Response BodyIListVouchersResponse | Element | Type | Description |
|---|---|---|---|
| voucherList | List<IVoucherSerialNumber> | The vouchers issued to the customer. | |
| voucherTypes | List<IVoucherType | The types of vouchers associated in the list of vouchers. |
Request & Response Examples
Request:
GET: http://[SWARM_LEADER_IP]/WebRestApi/rest/loyalty/vouchers
Response:
Status: 200 OK
{
"vouchersList": [
{
"voucherSerialNumber": {
"lastUpdated": 1556707671950,
"voucherTypeId": {
"regionId": {
"id": "All",
"groupTypeId": "region",
"groupHierarchyId": "All"
},
"voucherTypeId": "10_POUND"
},
"serialNumber": "11111111",
"value": 1000,
"status": "ISSUED",
"currencyId": "GBP",
"customerId": {
"id": "1"
},
"usageCount": 1000
}
}
],
"voucherTypes": [
{
"voucherType": {
"lastUpdated": 1556707672001,
"regionId": {
"id": "All",
"groupTypeId": "region",
"groupHierarchyId": "All"
},
"voucherTypeId": "10_POUND",
"description": {
"string": [
{
"string": "£10 Pound off"
},
{
"country": "GB",
"language": "en",
"string": "£10 Pound off"
}
]
},
"longDescription": {
"string": [
{
"string": "£10 Pound off when you spend £100"
},
{
"country": "GB",
"language": "en",
"string": "When you spend £100"
}
]
},
"disabled": false,
"allowReturn": false,
"allowIssue": true,
"allowTender": true,
"appliesDiscount": false,
"track": false,
"captureSerialNumber": false,
"generateSerialNumber": false,
"allowIssueOffline": false,
"allowRedemptionOffline": false,
"saleable": false,
"printed": false,
"endorse": false,
"openDrawer": false,
"expiryPeriod": 0,
"frankOnRedemption": false,
"valueType": "FIXED",
"redemptionOptions": {
"tenderValue": 1000,
"rewardType": "NONE",
"minimumSpend": 10000,
"itemPriceAbove": 0,
"itemPriceBelow": 0,
"markItemsUsed": false
},
"currencyKey": {
"id": "GBP"
},
"voucherValue": 10000,
"allowReturnOffline": false,
"usageLimit": 1000,
"allowMultiUseInOneTransaction": true
}
}
]
}
Get Voucher Details
This service is used to loads a voucher and its voucher type by the voucherId (voucher serial number).
Request
Request Service URL
GET /loyalty/vouchers/{voucherId}
Request Tokens
- voucherId: The ID of the Voucher to return the voucher details.
Request Parameters
There are no request parameters.
Request Body
There is no request body.
Response
Response Headers
There are no response headers.
Response Body
GET VoucherResponse
| Element | Type | Description |
|---|---|---|
| voucher | IVoucherSerialNumber | The voucher requested. |
| voucherType | IVoucherType | The voucher type of the voucher requested. |
Request & Response Examples
Request:
GET http://[SWARM_LEADER_IP]/WebRestApi/rest/loyalty/vouchers/0502046240313153745016
Response:
{
"voucherType": {
"lastUpdated": 1724321738068,
"regionId": {
"groupTypeId": "region",
"groupHierarchyId": "All",
"groupId": "US",
"id": "US"
},
"voucherTypeId": "10_DOLLAR",
"description": {
"string": [
{
"country": "US",
"language": "en",
"string": "$10 dollar off"
}
]
},
"longDescription": {
"string": [
{
"country": "US",
"language": "en",
"string": "When you spend $100"
}
]
},
"disabled": false,
"allowReturn": false,
"allowIssue": true,
"allowTender": true,
"appliesDiscount": false,
"track": false,
"captureSerialNumber": false,
"generateSerialNumber": false,
"allowIssueOffline": false,
"allowRedemptionOffline": false,
"saleable": false,
"printed": false,
"endorse": false,
"openDrawer": false,
"expiryPeriod": 0,
"frankOnRedemption": false,
"valueType": "FIXED",
"redemptionOptions": {
"tenderValue": 1000,
"rewardType": "NONE",
"minimumSpend": 10000,
"itemPriceAbove": 0,
"itemPriceBelow": 0,
"markItemsUsed": false,
"tenderid": {
"tenderId": "VCH",
"groupId": {
"groupTypeId": "region",
"groupHierarchyId": "All",
"groupId": "US",
"id": "US"
}
}
},
"currencyKey": {
"id": "USD"
},
"voucherValue": 10000,
"allowReturnOffline": false,
"usageLimit": 1000000,
"allowMultiUseInOneTransaction": true
}
}
Account Balance API
The Account Balance API is used to run customer account related functions. Following is the list of Account Balance APIs covered in this section:
-
Loyalty Lookup.
-
Get Account & Balance Details.
-
Submit or Cancel Account Balance Update.
Loyalty Lookup
This service is used to run a customer loyalty lookup.
Request
Request Service URL
GET /accounts/search/{?accountType}{?accountId}{?pan}{?hashedPan}{?currencyId}{?locationId}
Request Headers
| Header | Description | Example |
|---|---|---|
| enactor-device-id | This header will identify the ID of the device making the request. | pos1@0001.enactor |
| enactor-location-id | This header will specify the location of the device making the request. | 0001 |
| enactor-user-id | This header will specify the ID of the user making the request. Note that unlike the subject header, this identifier should be for information only and should not be used for authorisation. | 000101 |
| subject | Customer number to identify and verify the customer who is making the request and has the required permission to access an account. | 100 |
Request Tokens
-
accountType: Type of the account CustomerLoyaltyAccount, CustomerDepositAccount, CustomerCreditAccount, CustomerSpendAccount, etc.
-
accountId: The customer account ID.
-
pan:
The card number or the nceResponse.
-
hashedPan: The hashed card number.
-
currencyId: The ID of the currency.
-
locationId: The ID of the locations.
Request Parameters
There are no request parameters.
Request Body
There is no response body.
Response
Response Headers
There is no response header.
Response Body
| Element | Type | Description |
|---|---|---|
| accountBalanceEnquiryResponses | List <AccountBalanceEnquiryResponses > | A list of account balances associated with the customer, as requested in the lookup request. |
Request & Response Examples
Request:
GET http://[SWARM_LEADER_IP]/WebRestApi/rest/accounts/search/?accountType=customerLoyaltyAccount&accountId=887
enactor-device-id: pos1@0001.enactor
enactor-location-id: 0001
enactor-user-id: 000101
subject: 887
Response:
Status: 200 OK
{
"accountBalanceEnquiryResponses": [
{
"@type": "accountBalanceEnquiryResponse",
"accountBalanceEnquiryOutput": {
"@type": "accountBalanceEnquiryOutput",
"account": {
"@type": "customerLoyaltyAccount",
"loyaltySchemeId": {
"@type": "loyaltySchemeKey",
"id": "LOYALTY_UK"
},
"tierCode": "UK",
"manualTierReview": true,
"accountId": "0101025190527144502028",
"accountType": "customerLoyaltyAccount",
"accountOpenedDate": 1247596200000,
"status": "ACTIVE",
"customerNumber": "1",
"currencyId": {
"@type": "currencyKey",
"id": "GBP"
}
},
"accountDescription": "Customer Loyalty Account - Club",
"customer": {
"@type": "customer",
"addresses": [
{
"@type": "address",
"country": "GBR",
"isPreferred": true,
"county": "London",
"street2": "Chsiwick",
"street3": "street3",
"town": "London"
}
],
"customerNumber": "100000000000001",
"emailAddresses": [
{
"@type": "emailAddress",
"emailAddress": "validCustomer@enactor.co.uk",
"typeId": {
"@type": "contactTypeKey"
}
}
],
"phoneNumbers": [
{
"@type": "phoneNumber",
"number": "020 8234 4321",
"typeId": {
"@type": "contactTypeKey"
}
}
],
"customerName": {
"@type": "name",
"surname": "User",
"forename": "Test",
"title": "Mr"
}
},
"accountBalance": {
"@type": "accountBalance",
"accountId": "123456",
"accountType": "customerLoyaltyAccount",
"accountBalance": 1000,
"cardNumber": "8934736829037",
"currencyId": "GBP",
"balanceDate": 1625140844717,
"lastUpdated": 1625054444717
},
"customerCard": {
"@type": "customerCard",
"accountId": "0101025190527144502028",
"status": "NEW",
"accountType": "customerLoyaltyAccount",
"pan": "8934736829037",
"expiryDate": 1638100844718,
"issueDate": 1620820844718,
"nameOnCard": "Test User",
"issuedAt": {
"@type": "locationKey",
"id": "0001"
},
"createdOn": 1620734444718
},
"customerGroup": [
{
"@type": "groupKey",
"groupTypeId": "customerGroup",
"groupHierarchyId": "GOLD",
"id": "GOLD"
}
],
"customerLoyaltyAccountTotal": {
"@type": "customerLoyaltyAccountTotal",
"accountId": "0101025190527144502028",
"currencyId": {
"@type": "currencyKey",
"id": "GBP"
},
"numberOfTransactions": 3434,
"numberOfVisits": 8,
"totalSpend": 2980
},
"alternativeAmount": 888
},
"dynamicPromotions": [
{
"@type": "dynamicPromotion",
"promotionId": {
"@type": "promotionKey",
"promotionId": "PROMO",
"groupKey": {
"@type": "groupKey",
"groupTypeId": "customerGroup",
"groupHierarchyId": "GOLD",
"id": "GOLD"
}
},
"promotion": {
"@type": "promotion",
"promotionId": "TEST",
"groupKey": {
"@type": "groupKey",
"groupTypeId": "customerGroup",
"groupHierarchyId": "GOLD",
"id": "GOLD"
},
"description": "Birthday Promotion",
"priority": 99,
"overlapping": false,
"distributeSavingsOverAllItems": true,
"operationWithPreviousPromotions": "GROSS",
"raiseNearMissAlert": true,
"maximumTriggersPerTransaction": 10,
"timetableTrigger": {
"@type": "timetableTrigger",
"startDate": "2021-03-23T00:00:00.000+05:30",
"endDate": "2021-10-09T23:59:59.000+05:30",
"triggerPeriods": [
{
"timePeriod": {
"dayOfWeek": 1
}
},
{
"timePeriod": {
"dayOfWeek": 2
}
},
{
"timePeriod": {
"dayOfWeek": 3
}
},
{
"timePeriod": {
"dayOfWeek": 4
}
},
{
"timePeriod": {
"dayOfWeek": 5
}
},
{
"timePeriod": {
"dayOfWeek": 6
}
},
{
"timePeriod": {
"dayOfWeek": 7
}
}
]
},
"allowedForEmployeeSale": true,
"adjustEmployeeBalance": true
}
}
],
"messages": [
{
"@type": "uiMessage",
"messageBase": "Pos/Birthday/BirthdayMessages",
"messageId": "CUSTOMER_BIRTHDAY"
}
],
"errorMessage": {}
}
]
}
Loyalty Account Search
This service allows to get a list of loyalty accounts matching a customer.
This response is also returned as a Paged array list (though normally there would be only one record returned).
The values list has three values: the Customer loyalty account number, account type and status.
Now that the customer loyalty account number has been found, it may be submitted to the account balance enquiry service to retrieve the account details.
Request
Request Service URL
GET /loyalty
Request Tokens
There are no request tokens.
Request Parameters
There are no request parameters.
Request Body
There is no request body.
Response
Response Headers
There is no response header.
Response Body
| Element | Type | Description |
|---|---|---|
| accountList | Complex Type | Includes a list of loyalty accounts for the requested customer number. |
Request & Response Examples
Request:
Search for loyalty accounts of the customer with the customer ID of '100':
GET: http://{{SWARM_LEADER_IP}}//WebRestApi/rest/loyalty
Response:
The example response includes two loyalty account records for the customer ID of '100'.
Body: {
"accountList" : [ {
"customerLoyaltyAccount" : {
"tierName" : "Gold",
"loyaltySchemeName" : "Loyalty Scheme UK",
"accountId" : "200",
"accountType" : "customerLoyaltyAccount",
"accountOpenedDate" : 1635724800000,
"status" : "ACTIVE",
"customerNumber" : "100",
"tierCode" : "UK3",
"manualTierReview" : false,
"currencyId" : {
"id" : "GBP"
},
"loyaltySchemeId" : {
"id" : "LOYALTY_UK"
}
}
}, {
"customerLoyaltyAccount" : {
"tierName" : "Silver",
"loyaltySchemeName" : "Loyalty Scheme UK",
"accountId" : "201",
"accountType" : "customerLoyaltyAccount",
"accountOpenedDate" : 1635724800000,
"status" : "ACTIVE",
"customerNumber" : "100",
"tierCode" : "UK2",
"manualTierReview" : false,
"currencyId" : {
"id" : "GBP"
},
"loyaltySchemeId" : {
"id" : "LOYALTY_UK"
}
}
} ]
}
Get Account & Balance Details
This service is used to retrieve account balance details based on the provided parameters.
Request
Request Service URL
GET /accounts/{accountType}/{accountId}
Request Headers
| Header | Description | Example |
|---|---|---|
| enactor-device-id | This header will identify the ID of the device making the request. | pos1@0001.enactor |
| enactor-location-id | This header will specify the location of the device making the request. | 0001 |
| enactor-user-id | This header will specify the ID of the user making the request. Note that unlike the subject header, this identifier should be for information only and should not be used for authorisation. | 000101 |
| subject | Customer number to identify and verify the customer who is making the request and has the required permission to access an account. | 100 |
Request Tokens
-
accountType: Type of the account CustomerLoyaltyAccount, CustomerDepositAccount, CustomerCreditAccount, CustomerSpendAccount, etc.
-
accountId: The customer account ID.
Request Parameters
There are no request parameters.
Request Body
There is no response body.
Response
Response Headers
There is no response header.
Response Body
| Element | Type | Description |
|---|---|---|
| accountBalanceEnquiryResponses | List <AccountBalanceEnquiryResponses > | A list of account balances associated with the customer, as requested in the lookup request. |
Request & Response Examples
Request:
GET http://[SWARM_LEADER_IP]/WebRestApi/rest/accounts/customerLoyaltyAccount/888
enactor-device-id: pos1@0001.enactor
enactor-location-id: 0001
enactor-user-id: 000101
subject: 100
Response:
Status: 200 OK
{
"@type": "accountBalanceEnquiryResponse",
"accountBalanceEnquiryOutput": {
"@type": "accountBalanceEnquiryOutput",
"account": {
"@type": "customerLoyaltyAccount",
"loyaltySchemeId": {
"@type": "loyaltySchemeKey",
"id": "LOYALTY_UK"
},
"tierCode": "UK",
"manualTierReview": true,
"accountId": "0101025190527144502028",
"accountType": "customerLoyaltyAccount",
"accountOpenedDate": 1247596200000,
"status": "ACTIVE",
"customerNumber": "1",
"currencyId": {
"@type": "currencyKey",
"id": "GBP"
}
},
"accountDescription": "Customer Loyalty Account - Club",
"customer": {
"@type": "customer",
"addresses": [
{
"@type": "address",
"country": "GBR",
"isPreferred": true,
"county": "London",
"street2": "Chsiwick",
"street3": "street3",
"town": "London"
}
],
"customerNumber": "100000000000001",
"emailAddresses": [
{
"@type": "emailAddress",
"emailAddress": "validCustomer@enactor.co.uk",
"typeId": {
"@type": "contactTypeKey"
}
}
],
"phoneNumbers": [
{
"@type": "phoneNumber",
"number": "020 8234 4321",
"typeId": {
"@type": "contactTypeKey"
}
}
],
"customerName": {
"@type": "name",
"surname": "User",
"forename": "Test",
"title": "Mr"
}
},
"accountBalance": {
"@type": "accountBalance",
"accountId": "123456",
"accountType": "customerLoyaltyAccount",
"accountBalance": 1000,
"cardNumber": "8934736829037",
"currencyId": "GBP",
"balanceDate": 1625140844717,
"lastUpdated": 1625054444717
},
"customerCard": {
"@type": "customerCard",
"accountId": "0101025190527144502028",
"status": "NEW",
"accountType": "customerLoyaltyAccount",
"pan": "8934736829037",
"expiryDate": 1638100844718,
"issueDate": 1620820844718,
"nameOnCard": "Test User",
"issuedAt": {
"@type": "locationKey",
"id": "0001"
},
"createdOn": 1620734444718
},
"customerGroup": [
{
"@type": "groupKey",
"groupTypeId": "customerGroup",
"groupHierarchyId": "GOLD",
"id": "GOLD"
}
],
"customerLoyaltyAccountTotal": {
"@type": "customerLoyaltyAccountTotal",
"accountId": "0101025190527144502028",
"currencyId": {
"@type": "currencyKey",
"id": "GBP"
},
"numberOfTransactions": 3434,
"numberOfVisits": 8,
"totalSpend": 2980
},
"alternativeAmount": 888
},
"dynamicPromotions": [
{
"@type": "dynamicPromotion",
"promotionId": {
"@type": "promotionKey",
"promotionId": "PROMO",
"groupKey": {
"@type": "groupKey",
"groupTypeId": "customerGroup",
"groupHierarchyId": "GOLD",
"id": "GOLD"
}
},
"promotion": {
"@type": "promotion",
"promotionId": "TEST",
"groupKey": {
"@type": "groupKey",
"groupTypeId": "customerGroup",
"groupHierarchyId": "GOLD",
"id": "GOLD"
},
"description": "Birthday Promotion",
"priority": 99,
"overlapping": false,
"distributeSavingsOverAllItems": true,
"operationWithPreviousPromotions": "GROSS",
"raiseNearMissAlert": true,
"maximumTriggersPerTransaction": 10,
"timetableTrigger": {
"@type": "timetableTrigger",
"startDate": "2021-03-23T00:00:00.000+05:30",
"endDate": "2021-10-09T23:59:59.000+05:30",
"triggerPeriods": [
{
"timePeriod": {
"dayOfWeek": 1
}
},
{
"timePeriod": {
"dayOfWeek": 2
}
},
{
"timePeriod": {
"dayOfWeek": 3
}
},
{
"timePeriod": {
"dayOfWeek": 4
}
},
{
"timePeriod": {
"dayOfWeek": 5
}
},
{
"timePeriod": {
"dayOfWeek": 6
}
},
{
"timePeriod": {
"dayOfWeek": 7
}
}
]
},
"allowedForEmployeeSale": true,
"adjustEmployeeBalance": true
}
}
],
"messages": [
{
"@type": "uiMessage",
"messageBase": "Pos/Birthday/BirthdayMessages",
"messageId": "CUSTOMER_BIRTHDAY"
}
],
"errorMessage": {}
}
Account Balance Enquiry
This service provides the requested balance of any customer loyalty account.
Request
Request Service URL
GET /accountbalances?accountType={accountType}&pan={customerCardNumber}¤cyI{currencyID}
Request Headers
There are no request headers.
Request Tokens
- accountType - Type of the account which should be
- CustomerLoyaltyAccount in this case.
- Pan - The customer card number being enquired.
- currencyId - The ID of the currency associated to the account being enquired.
Request Parameters
There are no request parameters.
Request Body
There is no request body.
Response
Response Headers
There is no response header.
Response Body
| Element | Type | Description |
|---|---|---|
| account | Complex | Object containing the account information. |
| customer | Complex | Object containing the customer details. |
| accountBalance | Complex | Object containing the account balance information. |
| accountId | String | ID of the account. |
| accountType | String | Type of the account. |
| accountBalance | Long | Balance amount of the account. |
| balanceDate | DateTime | Date and time which the balance was last updated in the account. |
| customerCard | Complex | Object containing customer card details. |
| customerGroup | Complex | Customer Group details to which customer belongs (0 to many). |
| customerLoyaltyAccountTotal | Complex | Object containing the loyalty account summary totals. |
Following are the outcomes for Account Balance Service Enquiry:
-
Success: Account is found and Customer details are returned.
-
NoAccount: Card or Customer Account is not found; the POS will inform the user appropriately.
-
UnknownAccountType: Customer found but account type not recognised.
-
Fail: Other failure occurred during Account lookup. An error message will be displayed to the user.
Request & Response Examples
Request:
Enquiry of loyalty account balance with the card number of '14420000':
GET: http://{{SWARM_LEADER_IP}}/WebRestApi/rest/accountbalances?
accountType=customerLoyaltyAccount&pan=14420000¤cyId=GBP
Response:
Following is an example response that includes the loyalty account record for the customer loyalty card of '14420000':
Body: {
"outcome" : {
"name" : "Success"
},
"account" : {
"@type" : "customerLoyaltyAccount",
"accountId" : "200",
"accountType" : " customerLoyaltyAccount ",
"accountOpenedDate" : 1684105200000,
"status" : "ACTIVE",
"customerNumber" : "100",
"lastUpdated" : 1725290061930,
"currencyId" : {
"id" : "GBP"
}
},
"customer" : {
"addresses" : [ {
"@type" : "address",
"country" : "United Kingdom",
"countryCodeId" : {
"countryId" : "GBR",
"id" : "GBR"
},
"isPreferred" : true,
"isActive" : false,
"status" : "ACTIVE",
"typeId" : {
"contactTypeId" : "ADDRESS_HOME",
"id" : "ADDRESS_HOME"
},
"postCode" : "SG14 3AG",
"street1" : "137 Newport Road",
"town" : "Carmel",
"isTemplate" : false,
"lastUpdated" : 1725956944000,
"addressReferenceId" : "bb36:1b2aadb5d71:ef5efbd7-:69b14aea4b151737"
} ],
"contactable" : false,
"noChildren" : 0,
"customerNumber" : "100",
"emailAddresses" : [ {
"emailAddress" : "abaldwin@enactordata.co",
"lastUpdated" : 1725956944000,
"preferred" : true,
Submit or Cancel Account Balance Update
This service is used to apply or cancel the account balance update to the appropriate account balance.
Request
Request Service URL
POST /accountBalances/update
PATCH /accountBalances
Request Headers
| Header | Description | Example |
|---|---|---|
| enactor-device-id | This header will identify the ID of the device making the request. | pos1@0001.enactor |
| enactor-location-id | This header will specify the location of the device making the request. | 0001 |
| enactor-user-id | This header will specify the ID of the user making the request. Note that unlike the subject header, this identifier should be for information only and should not be used for authorisation. | 000101 |
| subject | Customer number to identify and verify the customer who is making the request and has the required permission to access an account. | 100 |
Request Tokens
-
accountType: Type of the account CustomerLoyaltyAccount, CustomerDepositAccount, CustomerCreditAccount, CustomerSpendAccount, etc.
-
accountId: The customer account ID.
Request Parameters
There are no request parameters.
Request Body
Response
Response Headers
There is no response header.
Response Body
| Element | Type | Description |
|---|---|---|
| accountBalanceEnquiryResponses | List <AccountBalanceEnquiryResponses > | A list of account balances associated with the customer, as requested in the lookup request. |
Request & Response Examples
Request:
POST http://[SWARM_LEADER_IP]/WebRestApi/rest/accountBalances/update
enactor-device-id: pos1@0001.enactor
enactor-location-id: 0001
enactor-user-id: 000101
subject: 100
Content-Type: application/json
{
"@type": "accountBalanceUpdate",
"transactionId": 978789,
"deviceId": { "@type": "deviceKey", "id": "pos1@0001.enactor" },
"accountId": "0101025190527144502028",
"accountType": "customerLoyalatyAccount",
"cardNumber": "8934736829037",
"updateAmount": 88,
"dateTimeUpdated": 1624295653842,
"expiryTime": 1625591653000,
"status": "PENDING",
"referenceId": "34546344543",
"locationId": "0001"
}
Response:
Status: 200 OK
{
"@type": "accountBalanceUpdateResponse",
"accountBalanceUpdateOutput": {
"@type": "accountBalanceUpdateOutput",
"accountBalanceUpdate": {
"@type": "accountBalanceUpdate",
"transactionId": 978789,
"deviceId": {
"@type": "deviceKey",
"id": "pos1@0001.enactor"
},
"originalTransactionDeviceId": {
"@type": "deviceKey",
"id": "pos1@0001.enactor"
},
"originalTransactionId": "123456789012345",
"locationId": "Store1",
"accountId": "0101025190527144502028",
"accountType": "customerLoyalatyAccount",
"cardNumber": "8934736829037",
"updateAmount": 88,
"dateTimeUpdated": 1624300226258,
"expiryTime": 1625596226000,
"status": "PENDING",
"referenceId": "343435423"
}
},
"errorMessage": {}
}
Account Balance Update
This service allows sending an update request for the account balance of a given account.
Request
Request Service URL
POST /accountbalances/pos/update
Request Headers
There is no request header.
Request Tokens
There are no request tokens.
Request Parameters
There are no request parameters.
Request Body
| Element | Mandatory / Optional | Type | Description |
|---|---|---|---|
| accountType | Mandatory | String | Type of the account. |
| cardNumber | Mandatory | String | Card number associated with the account. |
| cardNumberHashed | Optional | String | Hashed value of the card number. |
| currencyId | Optional | String | ID of the currency used in the account. |
| locationId | Optional | String | ID of the location associated with the account. |
Response
Response Headers
There is no response header.
Response Body
| Element | Type | Description |
|---|---|---|
| account | Complex | Object containing the account information. |
| customer | Complex | Object containing the customer details. |
| accountBalance | Complex | Object containing the account balance information. |
| accountId | String | ID of the account. |
| accountType | String | Type of the account. |
| accountBalance | Long | Balance amount of the account. |
| balanceDate | DateTime | Date and time which the balance was last updated in the account. |
| customerCard | Complex | Object containing customer card details. |
| customerGroup | Complex | Customer Group details to which customer belongs (0 to many). |
| customerLoyaltyAccountTotal | Complex | Object containing the loyalty account summary totals. |
Following are the outcomes for Account Balance Service Enquiry:
-
Success: Account is found and Customer details are returned.
-
NoAccount: Card or Customer Account is not found; the POS will inform the user appropriately.
-
UnknownAccountType: Customer found but account type not recognised.
-
Fail: Other failure occurred during Account lookup. An error message will be displayed to the user.