How-to Guide - Rest API - Voucher

Voucher API

Voucher Serial Number Enquiry

This service allows checking existing vouchers and retrieving the voucher details based on the serial number that is entered.

Request

Request Service URL

POST /loyalty/voucherSerialNumber/pos/enquiry

Request Tokens

There are no request tokens.

Request Parameters

There are no request parameters.

Request Body

Element	Mandatory / Optional	Type	Description
serialNumber	Mandatory	String	Tracked number of the Voucher.
voucherTypeId	Mandatory	Complex Type	Type of Voucher being looked up; this is the Voucher Type ID, keyed by Region.

Response

The response will depend on the result of the lookup.

If the Voucher is not found, then the service will return an outcome of 'NotFound'. The POS will then display a message to the user, who may retry with another Voucher Number.

If the voucher is found, the service returns the value and status of the Voucher.

Response Headers

There are no response headers.

Response Body

Element	Type	Description
outcome	String	Result of the lookup: for a successful match, this will be set to 'Success'.
voucherSerialNumber	Complex Type	Type of Voucher being looked up; this is the Voucher Type ID, keyed by Region.
serialNumber	String	Tracked number of the Voucher.
value	Long	This is the amount value of the Voucher.
status	String	Status of the Voucher. Status could be one of New, Issued, Redeemed or Voided.
currencyId	String	ID of the currency used in the Voucher.
customerID	Complex Type	The details of the Customer associated with the Voucher.

Request & Response Examples

Request

Enquiry of the Gift Voucher UK that has a serial number of '0101249180222154821269'.

POST: http://{{SWARM_LEADER_IP}}/WebRestApi/rest/loyalty/voucherSerialNumber/pos/enquiry


Body: {
  "serialNumber" : "0101249180222154821269",
  "voucherTypeId" : {
    "regionId" : {
      "groupTypeId" : "region",
      "groupHierarchyId" : "All",
      "groupId" : "UK",
      "id" : "UK"
    },
    "voucherTypeId" : "UK-GV"
  }
}

Response

The example response includes the outcome of the Gift Voucher UK that has a serial number of '0101249180222154821269'.

Body: {
  "outcome" : {
    "name" : "Success"
  },
  "voucherSerialNumber" : {
    "lastUpdated" : 1727759779824,
    "voucherTypeId" : {
      "regionId" : {
        "groupTypeId" : "region",
        "groupHierarchyId" : "All",
        "groupId" : "UK",
        "id" : "UK"
      },
      "voucherTypeId" : "UK-GV"
    },
    "serialNumber" : "0101249180222154821269",
    "value" : 10000,
    "status" : "ISSUED",
    "currencyId" : "GBP",
    "customerId" : { }
  }
}

Voucher Serial Number Matching Enquiry

This service is used to check the Voucher Type for a given Voucher Number. This service will be used by the POS when the user first enters a Voucher Number before choosing a Voucher Type.

Request

Request Service URL

POST /loyalty/voucherSerialNumber/pos/matchingEnquiry

Request Tokens

There are no request tokens.

Request Parameters

There are no request parameters.

Request Body

Element	Mandatory / Optional	Type	Description
regionId	Mandatory	Complex Type	Region of the POS Terminal from which the request is being made (Voucher Types may be set up regionally).
serialNumber	Mandatory	String	Tracked number of the Voucher.
removeExpiredVoucherSerialNumbers	Mandatory	Boolean	Flag that specifies the service to remove old, expired Vouchers.

Response

The response will depend on the result of the lookup.

The response always contains a pagedArrayList element. If the Voucher Number is not found, then the pagedArrayList contains an array of Property Names, but no values. If the Voucher is found, the pagedArrayList contains an array of Property Names and a key element, which contains details of the Voucher Serial Number that has been found.

Response Headers

There are no response headers.

Response Body

Element	Type	Description
VoucherSerialNumberKey	String	This contains the key of the Voucher Serial Number which comprises of: The Voucher Type to which the serial number belongs, including the region. Voucher Type. Serial Number of the Voucher.
description	Complex Type	Equivalent to the Voucher Serial Number.
descriptionProperty	String	Always set to the 'serialNumber'.
data	Long	Contains the full set of values corresponding to the Property Names: groupId serialNumber voucherType (including Region) status (of the Voucher) expiryDate and startDate campaignNumber and externalReference (optional)

Request & Response Examples

Request

Addition of the Gift Voucher UK to the basket that has a serial number of '0101249180222154821269'.

POST: http://{{SWARM_LEADER_IP}}/WebRestApi/rest/loyalty/voucherSerialNumber/pos/matchingEnquiry


Body: {
  "regionId" : {
    "groupTypeId" : "region",
    "groupHierarchyId" : "All",
    "groupId" : "UK",
    "id" : "UK"
  },
  "serialNumber" : "0101249180222154821269",
  "removeExpiredVoucherSerialNumbers" : false
}

Response

