Introduction
Welcome to the Loyalize API documentation.
The Loyalize API is built on REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Authentication
Get API KEY
To obtain your API key please contact us using the following email address.
Loyalize expects for the API key to be included in all API requests to the server: in the header of the request, following this format:
Authorization: your_api_key
To authorize, every request should contain the authentication header:
Categories
Get All Categories
This endpoint retrieves all categories.
HTTP Request
GET v1/stores/categories
curl --location --request GET "v1/stores/categories"
-H "Authorization: your_api_key"
The above command returns the following JSON output:
[
{
"name": "Automotive",
"seoFriendlyId": "automotive"
},
{
"name": "Babies & Kids",
"seoFriendlyId": "babies-kids"
}
]
Stores
Get All Stores
This endpoint retrieves all stores.
HTTP Request
GET v1/stores
Query Parameters
Parameter | Default | Description |
---|---|---|
page | 0 | Page number starting from 0 (zero). |
size | 20 | Number of results per page. |
name | Keyword used to find a store. For example, computer returns such results as Microsoft, Newegg, Corsair, Logitech and Monoprice, while gucci returns such results as Bergdorf Goodman and Perfumania.
|
|
categories |
Filter stores by one or more categories. Use
seoFriendlyId for the category that
you want to
filter. If more than one category is required, separate them by commas.
Examples:
automotive automotive,babies-kids |
|
ids | Filter stores by one or more store IDs. | |
countries |
Pull stores that ship products to or provide services in a specific country or countries.
If more than one country is required, separate them by commas.
Filtering by multiple countries narrows down the output.
Examples:
GLOBAL US,CA GB,FR,DE |
|
hasAddress | Pull stores with full physical addresses of headquarters. | |
tagName | Filter by a specific tag.
b2bStores Pull stores that carry products or provide services relevant to businesses.
bopisStores Pull stores that support buy-online-pickup-in-store or curbside delivery options.
extraCashback Pull stores that offer extra cashback.
toolbarAllowed Pull stores that permit the usage of browser toolbars.
topStores Pull the most recognizable and popular stores.
|
|
sort |
Sort by store name.
Examples:
name,asc name,desc |
import org.springframework.http.HttpEntity
import org.springframework.http.HttpHeaders
import org.springframework.http.HttpMethod
import org.springframework.web.client.RestTemplate
private static void getStores()
{
RestTemplate restTemplate = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
headers.add("Authorization", "your_api_key");
HttpEntity<Void> httpEntity = new HttpEntity(headers);
var responseAsJson = restTemplate.exchange("v1/stores",
HttpMethod.GET, httpEntity, String.class);
// convert responseAsJson to Java Objects
}
The above command returns the following JSON output:
{
"content": [
{
"id": 1,
"name": "Demo Store",
"url": "https://www.demo-store.com/",
"seoFriendlyId": "demo-store",
"description": "This is a test description",
"trackingUrl": "https://api.loyalize.com/v1/stores/1/tracking?cid=100&cp=",
"imageUrl": "https://api.loyalize.com/resources/stores/1/logo",
"commission": {
"value": 1.80,
"format": "%"
},
"countries": [
"GB",
"GLOBAL",
"US"
],
"categories": ["Demo Category"],
"storeTerms": "Not all purchases are eligible for cashback. Each store reserves the right
to exclude certain products or services from eligibility and you are subject to such
exclusions. Cashback is earned only on eligible purchases initiated using this platform.
To our knowledge, at Demo Store...",
"generalTerms": "Not all purchases are eligible for cashback. Each store reserves the right
to exclude certain products or services from eligibility and you are subject to such
exclusions. Cashback is earned only on eligible purchases initiated using this platform.",
"specificTerms": "To our knowledge, at Demo Store the following are not eligible for
cashback: laptops, tablets, desktops, video game and virtual reality hardware, computer
cards and components, COVID tests,all gift cards, and all Apple-branded products.
Additionally, Demo Store offers cashback only to new online customers."
}
],
"pageable": {
"sort": {
"sorted": false,
"unsorted": true,
"empty": true
},
"offset": 0,
"pageNumber": 0,
"pageSize": 1,
"paged": true,
"unpaged": false
},
"totalPages": 10,
"totalElements": 1000,
"last": true,
"number": 0,
"sort": {
"sorted": false,
"unsorted": true,
"empty": true
},
"size": 1,
"first": true,
"numberOfElements": 10,
"empty": false,
}
Get a Specific Store
This endpoint retrieves a specific store.
HTTP Request
GET v1/stores/<ID>
URL Parameters
Parameter | Description |
---|---|
id | ID of the store to retrieve |
import org.springframework.http.HttpEntity
import org.springframework.http.HttpHeaders
import org.springframework.http.HttpMethod
import org.springframework.web.client.RestTemplate
private static void getStoreById()
{
RestTemplate restTemplate = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
headers.add("Authorization", "your_api_key");
HttpEntity<Void> httpEntity = new HttpEntity(headers);
var responseAsJson = restTemplate.exchange("v1/stores/1",
HttpMethod.GET, httpEntity, String.class);
// convert responseAsJson to Java Objects
}
The above command returns the following JSON output:
{
"id": 1,
"name": "Demo Store",
"url": "https://www.demo-store.com/",
"seoFriendlyId": "demo-store",
"description": "This is a test description",
"trackingUrl": "https://api.loyalize.com/v1/stores/1/tracking?cid=100&cp=",
"imageUrl": "https://api.loyalize.com/resources/stores/1/logo",
"commission": {
"value": 1.80,
"format": "%"
},
"countries": [
"GB",
"GLOBAL",
"US"
],
"categories": ["Demo Category"],
"storeTerms": "Not all purchases are eligible for cashback. Each store reserves the right
to exclude certain products or services from eligibility and you are subject to such
exclusions. Cashback is earned only on eligible purchases initiated using this platform.
To our knowledge, at Demo Store...",
"generalTerms": "Not all purchases are eligible for cashback. Each store reserves the right
to exclude certain products or services from eligibility and you are subject to such
exclusions. Cashback is earned only on eligible purchases initiated using this platform.",
"specificTerms": "To our knowledge, at Demo Store the following are not eligible for
cashback: laptops, tablets, desktops, video game and virtual reality hardware, computer
cards and components, COVID tests,all gift cards, and all Apple-branded products.
Additionally, Demo Store offers cashback only to new online customers."
}
Store Search
This endpoint retrieves all stores that have the search term either in their name(s) or
description(s). For example, computer
returns such results as Microsoft, Newegg, Corsair, Logitech and Monoprice,
while gucci
returns such results as Bergdorf Goodman and Perfumania.
HTTP Request
GET v1/stores/search
QUERY Parameters
Parameter | Default | Description |
---|---|---|
term | The term to search within store names and store descriptions. | |
page | 0 | Page number starting from 0 (zero). |
size | 20 | Number of results per page. |
import org.springframework.http.HttpEntity
import org.springframework.http.HttpHeaders
import org.springframework.http.HttpMethod
import org.springframework.web.client.RestTemplate
public class Demo
{
public static void main (String[] args){
RestTemplate restTemplate = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
headers.add("Authorization", "your_api_key");
HttpEntity<Void> httpEntity = new HttpEntity(headers);
var responseAsJson = restTemplate.exchange("v1/stores/search?term=target",
HttpMethod.GET, httpEntity, String.class);
// convert responseAsJson to Java Objects
System.out.println(responseAsJson);
}
}
The above command returns the following JSON output:
[
{
"id": 1818,
"name": "Target",
"url": "https://www.target.com/",
"commission": {
"value": 5.00,
"format": "%"
},
"description": "Target is a leading retail brand that offers a vast selection of trendy and
affordable products for everyday life. Known for its distinctive red bullseye logo,
Target stores provide a delightful shopping experience with a diverse range of goods,
including clothing, electronics, home essentials, and groceries. With a focus on stylish
design, exceptional quality, and accessible pricing, Target continues to be a favorite
destination for shoppers seeking value and variety."
},
...]
Store Address
This is how you can retrieve primary physical addresses for stores.
HTTP Request
GET v1/stores/<ID>/address
Examples:
-
Walmart → Store ID
7283
addressv1/stores/7283/address
-
Target → Store ID
1818
addressv1/stores/1818/address
import org.springframework.http.HttpEntity
import org.springframework.http.HttpHeaders
import org.springframework.http.HttpMethod
import org.springframework.web.client.RestTemplate
private static void getStores()
{
RestTemplate restTemplate = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
headers.add("Authorization", "your_api_key");
HttpEntity<Void> httpEntity = new HttpEntity(headers);
var responseAsJson = restTemplate.exchange("v1/stores/1/address",
HttpMethod.GET, httpEntity, String.class);
// convert responseAsJson to Java Objects
}
The above command returns the following JSON output:
{
"storeId": 1,
"line1": "8311 West Roosevelt Road",
"line2": null,
"city": "Forest Park",
"region": "Illinois",
"zip": "60130",
"country": "United States"
}
Logos
This is how you can retrieve store logos.
HTTP Request
GET
resources/stores/{store_id}/logo
Examples:
-
Walmart → Store ID
7283
logoresources/stores/7283/logo
-
Target → Store ID
1818
logoresources/stores/1818/logo
Click Data
Get Click Data
This endpoint retrieves such data as click IDs, click dates, store names, shopper IDs, optional SIDs, and transaction IDs where applicable.
HTTP Request
GET v2/clicks
Query Parameters
Parameter | Default | Description |
---|---|---|
page | 0 | Page number starting from 0 (zero). |
size | 20 | Number of results per page. |
sort |
Sort by click date.
Examples:
clickDate,asc clickDate,desc |
|
shopperId | Filter click data by external shopper ID. | |
sid | Filter click data by SubID. | |
storeId | Filter click data by store ID. | |
storeName | Filter click data by store name. | |
clickDateStart, clickDateEnd | Filter click data by date range.
clickDateStart=YYYY-MM-DD clickDateEnd=YYYY-MM-DD |
import org.springframework.http.HttpEntity
import org.springframework.http.HttpHeaders
import org.springframework.http.HttpMethod
import org.springframework.web.client.RestTemplate
private static void getClickData()
{
RestTemplate restTemplate = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
headers.add("Authorization", "your_api_key");
HttpEntity<Void> httpEntity = new HttpEntity(headers);
var responseAsJson = restTemplate.exchange("v2/clicks,
HttpMethod.GET, httpEntity, String.class);
// convert responseAsJson to Java Objects
}
The above command returns the following JSON output:
{
"content": [
{
"id": "0b42911e03a44fhj8fb117ffa817754b",
"clickDate": "2023-10-28T09:24:32.784948Z",
"storeName": "Demo Store 1",
"storeId": 1,
"shopperId": "56ac8010-240e-4b5c-8e95-cfd38529b9f9",
"sid": null,
"transactionId": null
},
{
"id": "a698b13fd1574a345186fc377d5833be",
"clickDate": "2023-10-27T21:02:19.705489Z",
"storeName": "Demo Store 2",
"storeId": 2,
"shopperId": "56ac8010-240e-4b5c-8e95-cfd38529b9f9",
"sid": null,
"transactionId": "2537"
}
],
"pageable": {
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"offset": 0,
"pageNumber": 0,
"pageSize": 20,
"unpaged": false,
"paged": true
},
"totalPages": 1,
"totalElements": 2,
"last": false,
"size": 20,
"number": 0,
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"numberOfElements": 20,
"first": true,
"empty": false
}
Get Data for a Specific Click
This endpoint retrieves data for a specific click.
HTTP Request
GET v2/clicks/<ID>
URL Parameters
Parameter | Description |
---|---|
id | ID of the click to retrieve |
import org.springframework.http.HttpEntity
import org.springframework.http.HttpHeaders
import org.springframework.http.HttpMethod
import org.springframework.web.client.RestTemplate
private static void getClickData()
{
RestTemplate restTemplate = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
headers.add("Authorization", "your_api_key");
HttpEntity<Void> httpEntity = new HttpEntity(headers);
var responseAsJson = restTemplate.exchange("v2/clicks/1",
HttpMethod.GET, httpEntity, String.class);
// convert responseAsJson to Java Objects
}
The above command returns the following JSON output:
{
"id":"0b42911e03a44fhj8fb117ffa817754b",
"clickDate":"2023-10-28T09:24:32.784948Z",
"storeName":"Demo Store",
"storeId":1,
"shopperId":"56ac8010-240e-4b5c-8e95-cfd38529b9f9",
"sid":null,
"transactionId":null
}
User Tracking
Get All Stores and Get a Specific Store endpoints provide objects that contain the trackingUrl field, which has two mandatory and one optional query parameters.
Mandatory
v1/stores/1/tracking?cid=100&cp=
Optional
v1/stores/1/tracking?cid=100&cp=shoppper-id&sid=sub-id
- cid – Your Loyalize ID which is prefilled when your API key is used. Do not build links manually.
- cp - Unique identifier of a shopper in your environment (36 character limit), which must be passed on to Loyalize. Maps to Shopper ID in your Loyalize dashboard for tracked transactions.
- sid – Optional parameter that can be passed on to Loyalize. Allows to group and filter shoppers based on applications used if there are multiple use cases.
-
cp=shopper-1
https://api.loyalize.com/v1/stores/1/tracking?cid=100&cp=shopper-1
-
cp=shopper-1, sid=mobile-app
https://api.loyalize.com/v1/stores/1/tracking?cid=100&cp=shopper-1&sid=mobile-app
-
cp=shopper-1, sid=website
https://api.loyalize.com/v1/stores/1/tracking?cid=100&cp=shopper-1&sid=website
Transactions
Get All Transactions
This endpoint retrieves all transactions.
HTTP Request
GET v2/transactions
Query Parameters
Parameter | Default | Description |
---|---|---|
page | 0 | Page number starting from 0 (zero). |
size | 20 | Number of results per page. |
shopperId | Filter transactions by external shopper ID. | |
sid | Filter transactions by one or more SubIDs. | |
storeId | Filter transactions by store ID. | |
status | Filter transactions by status. Available values are: PENDING, AVAILABLE, PAYMENT_INITIATED, PAID, NON_COMMISSIONABLE | |
startDate | Set the reporting period start date when filtering by purchase date.
startDate=YYYY-MM-DD startDate=YYYY-MM-DDT00:00:00Z |
|
endDate | Set the reporting period end date when filtering by purchase date.
endDate=YYYY-MM-DD endDate=YYYY-MM-DDT00:00:00Z |
|
paidStartDate | Set the reporting period start date when filtering by payment date. | |
paidEndDate | Set the reporting period end date when filtering by payment date. |
import org.springframework.http.HttpEntity
import org.springframework.http.HttpHeaders
import org.springframework.http.HttpMethod
import org.springframework.web.client.RestTemplate
private static void getTransactions()
{
RestTemplate restTemplate = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
headers.add("Authorization", "your_api_key");
HttpEntity<Void> httpEntity = new HttpEntity(headers);
var responseAsJson = restTemplate.exchange("v2/transactions",
HttpMethod.GET, httpEntity, String.class);
// convert responseAsJson to Java Objects
}
The above command returns the following JSON output:
{
"content": [
{
"id": 1,
"sid": "sub-id-1",
"shopperId": "56ac8010-240e-4b5c-8e95-cfd38529b9f9",
"storeId": 1,
"storeName": "Demo Store",
"orderNumber": "demo-order-number",
"status": "PENDING",
"saleAmount": 1000,
"shopperCommission": 120,
"tier": "T1",
"purchaseDate": "2020-09-01T15:10:45Z",
"pendingDate": "2020-09-01T15:10:45Z",
"availabilityDate": null,
"paymentDate": null,
"lastUpdate": "2020-09-01T15:10:45Z",
}
]
}
Get a Specific Transaction
This endpoint retrieves a specific transaction.
HTTP Request
GET v2/transactions/<ID>
URL Parameters
Parameter | Description |
---|---|
id | ID of the transaction to retrieve |
import org.springframework.http.HttpEntity
import org.springframework.http.HttpHeaders
import org.springframework.http.HttpMethod
import org.springframework.web.client.RestTemplate
private static void getTransactions()
{
RestTemplate restTemplate = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
headers.add("Authorization", "your_api_key");
HttpEntity<Void> httpEntity = new HttpEntity(headers);
var responseAsJson = restTemplate.exchange("v2/transactions/1",
HttpMethod.GET, httpEntity, String.class);
// convert responseAsJson to Java Objects
}
The above command returns the following JSON output:
{
"id": 1,
"sid": "sub-id-1",
"shopperId": "56ac8010-240e-4b5c-8e95-cfd38529b9f9",
"storeId": 1,
"storeName": "Demo Store",
"orderNumber": "demo-order-number",
"status": "PENDING",
"saleAmount": 1000,
"shopperCommission": 120,
"tier": "T1",
"purchaseDate": "2020-09-01T15:10:45Z",
"pendingDate": "2020-09-01T15:10:45Z",
"availabilityDate": null,
"paymentDate": null,
"lastUpdate": "2020-09-01T15:10:45Z"
}
SKU Details
This call retrieves store logos.
HTTP Request
GET
v2/sku-details
Query Parameters
Parameter | Default | Description |
---|---|---|
page | 0 | Page number starting from 0 (zero). |
size | 20 | Number of results per page. |
transactionId | Filter SKU data for a specific transaction. | |
startDate | Set the reporting period start date. | |
endDate | Set the reporting period end date. |
import org.springframework.http.HttpEntity
import org.springframework.http.HttpHeaders
import org.springframework.http.HttpMethod
import org.springframework.web.client.RestTemplate
private static void getData()
{
RestTemplate restTemplate = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
headers.add("Authorization", "your_api_key");
HttpEntity<Void> httpEntity = new HttpEntity(headers);
var responseAsJson = restTemplate.exchange("https://api.loyalize.com/v2/sku-details",
HttpMethod.GET, httpEntity, String.class);
// convert responseAsJson to Java Objects
}
The above command returns the following JSON output:
{
"content": [
{
"id": 224,
"transactionId": 1,
"sku": "demo-sku-value",
"itemName": "Demo Item",
"quantity": 1,
"price": "20.54",
"shopperId": "shopper-id",
"orderNumber": "demo-order-nr",
"purchaseDate": "2022-09-09T12:46:20Z",
"storeName": Demo Store,
}
]
}
Webhooks
New Transaction
Get notifications on new transactions.
{
"body": {
"eventType": "NEW_TRANSACTION",
"data": {
"transactions": [1],
"changes": {
"newStatus": "PENDING"
}
}
}
}
Parameter | Description |
---|---|
eventType | Event type name |
data | Event related data |
transactions | ID(s) of new transaction(s) |
changes | New transactions are assigned the PENDING status by default |
Transaction Status Update
Get notifications on updates to transaction status(es).
{
"body":{
"eventType":"TRANSACTION_STATUS_UPDATE",
"data":{
"transactions":[1],
"changes":{
"newStatus":"AVAILABLE",
"oldStatus":"PENDING"
}
}
}
}
Parameter | Description |
---|---|
eventType | Event type name |
data | Event related data |
transactions | IDs of transactions with status updates. A single ID will be returned for updates involving PENDING, AVAILABLE, and NON_COMMISSIONABLE statuses. Multiple IDs may be returned for updates involving PAYMENT_INITIATED and PAID statuses. |
changes | Updates to transactions are reflected in newStatus and oldStatus fields |
Cashback Value Change
Get notifications on changes to transaction cashback values.
{
"body":{
"eventType":"CASHBACK_VALUE_CHANGE",
"data":{
"transactions":[1],
"changes":{
"newCashbackValue":"0.17",
"oldCashbackValue":"0.16",
"newSaleAmount":"18.49",
"oldSaleAmount":"18.48"
}
}
}
}
Parameter | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|
eventType | Event type name | |||||||||
data | Event related data | |||||||||
transactions | ID of a transaction with changes to cashback values | |||||||||
changes | Updates to a PENDING transaction as they relate to the Transactions endpoint
|
Store Added
Get notifications on new store availability.
{
"body": {
"eventType": "STORE_ADDED",
"data": [{
"id": 16811,
"name": "OutdoorMaster"
},{
"id": 29925,
"name": "Ritche Watch Bands"
}]
}
}
Parameter | Description |
---|---|
eventType | Event type name |
data | Event related data presented as an array of objects where each id matches the ID of an added store |
Store Removed
Get notifications on removal of stores.
{
"body": {
"eventType": "STORE_REMOVED",
"data": [{
"id": 552,
"name": "CreditRepair.com"
},{
"id": 19752,
"name": "Formula"
},{
"id": 20760,
"name": "RealSteel Center"
}]
}
}
Parameter | Description |
---|---|
eventType | Event type name |
data | Event related data presented as an array of objects where each id matches the ID of a removed store |
Store Cashback Change
Get notifications on changes to store cashback values.
{
"body": {
"eventType": "STORE_CASHBACK_CHANGE",
"data": [
{
"id": 1,
"name": "Demo Store",
"newCashback": {
"value": "12.0",
"format": "%"
},
"oldCashback": {
"value": "5.0",
"format": "%"
}
}
]
}
}
Parameter | Description |
---|---|
eventType | Event type name |
data | Event related data |
id | ID of a store with changes to cashback values |
name | Name of a store with changes to cashback values |
newCashback | Updated store cashback value |
oldCashback | Previous store cashback value |
Errors
The Loyalize.com API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request – Request is invalid. |
401 | Unauthorized – API key is wrong. |
404 | Not Found – Specified resource cannot be found. |
500 | Internal Server Error – There was a problem with our server. Try again later. |
503 | Service Unavailable – Temporarily offline for maintenance. Please try again later. |
Postman Collection
File | Download
|
---|