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_keywith 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: automotiveautomotive,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
| 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 ..."
}
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. |
| apiuId | Get one transaction by apiu transaction id. | |
| shopperId | Filter transactions by the external shopper id | |
| 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,
"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 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. |