NAV Navbar
java
shell

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

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,
    "commission": 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.
java
shell