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"
 }
]
  
  

Deals

Get Deals

This endpoint will retrieve a list of all deals for a specific store, with details like deal title, description, and type (e.g. coupon, free shipping, sale), as well as applicable dates and any associated coupon codes.

HTTP Request

GET v1/deals

Query Parameters

Parameter Default Description
page 0 Page number starting from 0 (zero).
size 20 Number of results per page (up to 1,000).
id Identifier of a store associated with deals.
dealType Filter deals by type. Available values are: COUPON, FREE_SHIPPING, SALE_DISCOUNT, NEW_PRODUCT.
storeId Filter deals by store ID.
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

import org.springframework.http.HttpEntity
import org.springframework.http.HttpHeaders
import org.springframework.http.HttpMethod
import org.springframework.web.client.RestTemplate
private static void getDeals()
{
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/deals,
HttpMethod.GET, httpEntity, String.class);
// convert responseAsJson to Java Objects
}

The above command returns the following JSON output:

{
  "content": [
    {
        "id": 1,
        "storeId": 1,
        "storeName": "Demo Store",
        "title": "Demo title",
        "description": "Demo description",
        "dealType": "SALE_DISCOUNT",
        "couponCode": null,
        "trackingUrl": "https://api.loyalize.com/v1/stores/1/tracking?cid=122&cp=&dealId=1",
        "startDate": 2025-04-10T01:39:38.590066Z,
        "endDate": 2025-04-24T01:39:38.590066Z,
        "lastUpdate": "2025-04-13T17:39:51.143957Z"
        },
    {
        "id": 2,
        "storeId": 2,
        "storeName": "Demo Store 2",
        "title": "Demo title",
        "description": "Demo description",
        "dealType": "COUPON",
        "couponCode": "B3KPQ",
        "trackingUrl": "https://api.loyalize.com/v1/stores/2/tracking?cid=122&cp=&dealId=2",
        "startDate": 2025-04-14T01:39:38.590066Z,
        "endDate": 2025-04-24T01:39:38.590066Z,
        "lastUpdate": "2025-04-14T01:39:38.590066Z"
    },
  ],
  "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 a Specific Deal

This endpoint retrieves data for a specific deal.

HTTP Request

GET v1/deals/<ID>

URL Parameters

Parameter Description
id ID of the deal 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 getDealByID()
{
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/deals/1",
HttpMethod.GET, httpEntity, String.class);

// convert responseAsJson to Java Objects
}

The above command returns the following JSON output:


{
    "id": 1,
    "storeId": 1,
    "storeName": "Demo Store",
    "title": "Demo title",
    "description": "Demo description",
    "dealType": "SALE_DISCOUNT",
    "couponCode": null,
    "trackingUrl": "https://api.loyalize.com/v1/stores/1/tracking?cid=122&cp=&dealId=1",
    "startDate": 2025-04-10T01:39:38.590066Z,
    "endDate": 2025-04-24T01:39:38.590066Z,
    "lastUpdate": "2025-04-13T17:39:51.143957Z"
},
    

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 (up to 1,000).
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.
home
Pull stores based on one or more countries of their primary operation. Filtering by multiple countries will expand the output. Valid filter values are ISO 3166-1 alpha-2 country codes, region acronyms (APAC, EU, LATAM), and ALL to retrieve the entire inventory.
Examples:
US
ALL
CA,LATAM
countries
Pull stores that ship products to or provide services in a specific country or countries. Filtering by multiple countries narrows down the output. Valid filter values are ISO 3166-1 alpha-2 country codes as well as a GLOBAL tag indicating stores that service worldwide. Filtering by GLOBAL and a country or countries expands the output.
Examples:
GLOBAL
US,CA
GB,FR,DE
hasAddress Pull stores with full physical addresses of headquarters.
tagName
Filter by a specific tag or combine up to 5 tags for a more granular output.
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.
newCustomers
Pull stores that pay cashback on new customers only.
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",
            "language": "en",
            "description": "Demo 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": "%"
            },
            "commissionDetails": [
               {
                   "name": "Hotels",
                   "commission": {
                       "value": 8,
                       "format": "%"
                   }
                },
                {
                   "name": "Flights",
                   "commission": {
                       "value": 2.50,
                       "format": "USD"
                   }
                }
            ],
            "home": "US",
            "countries": [
                "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",
    "language": "en",
    "description": "Demo 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": "%"
    },
    "commissionDetails": [
       {
           "name": "Hotels",
           "commission": {
               "value": 8,
               "format": "%"
            }
        },
        {
           "name": "Flights",
           "commission": {
               "value": 2.50,
               "format": "USD"
           }
        }
    ],
    "home": "US",
    "countries": [
        "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."
}
    

Get Alternative Store Content

This endpoint retrieves alternative language content for a specific store, including description and terms.

HTTP Request

GET v1/stores/<ID>/alternative-content


