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:
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
To authorize, every request should contain the authentication header:
Make sure to replace
your_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: your_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 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
}
The above command returns JSON structured like this:
{
"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
}
The above command returns JSON structured like this:
{
"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
}
The above command returns JSON structured like this:
{
"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
}
The above command returns JSON structured like this:
{
"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);
}
}
The above command returns JSON structured like this:
[
{
"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
addressv1/stores/7283/address
-
Target → Store ID
1818
addressv1/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
}
The above command returns JSON structured like this:
{
"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
-
Example 1: cp = shopper-1 Link: →
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
}
The above command returns JSON structured like this:
{
"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
}
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,
}
]
}
Logos
This is how/where you may retrieve store logos.
HTTP Request
GET
v2/resources/stores/{store_id}/logo
Examples:
-
Walmart → Store ID
7283
logov2/resources/stores/7283/logo
-
Target → Store ID
1818
logov2/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
|
---|