Introduction
Welcome to the Loyalize API documentation.
The Loyalize API is built on 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 obtain your API key please contact us using the following email address.
Loyalize 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:
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 the following JSON output:
[
{
"name": "Automotive",
"seoFriendlyId": "automotive"
},
{
"name": "Babies & Kids",
"seoFriendlyId": "babies-kids"
}
]
Deals
Get Deals
This endpoint will retrieve a list of all deals for a specific store, with details like deal title, description, and type (e.g. coupon, free shipping, sale), as well as applicable dates and any associated coupon codes.
HTTP Request
GET v1/deals
Query Parameters
Parameter | Default | Description |
---|---|---|
page | 0 | Page number starting from 0 (zero). |
size | 20 | Number of results per page (up to 1,000). |
id | Identifier of a store associated with deals. | |
dealType | Filter deals by type. Available values are: COUPON, FREE_SHIPPING, SALE_DISCOUNT, NEW_PRODUCT. | |
storeId | Filter deals by store ID. | |
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 |
import org.springframework.http.HttpEntity
import org.springframework.http.HttpHeaders
import org.springframework.http.HttpMethod
import org.springframework.web.client.RestTemplate
private static void getDeals()
{
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/deals,
HttpMethod.GET, httpEntity, String.class);
// convert responseAsJson to Java Objects
}
The above command returns the following JSON output:
{
"content": [
{
"id": 1,
"storeId": 1,
"storeName": "Demo Store",
"title": "Demo title",
"description": "Demo description",
"dealType": "SALE_DISCOUNT",
"couponCode": null,
"trackingUrl": "https://api.loyalize.com/v1/stores/1/tracking?cid=122&cp=&dealId=1",
"startDate": 2025-04-10T01:39:38.590066Z,
"endDate": 2025-04-24T01:39:38.590066Z,
"lastUpdate": "2025-04-13T17:39:51.143957Z"
},
{
"id": 2,
"storeId": 2,
"storeName": "Demo Store 2",
"title": "Demo title",
"description": "Demo description",
"dealType": "COUPON",
"couponCode": "B3KPQ",
"trackingUrl": "https://api.loyalize.com/v1/stores/2/tracking?cid=122&cp=&dealId=2",
"startDate": 2025-04-14T01:39:38.590066Z,
"endDate": 2025-04-24T01:39:38.590066Z,
"lastUpdate": "2025-04-14T01:39:38.590066Z"
},
],
"pageable": {
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"offset": 0,
"pageNumber": 0,
"pageSize": 20,
"unpaged": false,
"paged": true
},
"totalPages": 1,
"totalElements": 2,
"last": false,
"size": 20,
"number": 0,
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"numberOfElements": 20,
"first": true,
"empty": false
}
Get a Specific Deal
This endpoint retrieves data for a specific deal.
HTTP Request
GET v1/deals/<ID>
URL Parameters
Parameter | Description |
---|---|
id | ID of the deal 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 getDealByID()
{
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/deals/1",
HttpMethod.GET, httpEntity, String.class);
// convert responseAsJson to Java Objects
}
The above command returns the following JSON output:
{
"id": 1,
"storeId": 1,
"storeName": "Demo Store",
"title": "Demo title",
"description": "Demo description",
"dealType": "SALE_DISCOUNT",
"couponCode": null,
"trackingUrl": "https://api.loyalize.com/v1/stores/1/tracking?cid=122&cp=&dealId=1",
"startDate": 2025-04-10T01:39:38.590066Z,
"endDate": 2025-04-24T01:39:38.590066Z,
"lastUpdate": "2025-04-13T17:39:51.143957Z"
},
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 (up to 1,000). |
name | Keyword used to find a store. For example, computer returns such results as Microsoft, Newegg, Corsair, Logitech and Monoprice, while gucci returns such results as Bergdorf Goodman and Perfumania.
|
|
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. | |
home |
Pull stores based on one or more countries of their primary operation. Filtering by multiple countries will expand the output. Valid filter values are ISO 3166-1 alpha-2 country codes, region acronyms (
APAC , EU , LATAM ), and ALL to retrieve the entire inventory.
Examples:
US ALL CA,LATAM |
|
countries |
Pull stores that ship products to or provide services in a specific country or countries.
Filtering by multiple countries narrows down the output. Valid filter values are ISO 3166-1 alpha-2 country codes as well as a GLOBAL tag indicating stores that service worldwide. Filtering by GLOBAL and a country or countries expands the output.
Examples:
GLOBAL US,CA GB,FR,DE |
|
hasAddress | Pull stores with full physical addresses of headquarters. | |
tagName | Filter by a specific tag or combine up to 5 tags for a more granular output.
b2bStores Pull stores that carry products or provide services relevant to businesses.
bopisStores Pull stores that support buy-online-pickup-in-store or curbside delivery options.
extraCashback Pull stores that offer extra cashback.
newCustomers Pull stores that pay cashback on new customers only.
toolbarAllowed Pull stores that permit the usage of browser toolbars.
topStores Pull the most recognizable and popular stores.
|
|
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 the following JSON output:
{
"content": [
{
"id": 1,
"name": "Demo Store",
"url": "https://www.demo-store.com/",
"seoFriendlyId": "demo-store",
"language": "en",
"description": "Demo description.",
"trackingUrl": "https://api.loyalize.com/v1/stores/1/tracking?cid=100&cp=",
"imageUrl": "https://api.loyalize.com/resources/stores/1/logo",
"commission": {
"value": 1.80,
"format": "%"
},
"commissionDetails": [
{
"name": "Hotels",
"commission": {
"value": 8,
"format": "%"
}
},
{
"name": "Flights",
"commission": {
"value": 2.50,
"format": "USD"
}
}
],
"home": "US",
"countries": [
"GLOBAL",
"US"
],
"categories": ["Demo Category"],
"storeTerms": "Not all purchases are eligible for cashback. Each store reserves the right
to exclude certain products or services from eligibility and you are subject to such
exclusions. Cashback is earned only on eligible purchases initiated using this platform.
To our knowledge, at Demo Store...",
"generalTerms": "Not all purchases are eligible for cashback. Each store reserves the right
to exclude certain products or services from eligibility and you are subject to such
exclusions. Cashback is earned only on eligible purchases initiated using this platform.",
"specificTerms": "To our knowledge, at Demo Store the following are not eligible for
cashback: laptops, tablets, desktops, video game and virtual reality hardware, computer
cards and components, COVID tests, all gift cards, and all Apple-branded products.
Additionally, Demo Store offers cashback only to new online customers."
}
],
"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
Parameter | Description |
---|---|
id | 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 the following JSON output:
{
"id": 1,
"name": "Demo Store",
"url": "https://www.demo-store.com/",
"seoFriendlyId": "demo-store",
"language": "en",
"description": "Demo description.",
"trackingUrl": "https://api.loyalize.com/v1/stores/1/tracking?cid=100&cp=",
"imageUrl": "https://api.loyalize.com/resources/stores/1/logo",
"commission": {
"value": 1.80,
"format": "%"
},
"commissionDetails": [
{
"name": "Hotels",
"commission": {
"value": 8,
"format": "%"
}
},
{
"name": "Flights",
"commission": {
"value": 2.50,
"format": "USD"
}
}
],
"home": "US",
"countries": [
"GLOBAL",
"US"
],
"categories": ["Demo Category"],
"storeTerms": "Not all purchases are eligible for cashback. Each store reserves the right
to exclude certain products or services from eligibility and you are subject to such
exclusions. Cashback is earned only on eligible purchases initiated using this platform.
To our knowledge, at Demo Store...",
"generalTerms": "Not all purchases are eligible for cashback. Each store reserves the right
to exclude certain products or services from eligibility and you are subject to such
exclusions. Cashback is earned only on eligible purchases initiated using this platform.",
"specificTerms": "To our knowledge, at Demo Store the following are not eligible for
cashback: laptops, tablets, desktops, video game and virtual reality hardware, computer
cards and components, COVID tests, all gift cards, and all Apple-branded products.
Additionally, Demo Store offers cashback only to new online customers."
}
Get Alternative Store Content
This endpoint retrieves alternative language content for a specific store, including description and terms.
HTTP Request
GET v1/stores/<ID>/alternative-content
import org.springframework.http.HttpEntity
import org.springframework.http.HttpHeaders
import org.springframework.http.HttpMethod
import org.springframework.web.client.RestTemplate
private static void getAlternativeStoreContent()
{
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/alternative-content",
HttpMethod.GET, httpEntity, String.class);
// convert responseAsJson to Java Objects
}
The above command returns the following JSON output:
[
{
"language": "fr",
"isDefault": false,
"description": "Description de démonstration.",
"storeTerms": "Toutes les achats ne sont pas éligibles pour le cashback. Chaque magasin se réserve le droit d’exclure certains produits ou services de l’éligibilité, et vous êtes soumis à ces exclusions.",
"generalTerms": "Le cashback est uniquement gagné sur les achats éligibles effectués via cette plateforme.",
"specificTerms": "Chez Demo Store, les articles suivants ne sont pas éligibles au cashback : ordinateurs portables, tablettes, ordinateurs de bureau, matériel de jeux vidéo et de réalité virtuelle, cartes-cadeaux et produits de marque Apple."
}
]
Store Search
This endpoint retrieves all stores that have the search term either in their name(s) or
description(s). For example, computer
returns such results as Microsoft, Newegg, Corsair, Logitech and Monoprice,
while gucci
returns such results as Bergdorf Goodman and Perfumania.
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 (up to 1,000). |
countries |
Pull stores that ship products to or provide services in a specific country or countries. Filtering by multiple
countries narrows down the output. Valid filter values are ISO 3166-1 alpha-2 country codes as well as a GLOBAL tag
indicating stores that service worldwide.
Examples:
GLOBAL US,CA GB,FR,DE |
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=target",
HttpMethod.GET, httpEntity, String.class);
// convert responseAsJson to Java Objects
System.out.println(responseAsJson);
}
}
The above command returns the following JSON output:
[
{
"id": 1,
"name": "Demo Store",
"url": "https://www.demo-store.com/",
"commission": {
"value": 1.80,
"format": "%"
},
"description": "Demo description.",
"language": "en",
"trackingUrl": "https://api.loyalize.com/v1/stores/1/tracking?cid=1&cp=",
"imageUrl": "https://api.loyalize.com/resources/stores/1/logo"
"countries": [
"GLOBAL",
"US"
]
},
...]
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 the following JSON output:
{
"storeId": 1,
"line1": "8311 West Roosevelt Road",
"line2": null,
"city": "Forest Park",
"region": "Illinois",
"zip": "60130",
"country": "United States"
}
Logos
This is how you can retrieve store logos.
HTTP Request
GET
resources/stores/{store_id}/logo
Examples:
-
Walmart → Store ID
7283
logoresources/stores/7283/logo
-
Target → Store ID
1818
logoresources/stores/1818/logo
Click Data
Get Click Data
This endpoint retrieves such data as click IDs, click dates, store names, shopper IDs, optional SIDs, and transaction IDs where applicable.
HTTP Request
GET v2/clicks
Query Parameters
Parameter | Default | Description |
---|---|---|
page | 0 | Page number starting from 0 (zero). |
size | 20 | Number of results per page (up to 1,000). |
sort |
Sort by click date.
Examples:
clickDate,asc clickDate,desc |
|
shopperId | Filter click data by external shopper ID. | |
sid | Filter click data by SubID. | |
storeId | Filter click data by store ID. | |
storeName | Filter click data by store name. | |
clickDateStart, clickDateEnd | Filter click data by date range.
clickDateStart=YYYY-MM-DD clickDateEnd=YYYY-MM-DD |
import org.springframework.http.HttpEntity
import org.springframework.http.HttpHeaders
import org.springframework.http.HttpMethod
import org.springframework.web.client.RestTemplate
private static void getClickData()
{
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/clicks,
HttpMethod.GET, httpEntity, String.class);
// convert responseAsJson to Java Objects
}
The above command returns the following JSON output:
{
"content": [
{
"id": "0b42911e03a44fhj8fb117ffa817754b",
"clickDate": "2023-10-28T09:24:32.784948Z",
"storeName": "Demo Store 1",
"storeId": 1,
"shopperId": "56ac8010-240e-4b5c-8e95-cfd38529b9f9",
"sid": null,
"transactionId": null
},
{
"id": "a698b13fd1574a345186fc377d5833be",
"clickDate": "2023-10-27T21:02:19.705489Z",
"storeName": "Demo Store 2",
"storeId": 2,
"shopperId": "56ac8010-240e-4b5c-8e95-cfd38529b9f9",
"sid": null,
"transactionId": "2537"
}
],
"pageable": {
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"offset": 0,
"pageNumber": 0,
"pageSize": 20,
"unpaged": false,
"paged": true
},
"totalPages": 1,
"totalElements": 2,
"last": false,
"size": 20,
"number": 0,
"sort": {
"sorted": true,
"unsorted": false,
"empty": false
},
"numberOfElements": 20,
"first": true,
"empty": false
}
Get Data for a Specific Click
This endpoint retrieves data for a specific click.
HTTP Request
GET v2/clicks/<ID>
URL Parameters
Parameter | Description |
---|---|
id | ID of the click 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 getClickData()
{
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/clicks/1",
HttpMethod.GET, httpEntity, String.class);
// convert responseAsJson to Java Objects
}
The above command returns the following JSON output:
{
"id":"0b42911e03a44fhj8fb117ffa817754b",
"clickDate":"2023-10-28T09:24:32.784948Z",
"storeName":"Demo Store",
"storeId":1,
"shopperId":"56ac8010-240e-4b5c-8e95-cfd38529b9f9",
"sid":null,
"transactionId":null
}
User Tracking
Get All Stores and Get a Specific Store endpoints provide objects that contain the trackingUrl field, which has two mandatory and one optional query parameters.
Mandatory
v1/stores/1/tracking?cid=100&cp=shopper-id
Optional
v1/stores/1/tracking?cid=100&cp=shopper-id&sid=sub-id
- cid – Your Loyalize ID which is prefilled when your API key is used. Do not build links manually.
- cp - Unique identifier of a shopper in your environment (96-character limit), which must be passed on to Loyalize. Maps to Shopper ID in your Loyalize dashboard for tracked transactions.
- sid – Optional parameter that can be passed on to Loyalize (96-character limit). Allows to group and filter shoppers based on applications used if there are multiple use cases.
-
cp=shopper-1
https://api.loyalize.com/v1/stores/1/tracking?cid=100&cp=shopper-1
-
cp=shopper-1, sid=mobile-app
https://api.loyalize.com/v1/stores/1/tracking?cid=100&cp=shopper-1&sid=mobile-app
-
cp=shopper-1, sid=website
https://api.loyalize.com/v1/stores/1/tracking?cid=100&cp=shopper-1&sid=website
Transactions
Get All Transactions
This endpoint retrieves all transactions.
HTTP Request
GET v2/transactions
Query Parameters
Parameter | Default | Description |
---|---|---|
ids | Filter transactions by one or more IDs. | |
page | 0 | Page number starting from 0 (zero). |
size | 20 | Number of results per page (up to 1,000). |
shopperId | Filter transactions by external shopper ID. | |
sid | Filter transactions by one or more SubIDs. | |
storeId | Filter transactions by store ID. | |
status | Filter transactions by status. Available values are: PENDING, AVAILABLE, PAYMENT_INITIATED, PAID, NON_COMMISSIONABLE | |
currency | Filter transactions by currency. | |
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. |
|
adminComment | Comments on transactions with missing cashback values. |
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 the following JSON output:
{
"content": [
{
"id": 1,
"sid": "sub-id-1",
"shopperId": "56ac8010-240e-4b5c-8e95-cfd38529b9f9",
"storeId": 1,
"storeName": "Demo Store",
"orderNumber": "demo-order-number",
"status": "PENDING",
"currency": "USD",
"saleAmount": 1000,
"shopperCommission": 120,
"tier": "T1",
"purchaseDate": "2020-09-01T15:10:45Z",
"pendingDate": "2020-09-01T15:10:45Z",
"availabilityDate": null,
"paymentDate": null,
"adminComment": "Non-commissionable action",
"lastUpdate": "2020-09-01T15:10:45Z",
"isSkuDetailsBrand": true
}
],
"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 Transaction
This endpoint retrieves a specific transaction.
HTTP Request
GET v2/transactions/<ID>
URL Parameters
Parameter | Description |
---|---|
id | ID of the transaction 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 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/1",
HttpMethod.GET, httpEntity, String.class);
// convert responseAsJson to Java Objects
}
The above command returns the following JSON output:
{
"id": 1,
"sid": "sub-id-1",
"shopperId": "56ac8010-240e-4b5c-8e95-cfd38529b9f9",
"storeId": 1,
"storeName": "Demo Store",
"orderNumber": "demo-order-number",
"status": "PENDING",
"currency": "USD",
"saleAmount": 1000,
"shopperCommission": 120,
"tier": "T1",
"purchaseDate": "2020-09-01T15:10:45Z",
"pendingDate": "2020-09-01T15:10:45Z",
"availabilityDate": null,
"paymentDate": null,
"adminComment": "Non-commissionable action",
"lastUpdate": "2020-09-01T15:10:45Z",
"isSkuDetailsBrand": true
}
SKU Details
This call retrieves store logos.
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 (up to 1,000). |
transactionId | Filter SKU data for a specific transaction. | |
startDate | Set the reporting period start date. | |
endDate | Set the reporting period end 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 the following JSON output:
{
"content": [
{
"transactionId": 1,
"sku": "demo-sku-value",
"itemName": "Demo Item",
"category": "Demo",
"quantity": 1,
"price": "20.54",
"shopperId": "shopper-id",
"orderNumber": "demo-order-nr",
"purchaseDate": "2022-09-09T12:46:20Z",
"storeName": Demo Store,
}
],
"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,
}
Webhooks
New Transaction
Get notifications on new transactions.
{
"body": {
"eventType": "NEW_TRANSACTION",
"data": {
"transactions": [1],
"changes": {
"newStatus": "PENDING"
}
}
}
}
Parameter | Description |
---|---|
eventType | Event type name |
data | Event related data |
transactions | ID(s) of new transaction(s) |
changes | New transactions are assigned the PENDING status by default |
Transaction Status Update
Get notifications on updates to transaction status(es).
{
"body":{
"eventType":"TRANSACTION_STATUS_UPDATE",
"data":{
"transactions":[1],
"changes":{
"newStatus":"AVAILABLE",
"oldStatus":"PENDING"
}
}
}
}
Parameter | Description |
---|---|
eventType | Event type name |
data | Event related data |
transactions | IDs of transactions with status updates. A single ID will be returned for updates involving PENDING, AVAILABLE, and NON_COMMISSIONABLE statuses. Multiple IDs may be returned for updates involving PAYMENT_INITIATED and PAID statuses. |
changes | Updates to transactions are reflected in newStatus and oldStatus fields |
Cashback Value Change
Get notifications on changes to transaction cashback values.
{
"body":{
"eventType":"CASHBACK_VALUE_CHANGE",
"data":{
"transactions":[1],
"changes":{
"newCashbackValue":"0.17",
"oldCashbackValue":"0.16",
"newSaleAmount":"18.49",
"oldSaleAmount":"18.48"
}
}
}
}
Parameter | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|
eventType | Event type name | |||||||||
data | Event related data | |||||||||
transactions | ID of a transaction with changes to cashback values | |||||||||
changes | Updates to a PENDING transaction as they relate to the Transactions endpoint
|
Store Added
Get notifications on new store availability.
{
"body": {
"eventType": "STORE_ADDED",
"data": [{
"id": 16811,
"name": "OutdoorMaster"
},{
"id": 29925,
"name": "Ritche Watch Bands"
}]
}
}
Parameter | Description |
---|---|
eventType | Event type name |
data | Event related data presented as an array of objects where each id matches the ID of an added store |
Store Removed
Get notifications on removal of stores.
{
"body": {
"eventType": "STORE_REMOVED",
"data": [{
"id": 552,
"name": "CreditRepair.com"
},{
"id": 19752,
"name": "Formula"
},{
"id": 20760,
"name": "RealSteel Center"
}]
}
}
Parameter | Description |
---|---|
eventType | Event type name |
data | Event related data presented as an array of objects where each id matches the ID of a removed store |
Store Cashback Change
Get notifications on changes to store cashback values.
{
"body": {
"eventType": "STORE_CASHBACK_CHANGE",
"data": [
{
"id": 1,
"name": "Demo Store",
"newCashback": {
"value": "12.0",
"format": "%"
},
"oldCashback": {
"value": "5.0",
"format": "%"
}
}
]
}
}
Parameter | Description |
---|---|
eventType | Event type name |
data | Event related data |
id | ID of a store with changes to cashback values |
name | Name of a store with changes to cashback values |
newCashback | Updated store cashback value |
oldCashback | Previous store cashback value |
Store Terms Change
Get notifications on changes to store terms.
{
"body": {
"eventType": "STORE_TERMS_CHANGE",
"data": [
{
"id": 1,
"name": "Demo Store",
"newTerms": "To our knowledge, at Demo Store, cashback is not available on the purchase of gift cards.",
"oldTerms": null
}
]
}
}
Parameter | Description |
---|---|
eventType | Event type name |
data | Event related data |
id | ID of a store with changes to terms |
name | Name of a store with changes to terms |
newTerms |
Updated store terms |
oldTerms |
Previous store terms |
Store Country Change
Get notifications on changes to store serviceable areas.
{
"body": {
"eventType": "STORE_COUNTRY_CHANGE",
"data": [
{
"id": 1,
"name": "Demo Store",
"newCountries": [
"US",
"CA"
],
"oldCountries": [
"US"
]
}
]
}
}
Parameter | Description |
---|---|
eventType | Event type name |
data | Event related data |
id | ID of a store with changes to serviceable areas |
name | Name of a store with changes to serviceable areas |
newCountries |
Updated store serviceable areas |
oldCountries |
Previous store serviceable areas |
Errors
The Loyalize.com API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request – Request is invalid. |
401 | Unauthorized – API key is wrong. |
404 | Not Found – Specified resource cannot be found. |
500 | Internal Server Error – There was a problem with our server. Try again later. |
503 | Service Unavailable – Temporarily offline for maintenance. Please try again later. |
Postman Collection
File | Download
|
---|