NAV Navbar
java
shell
loyalize_white_logo

Introduction

Welcome to Loyalize.com’s API

The Loyalize.com API is organized around 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 get your API Key please contact:

[email protected]

Loyalize.com 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: you_api_key

To authorize, every request should contain the authentication header:

Make sure to replace you_api_key with your API key.

Categories

Get All Categories

This endpoint retrieves all categories.

HTTP Request

GET v1/stores/categories

curl --location --request GET "v1/stores/categories"
  -H "Authorization: you_api_key"

The above command returns JSON structured like this:

[
 {
  "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 stores the name of which contains this word. Ex: box could return such stores as Boxup and BoxIT.
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.

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 JSON structured like this:

{
"content": [
{
    "id": 1,
    "name": "Demo Store",
    "seoFriendlyId": "demo-store",
    "description": "This is a test description",
    "trackingUrl": "v1/stores/1/tracking?cid=100&cp=",
    "imageUrl": "resources/stores/1/logo",
    "commission": {
                  "value": 1.80,
                  "format": "%"
                  },
    "categories": [
                   "Demo Category"
                  ]
  }
],
"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,
"storeTerms": While most purchases are eligible for the aforementioned cashback,
   please note that each brand reserves...
}


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

// convert responseAsJson to Java Objects
}

The above command returns JSON structured like this:

{
 "id": 1,
 "name": "Demo Store",
 "seoFriendlyId": "demo-store",
 "description": "This is a test description",
  "trackingUrl": "v1/stores/1/tracking?cid=100&cp=",
  "imageUrl": "resources/stores/1/logo",
  "commission": {
                "value": 1.80,
                "format": "%"
                },
  "categories": [
                 "Demo Category"
                ]
  "storeTerms": 
  "While most purchases are eligible for the aforementioned cashback,
     please note that each brand reserves ..."
}
  

Get Top Stores

This endpoint retrieves the most recognizable and popular brands and stores.

HTTP Request

GET v1/top-stores

Query Parameters

Parameter Default Description
page 0 Page number starting from 0 (zero).
size 20 Number of results per page.
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

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/top-stores",
HttpMethod.GET, httpEntity, String.class);

// convert responseAsJson to Java Objects
}

The above command returns JSON structured like this:

{
"content": [
{
    "id": 1,
    "name": "Demo Store",
    "seoFriendlyId": "demo-store",
    "description": "This is a test description",
    "trackingUrl": "v1/top-stores/1/tracking?cid=100&cp=",
    "imageUrl": "resources/top-stores/1/logo",
    "commission": {
                  "value": 1.80,
                  "format": "%"
                  },
    "categories": [
                   "Demo Category"
                  ]
  }
],
"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,
"storeTerms": While most purchases are eligible for the aforementioned cashback,
   please note that each brand reserves...
}


Get BOPIS Stores

This endpoint retrieves stores that support buy-online-pickup-in-store or curbside delivery options.

HTTP Request

GET v1/bopis-stores

Query Parameters

Parameter Default Description
page 0 Page number starting from 0 (zero).
size 20 Number of results per page.
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

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

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

// convert responseAsJson to Java Objects
}

The above command returns JSON structured like this:

{
"content": [
{
    "id": 1,
    "name": "Demo Store",
    "seoFriendlyId": "demo-store",
    "description": "This is a test description",
    "trackingUrl": "v1/stores/1/tracking?cid=100&cp=",
    "imageUrl": "resources/stores/1/logo",
    "commission": {
                  "value": 1.80,
                  "format": "%"
                  },
    "categories": [
                   "Demo Category"
                  ]
  }
],
"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,
"storeTerms": While most purchases are eligible for the aforementioned cashback,
   please note that each brand reserves...
}


This endpoint retrieves all stores that have the search term either in their name(s) or description(s).

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 JSON structured like this:

[
 {
  "id": 7183,
  "name": "Phone Power",
  "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."
 },
    ...]


User Tracking

Get All Stores and Get a Specific Store endpoints provide objects that contains the trackingUrl field which has two mandatory query parameters, and one is optional:

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 – Suborganization ID, optional parameter. If you want to group your shoppers, you can pass the sid parameter along with your cp. We will group all shoppers within an sid providing for filtering all transactions based on one or more sid values.

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 the external shopper id
sid Filter transactions by one or more sid.
status Filter transactions by the transaction status. Available values for status are: PENDING, AVAILABLE, PAYMENT_INITIATED, PAID, NON_COMMISSIONABLE
startDate Set the reporting period start date when filtering by purchase date.
endDate Set the reporting period end date when filtering by purchase date.
paidStartDate Set the reporting period start date when filtering by payment date.
paidEndDate Set the reporting period end date when filtering by payment date.
Pulling transactions by date range requires both startDate and endDate parameters in yyyy-MM-dd format
                
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 JSON structured like this:

{
"content": [
            {
             "id": 1,
             "sid": "sub-id-1",
             "shopperId": "56ac8010-240e-4b5c-8e95-cfd38529b9f9",
             "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

Get available SKU Details

This endpoint retrieves all available SKU Details records.

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 Details records for a specific transaction
startDate Set the reporting period start date.
endDate Set the reporting period end date.
Pulling SKU Details records by date range requires both startDate and endDate parameters in yyyy-MM-dd format. The records will be filtered by purchase 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 JSON structured like this:

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

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.

Download Postman Collection

File Download
java
shell