NAV Navbar
java
shell
loyalize_white_logo

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.

[email protected]

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:
US,CA
UK,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": "%"
            },
            "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 The 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": "%"
                },
 "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."
}
    

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=walmart",
HttpMethod.GET, httpEntity, String.class);

// convert responseAsJson to Java Objects
   System.out.println(responseAsJson);
 }
}

The above command returns the following JSON output:

[
 {
  "id": 7183,
  "name": "Phone Power",
  "url": "https://www.phone-power.com/",
  "commission": {
                 "value": 45.00,
                 "format": "USD"
                },
    "description": "Both residential and small business packages are available.
  We combine the highest quality customer service along with a competitive mix
  of pricing and features. The Phone Power network provides reliable
  service to thousands of customers, processing millions of minutes of calls
  each month, from all over the world. Phone Power also offers some of
  the most competitive international rates in the industry. All of our service
  packages come with our best international rates, without any dialing codes or
  special restrictions. You can dial internationally no matter where you are
  using our exclusive Click2Call interface inside the My Account portal."
 },
    ...]


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 address v1/stores/7283/address
  • Target → Store ID 1818 address v1/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 logo resources/stores/7283/logo
  • Target → Store ID 1818 logo resources/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("https://api.loyalize.com/v2/clicks,
HttpMethod.GET, httpEntity, String.class);
// convert responseAsJson to Java Objects
}

The above command returns the following JSON output:

{
  "content": [
    {
      "clickId": "0b42911e03a44fhj8fb117ffa817754b",
      "clickDate": "2023-10-28T09:24:32.784948Z",
      "storeName": "Walmart",
      "storeId": 1,
      "shopperId": "56ac8010-240e-4b5c-8e95-cfd38529b9f9",
      "sid": null,
      "transactionId": null
    },
    {
      "clickId": "a698b13fd1574a345186fc377d5833be",
      "clickDate": "2023-10-27T21:02:19.705489Z",
      "storeId": 2,
      "storeName": "Target",
      "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
}

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.

v1/stores/1/tracking?cid=100&cp= (Mandatory)

v1/stores/1/tracking?cid=100&cp=shoppper-id&sid=subgroup-id (Optional)

  • cid – Your Loyalize ID which is prefilled and no action is required. Please do not edit or delete it.
  • cp - In the cp (custom parameter) you must include the unique identifier of your shopper. So, the shopper id must be already available in your system, and you just provide it via the cp query parameter. After the transaction is tracked, we display the shopper id in your Loyalize Dashboard. It will match the cp that you provided. The cp parameter’s length can contain up to 36 characters.
  • sid – SubID, optional parameter. If you want to group your shoppers (be it based on a website they’ve used, or a mobile application, or if you license this functionality out to other businesses/organizations), you can pass the sid parameter along with your cp. We will group all shoppers within a sid providing a way for you to filter your transactions based on one or more sid values.
    • Example 1: cp = shopper-1 Link:http://api.loyalize/v1/stores/1/tracking?cid=100&cp=shopper-id
    • Example 2: cp = shopper-1 , sid = mobile-app Link:http://api.loyalize/v1/stores/1/tracking?cid=100&cp=shopper-id&sid=mobile-app
    • Example 3: cp = shopper-1, sid = website Link:http://api.loyalize/v1/stores/1/tracking?cid=100&cp=shopper-id&sid=web-app

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.
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": "Walmart",
             "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 The 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": "Walmart",
   "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": "Lorem Ipsum",
              "quantity": 1,
              "price": "20.54",
              "shopperId": "shopper-id",
              "orderNumber": "demo-order-nr",
              "purchaseDate": "2022-09-09T12:46:20Z",
              "storeName": Walmart,
              }
            ]
}
            
        

Webhooks

New Transaction

Get notifications on new transactions.


{
  "body": {
    "eventType": "NEW_TRANSACTION",
    "data": {
      "transactions": [2722],
      "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":[2722],
         "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":[2706],
         "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
Transactions Endpoint Old Value New Value
shopperCommission oldCashbackValue newCashbackValue
saleAmount oldSaleAmount newSaleAmount

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

Errors

The Loyalize.com API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
404 Not Found -- The specified kitten could not be found.
418 I'm a teapot.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Postman Collection

File Download
java
shell