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: your_api_key

You must replace your_api_key with your personal API key.

# With shell, you can just pass the correct header with each request
curl "any_endpoint_here"
  -H "Authorization: your_api_key"

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, `mattress` returns such results as Mattress Firm and Puffy Mattress.
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. Examples: `US,CA` `UK,FR,DE`
hasAddress		Pull stores with full physical addresses of headquarters.
tagName		Filter by a specific tag. `bopisStores` Pull stores that support buy-online-pickup-in-store or curbside delivery options. `topStores` Pull the most recognizable and popular stores. `toolbarAllowed` Pull stores that permit the usage of browser toolbars.
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
}

curl "v1/stores"
-H "Authorization: your_api_key"

{
"content": [
{
    "id": 1,
    "name": "Demo Store",
    "url": "https://www.demo-store.com/",
    "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/1",
HttpMethod.GET, httpEntity, String.class);

// convert responseAsJson to Java Objects
}

curl "v1/stores/1"
-H "Authorization: your_api_key"

{
 "id": 1,
 "name": "Demo Store",
 "url": "https://www.demo-store.com/",
 "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
}

curl "v1/top-stores"
-H "Authorization: your_api_key"

{
"content": [
{
    "id": 1,
    "name": "Demo Store",
    "url": "https://www.demo-store.com/",
    "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
}

curl "v1/bopis-stores"
-H "Authorization: your_api_key"

{
"content": [
{
    "id": 1,
    "name": "Demo Store",
    "url": "https://www.demo-store.com/",
    "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...
}

Store Search

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);
 }
}

curl "v1/stores/search"
-H "Authorization: your_api_key"

[
 {
  "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
}

curl "v1/stores/1/address"
-H "Authorization: your_api_key"


{
  "storeId": 1,
  "line1": "8311 West Roosevelt Road",
  "line2": null,
  "city": "Forest Park",
  "region": "Illinois",
  "zip": "60130",
  "country": "United States"
}

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 – 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.localhost/v1/stores/1/tracking?cid=100&cp=shopper-id
- Example 2: cp = shopper-1 , sid = mobile-app Link: → http://api.localhost/v1/stores/1/tracking?cid=100&cp=shopper-id&sid=mobile-app
- Example 3: cp = shopper-1, sid = website Link: → http://api.localhost/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 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. `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. `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
}

curl "v2/transactions"
-H "Authorization: your_api_key"

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

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
}

curl "v2/sku-details"
-H "Authorization: your_api_key"

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

Logos

This is how/where you may retrieve store logos.

HTTP Request

GET v2/resources/stores/{store_id}/logo

Examples:

Walmart → Store ID 7283 logo v2/resources/stores/7283/logo
Target → Store ID 1818 logo v2/resources/stores/1818/logo

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`

Introduction

Authentication

Get API KEY

Categories

Get All Categories

HTTP Request

Stores

Get All Stores

HTTP Request

Query Parameters

Get a Specific Store

HTTP Request

URL Parameters

Get Top Stores

HTTP Request

Query Parameters

Get BOPIS Stores

HTTP Request

Query Parameters

Store Search

HTTP Request

QUERY Parameters

Store Address

HTTP Request

User Tracking

Transactions

Get All Transactions

HTTP Request

Query Parameters

SKU Details

Query Parameters

Logos

Errors

Download Postman Collection