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:

contact@loyalize.com

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

ParameterDefaultDescription
page0Page number starting from 0 (zero).
size10Number of results per page.
nameKeyword used to find stores the name of which contains this word. Ex: box could return such stores as Boxup and BoxIT.
categoriesFilter 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/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
}


Get a Specific Store

This endpoint retrieves a specific store.

HTTP Request

GET v1/stores/<ID>

URL Parameters

ParameterDescription
IDThe 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 ..."
}
  

Search within Store Names and Descriptions

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

ParameterDescription
termThe term to search for within store names and store descriptions

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 query parameters:

v1/stores/1/tracking?cid=100&cp=

  • cid – Your Loyalize internal ID that is prefilled and no action is required. Please do not edit or delete it.
  • cp - you must include in the “cp” (custom parameter) the value of your shopper unique id. So, the shopper id must be already available in your system and you just provide it via “cp” query parameter. After the transaction is tracked, we display in the Loyalize Dashboard the shopper id, which will match the “cp” you provided. cp parameter can have up to 36 characters length.

Transactions

Get All Transactions

This endpoint retrieves all transactions.

HTTP Request

GET v2/transactions

Query Parameters

ParameterDefaultDescription
page0Page number starting from 0 (zero).
size10Number of results per page.
apiuIdGet one transaction by apiu transaction id.
shopperIdFilter transactions by the external shopper id
statusFilter transactions by the transaction status. Available values for status are: PENDING, AVAILABLE, PAID

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,
    "shopperId": "56ac8010-240e-4b5c-8e95-cfd38529b9f9",
    "storeId": "store_id",
    "status": "PENDING",
    "saleAmount": 1000,
    "shopperCommission": 120,
    "tier": "T1: 1-1000",
    "purchaseDate": "2020-09-01T15:10:45Z",
    "pendingDate": "2020-09-01T15:10:45Z",
    "availabilityDate": null,
    "paymentDate": null,
     }
    ]
  }


Errors

The Loyalize.com API uses the following error codes:

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

Download Postman Collection

FileDownload
java
shell