Skip to main content

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

ElementTypeDescription
customerICustomerThe 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

ElementRequired / OptionalTypeDescription
customerNameRequiredICustomerNameThe 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

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

ElementRequired / OptionalTypeDescription
phoneNumberDetailsRequiredIPhoneNumberThe 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

ElementRequired / OptionalTypeDescription
phoneNumberDetailsRequiredIPhoneNumberThe 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

ElementRequired / OptionalTypeDescription
emailAddressDetailsRequiredIEmailAddressThe 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

ElementRequired / OptionalTypeDescription
emailAddressDetailsRequiredIEmailAddressThe 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

ElementRequired / OptionalTypeDescription
addressAndContactRequiredIAddressAndContactThe 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

ElementRequired / OptionalTypeDescription
addressAndContactRequiredIAddressAndContactThe 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 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

ElementTypeDescription
customerTransactionListICustomerTransactionListThis 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

ElementTypeDescription
customerTransactionDetailsListICustomerTransactionDetailsListThis contains the List of Customer Transaction Details.
criteriaICustomerTransactionEnquiryListCriteriaThis contains the criteria for the retrieved transaction.
transactionDateDateThis 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

ElementTypeDescription
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

ElementTypeDescription
accountIdStringThe loyalty account ID of the customer.
customerNumberIntegerThe customer account ID of the customer.
lastTransactionDateDateTimeThe date and time of the last transaction performed by the customer.
lastTransactionValueIntegerThe value of the last transaction performed by the customer.
rewardNumberStringThe loyalty card number of the customer.
accountStatusIdStringThe status ID of the loyalty account of the customer.
accountStatusDescStringThe status description of the loyalty account of the customer.
rewardTierStringThe loyalty tier ID that the customer is in.
rewardTierDescStringThe loyalty tier description that the customer is in.
pointsBalanceIntegerThe loyalty points balance of the customer.
redemptionBalanceIntegerThe redemption balance of the customer.
pointsDateDateTimeThe date and time that the points were last updated.
loyaltySchemeIdStringThe loyalty scheme ID of the customer.
loyaltySchemeDescStringThe 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 BodyIListVouchersResponseElementTypeDescription
voucherListList<IVoucherSerialNumber>The vouchers issued to the customer.
voucherTypesList<IVoucherTypeThe 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
ElementTypeDescription
voucherIVoucherSerialNumberThe voucher requested.
voucherTypeIVoucherTypeThe 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

HeaderDescriptionExample
enactor-device-idThis header will identify the ID of the device making the request.pos1@0001.enactor
enactor-location-idThis header will specify the location of the device making the request.0001
enactor-user-idThis 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
subjectCustomer 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

ElementTypeDescription
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": {}
    }
  ]
}

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

HeaderDescriptionExample
enactor-device-idThis header will identify the ID of the device making the request.pos1@0001.enactor
enactor-location-idThis header will specify the location of the device making the request.0001
enactor-user-idThis 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
subjectCustomer 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

ElementTypeDescription
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": {}
}

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

HeaderDescriptionExample
enactor-device-idThis header will identify the ID of the device making the request.pos1@0001.enactor
enactor-location-idThis header will specify the location of the device making the request.0001
enactor-user-idThis 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
subjectCustomer 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

ElementTypeDescription
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": {}
}