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
Parameter | Default | Description |
---|---|---|
page | 0 | Page number starting from 0 (zero). |
size | 10 | 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 |
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 ..."
}
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
Parameter | Description |
---|---|
term | The 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 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 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.
- sid – Suborganization ID, optional parameter. If you want to group your shoppers, you can pass the sid parameter alongside your cp. We will group all shoppers within an sid and this will provide for filtering 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 | 10 | 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, 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,
"sid": "sub-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 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 |
---|