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:
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."
}
    

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 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("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.
  • Examples:
    • 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
    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

    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
    java
    shell