The example response includes the outcome of the Gift Voucher UK added to the basket that has a serial number of '0101249180222154821269'.

Response

Body: {
  "list" : [ {
    "key" : {
      "@type" : "voucherSerialNumberKey",
      "serialNumber" : "0101249180222154821269",
      "voucherTypeId" : {
        "regionId" : {
          "groupTypeId" : "region",
          "groupHierarchyId" : "All",
          "groupId" : "UK",
          "id" : "UK"
        },
        "voucherTypeId" : "UK-GV"
      }
    },
    "descriptionProperty" : "0101249180222154821269",
    "data" : {
      "Region:groupId" : "UK",
      "serialNumber" : "0101249180222154821269",
      "voucherTypeKey.regionKey.groupTypeId" : "region",
      "voucherTypeKey.voucherTypeId" : "UK-GV",
      "voucherTypeKey.regionKey.groupId" : "UK",
      "voucherTypeKey.regionKey.groupHierarchyId" : "All",
      "status" : "ISSUED"
    }
  } ],
  "propertyNames" : [ "serialNumber", "voucherTypeKey.regionKey.groupId", "voucherTypeKey.regionKey.groupHierarchyId", "voucherTypeKey.regionKey.groupTypeId", "voucherTypeKey.voucherTypeId", "status", "expiryDate", "startDate", "campaignNumber", "externalReference", "Region:groupId" ]
}

Voucher Serial Number Update

This service is used to update the details of a Voucher.

Request

Request Service URL

POST /loyalty/voucherSerialNumber/pos/update

Request Tokens

There are no request tokens.

Request Parameters

There are no request parameters.

Request Body

Element	Mandatory / Optional	Type	Description
voucherTypeId	Mandatory	Complex Type	Type of Voucher being looked up; this is the Enactor Voucher Type ID, keyed by Region.
voucherValue	Mandatory	Long	This is the amount value of the Voucher.
newStatus	Mandatory	String	The updated status required for the Voucher (i.e. Issued, Redeemed, Voided).
newIssueDate	Mandatory	DateTime	The date and time that the voucher is issued.
currencyId	Mandatory	String	ID of the currency used in the Voucher.
allowCreate	Mandatory	Boolean	Flag that specifies the service to allow creation of Vouchers.

Response

The response will depend on the result of the update.

If the voucher is not found or if the update fails for another reason, then the service will return an outcome of 'Fail'. The POS will then display a message to the User, who may retry or take other appropriate action. If the update is successful, then the service will return the updated status of the Voucher and an update reference ID.

Response Headers

There are no response headers.

Response Body

Element	Type	Description
outcome	String	Result of the lookup: this will be set to 'Success'.
voucherSerialNumberKey	Complex Type	This contains the Voucher details, including: - `voucherTypeId` - type of Voucher being looked up, as provided in request. - `serialNumber` - Voucher Number, as provided in request.
voucherValue	Mandatory	This is the amount value of the Voucher.
newStatus	Mandatory	The updated status required for the Voucher (i.e. Issued, Redeemed, Voided).
newIssueDate	Mandatory	The date and time that the voucher is issued.
currencyId	Mandatory	ID of the currency used in the Voucher.
allowCreate	Mandatory	Flag that specifies the service to allow creation of Vouchers.

Request & Response Examples

Request

Use of the Gift Voucher UK tender to the basket that has a serial number of '0596062241001135745013'.

Request

POST: http://{{SWARM_LEADER_IP}}/WebRestApi/rest/loyalty/voucherSerialNumber/pos/update


Body: {
  "voucherSerialNumberKey" : {
    "serialNumber" : "0596062241001135745013",
    "voucherTypeId" : {
      "regionId" : {
        "groupTypeId" : "region",
        "groupHierarchyId" : "All",
        "groupId" : "UK",
        "id" : "UK"
      },
      "voucherTypeId" : "UK-GV"
    }
  },
  "voucherValue" : 5000,
  "newStatus" : "ISSUED",
  "newIssueDate" : 1727771280000,
  "currencyId" : "GBP",
  "allowCreate" : true
}

Response

The example response includes the outcome of the Gift Voucher UK tender that has a serial number of '0596062241001135745013'.

Response

Body: {
  "outcome" : {
    "name" : "Success"
  },
  "voucherSerialNumberUpdate" : {
    "voucherSerialNumberUpdate" : {
      "voucherSerialNumberKey" : {
        "serialNumber" : "0596062241001135745013",
        "voucherTypeId" : {
          "regionId" : {
            "groupTypeId" : "region",
            "groupHierarchyId" : "All",
            "groupId" : "UK",
            "id" : "UK"
          },
          "voucherTypeId" : "UK-GV"
        }
      },
      "voucherValue" : 5000,
      "newStatus" : "ISSUED",
      "newIssueDate" : 1727771280000,
      "updateId" : "20241001092815",
      "currencyId" : "GBP",
      "allowCreate" : true
    }
  }
}