import org.springframework.http.HttpEntity
import org.springframework.http.HttpHeaders
import org.springframework.http.HttpMethod
import org.springframework.web.client.RestTemplate

private static void getAlternativeStoreContent()
{
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/alternative-content",
HttpMethod.GET, httpEntity, String.class);

// convert responseAsJson to Java Objects
}

The above command returns the following JSON output:


[
  {
    "language": "fr",
    "isDefault": false,
    "description": "Description de démonstration.",
    "storeTerms": "Toutes les achats ne sont pas éligibles pour le cashback. Chaque magasin se réserve le droit d’exclure certains produits ou services de l’éligibilité, et vous êtes soumis à ces exclusions.",
    "generalTerms": "Le cashback est uniquement gagné sur les achats éligibles effectués via cette plateforme.",
    "specificTerms": "Chez Demo Store, les articles suivants ne sont pas éligibles au cashback : ordinateurs portables, tablettes, ordinateurs de bureau, matériel de jeux vidéo et de réalité virtuelle, cartes-cadeaux et produits de marque Apple."
  }
]
                    

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 (up to 1,000).
countries
Pull stores that ship products to or provide services in a specific country or countries. Filtering by multiple countries narrows down the output. Valid filter values are ISO 3166-1 alpha-2 country codes as well as a GLOBAL tag indicating stores that service worldwide.
Examples:
GLOBAL
US,CA
GB,FR,DE

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": 1,
  "name": "Demo Store",
  "url": "https://www.demo-store.com/",
  "commission": {
                 "value": 1.80,
                 "format": "%"
                },
  "description": "Demo description.",
  "language": "en",
  "trackingUrl": "https://api.loyalize.com/v1/stores/1/tracking?cid=1&cp=",
  "imageUrl": "https://api.loyalize.com/resources/stores/1/logo"
  "countries": [
      "GLOBAL",
      "US"
  ]
},
    ...]

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 (up to 1,000).
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=shopper-id

Optional
v1/stores/1/tracking?cid=100&cp=shopper-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 (96-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 (96-character limit). 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
    ids Filter transactions by one or more IDs.
    page 0 Page number starting from 0 (zero).
    size 20 Number of results per page (up to 1,000).
    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
    currency Filter transactions by currency.
    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.
    adminComment Comments on transactions with missing cashback values.
                    
    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",
                "currency": "USD",
                "saleAmount": 1000,
                "shopperCommission": 120,
                "tier": "T1",
                "purchaseDate": "2020-09-01T15:10:45Z",
                "pendingDate": "2020-09-01T15:10:45Z",
                "availabilityDate": null,
                "paymentDate": null,
                "adminComment": "Non-commissionable action",
                "lastUpdate": "2020-09-01T15:10:45Z",
                "isSkuDetailsBrand": true
            }
        ],
        "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 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",
       "currency": "USD",
       "saleAmount": 1000,
       "shopperCommission": 120,
       "tier": "T1",
       "purchaseDate": "2020-09-01T15:10:45Z",
       "pendingDate": "2020-09-01T15:10:45Z",
       "availabilityDate": null,
       "paymentDate": null,
       "adminComment": "Non-commissionable action",
       "lastUpdate": "2020-09-01T15:10:45Z",
       "isSkuDetailsBrand": true
    }
    
    

    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 (up to 1,000).
    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": [
            {
                "transactionId": 1,
                "sku": "demo-sku-value",
                "itemName": "Demo Item",
                "category": "Demo",
                "quantity": 1,
                "price": "20.54",
                "shopperId": "shopper-id",
                "orderNumber": "demo-order-nr",
                "purchaseDate": "2022-09-09T12:46:20Z",
                "storeName": Demo Store,
            }
        ],
        "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,
    }
                            
            

    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

    Store Terms Change

    Get notifications on changes to store terms.

    
    {
        "body": {
            "eventType": "STORE_TERMS_CHANGE",
            "data": [
                {
                    "id": 1,
                    "name": "Demo Store",
    "newTerms": "To our knowledge, at Demo Store, cashback is not available on the purchase of gift cards.",
                    "oldTerms": null
                }
            ]
        }
    }
                                                            
    Parameter Description
    eventType Event type name
    data Event related data
    id ID of a store with changes to terms
    name Name of a store with changes to terms
    newTerms Updated store terms
    oldTerms Previous store terms

    Store Country Change

    Get notifications on changes to store serviceable areas.

    
    {
        "body": {
            "eventType": "STORE_COUNTRY_CHANGE",
            "data": [
                {
                    "id": 1,
                    "name": "Demo Store",
                    "newCountries": [
                      "US",
                      "CA"
                    ],
                    "oldCountries": [
                      "US"
                    ]
                }
            ]
        }
    }
                                                                            
    Parameter Description
    eventType Event type name
    data Event related data
    id ID of a store with changes to serviceable areas
    name Name of a store with changes to serviceable areas
    newCountries Updated store serviceable areas
    oldCountries Previous store serviceable areas

    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