Voucher Serial Number Tracked Update

This service is used to update the details of a Voucher that has been configured with 'Update Usage' set to true.

Request

Request Service URL

POST /loyalty/voucherSerialNumber/pos/trackedUpdate

Request Tokens

There are no request tokens.

Request Parameters

There are no request parameters.

Request Body

Element	Mandatory / Optional	Type	Description
transactionId	Mandatory	String	The ID of the transaction that the voucher has been added to.
basketLineNumber	Mandatory	Long	The line number of the basket that the voucher has been added.
updateStatus	Mandatory	String	The updated status of the Voucher.
locationId	Mandatory	Complex Type	The ID of the location that the transaction is done.
userId	Mandatory	Complex Type	The ID of the user who is performing the transaction.
voucherTypeId	Mandatory	Complex Type	Type of Voucher being looked up; this is the Enactor Voucher Type ID, keyed by Region.
voucherValue	Mandatory	Long	This is the amount value of the Voucher.
newStatus	Mandatory	String	The updated status required for the Voucher (i.e. Issued, Redeemed, Voided).
currencyId	Mandatory	String	ID of the currency used in the Voucher.
allowCreate	Mandatory	Boolean	Flag that specifies the service to allow creation of Vouchers.

Response

The response will depend on the result of the update.

If the voucher is not found or if the update fails for another reason, then the service will return an outcome of 'Fail'. The POS will display a message to the User, who may retry or take other appropriate action. If the update is successful, then the service will return the updated status of the Voucher.

Response Headers

There are no response headers.

Response Body

Element	Type	Description
outcome	String	Result of the lookup: this will be set to 'Success'.
voucherSerialNumberKey	Complex Type	This contains the Voucher details, including: - `voucherTypeId` - type of Voucher being looked up, as provided in request - `serialNumber` - Voucher Number, as provided in request.
voucherValue	Mandatory	This is the amount value of the Voucher.
newStatus	Mandatory	The updated status required for the Voucher (i.e. Issued, Redeemed, Voided).
newIssueDate	Mandatory	The date and time that the voucher is issued.
currencyId	Mandatory	ID of the currency used in the Voucher.
allowCreate	Mandatory	Flag that specifies the service to allow creation of Vouchers.

Request & Response Examples

Request

Use of the Gift Voucher UK tender to the basket that has a serial number of '0101249180222154821269'.

Request

POST: http://{{SWARM_LEADER_IP}}/WebRestApi/rest/loyalty/voucherSerialNumber/pos/trackedUpdate


Body: {
  "transactionId" : "00050796000602410011351042",
  "basketLineNumber" : 2,
  "updateStatus" : "COMMITED",
  "locationId" : {
    "id" : "0005"
  },
  "userId" : {
    "id" : "000101"
  },
  "voucherSerialNumberKey" : {
    "serialNumber" : "0101249180222154821269",
    "voucherTypeId" : {
      "regionId" : {
        "groupTypeId" : "region",
        "groupHierarchyId" : "All",
        "groupId" : "UK",
        "id" : "UK"
      },
      "voucherTypeId" : "UK-GV"
    }
  },
  "voucherValue" : 10000,
  "newStatus" : "REDEEMED",
  "currencyId" : "GBP",
  "allowCreate" : false
}

Response

The example response includes the outcome of the Gift Voucher UK tender option that has a serial number of '0101249180222154821269'.

Response

Body: {
  "voucherSerialNumberUpdate" : {
    "voucherSerialNumberTrackedUpdate" : {
      "transactionId" : "00050796000602410011351042",
      "basketLineNumber" : 2,
      "updateStatus" : "COMMITED",
      "locationId" : {
        "id" : "0005"
      },
      "userId" : {
        "id" : "000101"
      },
      "voucherSerialNumberKey" : {
        "serialNumber" : "0101249180222154821269",
        "voucherTypeId" : {
          "regionId" : {
            "groupTypeId" : "region",
            "groupHierarchyId" : "All",
            "groupId" : "UK",
            "id" : "UK"
          },
          "voucherTypeId" : "UK-GV"
        }
      },
      "voucherValue" : 10000,
      "newStatus" : "REDEEMED",
      "currencyId" : "GBP",
      "allowCreate" : false
    }
  },
  "outcome" : {
    "name" : "Success"
  }
}

Voucher API​

Voucher Serial Number Enquiry​

Response​

Request & Response Examples​

Voucher Serial Number Matching Enquiry​

Response​

Request & Response Examples​

Voucher Serial Number Update​

Response​

Request & Response Examples​

Voucher Serial Number Tracked Update​

Request​

Response​

Request & Response Examples​

Voucher API

Voucher Serial Number Enquiry

Response

Request & Response Examples

Voucher Serial Number Matching Enquiry

Response

Request & Response Examples

Voucher Serial Number Update

Response

Request & Response Examples

Voucher Serial Number Tracked Update

Request

Response

Request & Response Examples