### HTTP Request Example: Get All Stores

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/member-registartion-configuration

An example HTTP/1.1 request to retrieve a list of all stores from the OpenLoyalty API. This request requires an `Authorization` header with a valid API key.

```HTTP
GET /api/store HTTP/1.1
Host: openloyalty.localhost
Authorization: YOUR_API_KEY
Accept: */*
```

--------------------------------

### Successful Response Example: Get All Stores (JSON)

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/member-registartion-configuration

A sample JSON response body for a successful `GET /api/store` request, showing the structure of an individual store item and pagination metadata.

```JSON
{
  "items": [
    {
      "storeId": "123e4567-e89b-12d3-a456-426614174000",
      "code": "text",
      "currency": "text",
      "name": "text",
      "active": true,
      "createdAt": "2025-06-15T07:31:11.546Z",
      "updatedAt": "2025-06-15T07:31:11.546Z",
      "createdBy": "text",
      "updatedBy": "text"
    }
  ],
  "total": {
    "all": 1,
    "filtered": 1,
    "estimated": true
  }
}
```

--------------------------------

### Successful Response Example: Campaign Creation

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/create-campaign

An example of the JSON response returned upon successful creation of a campaign, containing the unique campaign ID.

```JSON
{
  "campaignId": "00000000-0000-0000-0000-000000000000"
}
```

--------------------------------

### HTTP Request to Get All Webhook Events

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/add-webhook

Example HTTP/1.1 request to retrieve all available webhook events from the Open Loyalty API. Replace YOUR_API_KEY with a valid authorization token.

```HTTP
GET /api/{storeCode}/webhook/event HTTP/1.1
Host: openloyalty.localhost
Authorization: YOUR_API_KEY
Accept: */*
```

--------------------------------

### HTTP Request Example: Add Member with Full Details

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/add-member

This snippet provides a complete HTTP/1.1 request example for adding a new member. It demonstrates the use of the POST method, host, authorization header, content type, and a comprehensive JSON request body including various customer details like address, company, labels, and agreements.

```HTTP
POST /api/{storeCode}/member HTTP/1.1
Host: openloyalty.localhost
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 526

{
  "customer": {
    "referrerToken": "text",
    "firstName": "text",
    "lastName": "text",
    "gender": "male",
    "email": "text",
    "phone": "text",
    "loyaltyCardNumber": "text",
    "birthDate": "2025-06-14",
    "registeredAt": "2025-06-14T09:14:09.344Z",
    "address": {
      "street": "text",
      "address1": "text",
      "address2": "text",
      "postal": "text",
      "city": "text",
      "province": "text",
      "country": "text"
    },
    "company": {
      "name": "text",
      "nip": "text"
    },
    "labels": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "agreement1": true,
    "agreement2": true,
    "agreement3": true,
    "levelId": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

--------------------------------

### Successful Response for Get All Webhook Events

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/add-webhook

Example JSON response body for a successful GET /api/{storeCode}/webhook/event request, showing a list of available event names.

```JSON
{
  "items": [
    "text"
  ]
}
```

--------------------------------

### HTTP 200 OK Response Body Example

Source: https://help.openloyalty.io/technical-guide/api-fundamentals/how-to-query

Provides an example of a successful HTTP 200 response body, typically containing an identifier for a newly created or modified resource, indicating the operation was successful and the resource is available.

```JSON
{
  "customEventId": "00000000-0000-0000-0000-000000000000"
}
```

--------------------------------

### Combined API Query with Sorting, Filtering, and Pagination

Source: https://help.openloyalty.io/technical-guide/api-fundamentals/how-to-query

An example demonstrating how to combine multiple query parameters—pagination, filtering by document type and email, and sorting by document type—into a single GET request to the API endpoint.

```APIDOC
GET /api/DEFAULT/transaction?_page=1&_itemsOnPage=10&header:documentType[eq]=XY&customerData:email[eq]=ol@example.com&_orderBy[header:documentType]=asc
```

--------------------------------

### Referrer Token URL Format Example

Source: https://help.openloyalty.io/faq/referral-programs

This example demonstrates how a referrer token can be embedded into a URL. When a new member clicks this link and completes registration, Open Loyalty receives the referrer token and links it to the new member's account, enabling referral tracking.

```APIDOC
https://examplelink.com/invite?referrerToken=XYZ123
```

--------------------------------

### Example Successful Response for Create Achievement

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/create-campaign-1

A sample JSON response returned upon successful creation of an achievement, containing the newly generated achievement ID.

```JSON
{
  "achievementId": "00000000-0000-0000-0000-000000000000"
}
```

--------------------------------

### Loyalty Campaign Configuration: Register and Get Bonus Points

Source: https://help.openloyalty.io/sample-setups/sample-campaigns/7-register-to-the-program-and-get-50-bonus-points

This snippet outlines the default configuration for a direct loyalty campaign. It specifies the trigger event as 'Member was activated' and defines the effect of giving 50 points to the 'Points wallet' without any specific conditions.

```APIDOC
Campaign type: Direct
Campaign trigger: Account activation (Internal event -> Event type: Member was activated)
Rules:
  Conditions: None
  Effects: Give 50 points (Add units -> Wallet type: Points wallet -> Calculation formula: 50)
```

--------------------------------

### HTTP Request Example: Create Campaign with JSON Body

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/create-campaign

A sample HTTP POST request demonstrating how to create a new campaign, including required headers and a detailed JSON payload for a 'direct' campaign type.

```HTTP
POST /api/{storeCode}/campaign HTTP/1.1
Host: openloyalty.localhost
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 776

{
  "campaign": {
    "translations": {
      "en": {
        "name": "text",
        "description": "text"
      },
      "pl": {
        "name": "text",
        "description": "text"
      }
    },
    "displayOrder": 1,
    "type": "direct",
    "trigger": "transaction",
    "triggerStrategy": {
      "type": "daily"
    },
    "activity": {
      "startsAt": "2025-06-14T09:16:22.526Z",
      "endsAt": "2025-06-14T09:16:22.526Z"
    },
    "labels": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "visibility": {
      "target": "segment"
    },
    "audience": {
      "target": "segment"
    },
    "active": true,
    "rules": [
      {
        "name": "text",
        "description": "text",
        "effects": [
          {
            "effect": "give_points",
            "data": {}
          }
        ],
        "conditions": [
          {
            "attribute": "text",
            "operator": "expression"
          }
        ]
      }
    ],
    "limits": {
      "points": {
        "interval": {
          "type": "days",
          "value": 1
        },
        "value": 1
      },
      "pointsPerMember": {
        "interval": {
          "type": "days",
          "value": 1
        },
        "value": 1
      },
      "executionsPerMember": {
        "interval": {
          "type": "days",
          "value": 1
        },
        "value": 1
      }
    }
  }
}
```

--------------------------------

### HTTP Request Example for Adding a Transaction

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/add-transaction

An example of an HTTP POST request to the /api/{storeCode}/transaction endpoint, including necessary headers (Host, Authorization, Content-Type, Accept, Content-Length) and a comprehensive transaction request body.

```HTTP
POST /api/{storeCode}/transaction HTTP/1.1
Host: openloyalty.localhost
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 651

{
  "transaction": {
    "items": [
      {
        "sku": "text",
        "name": "text",
        "quantity": 1,
        "grossValue": 1,
        "category": "text",
        "maker": "text",
        "labels": [
          {
            "key": "text",
            "value": "text"
          }
        ]
      }
    ],
    "header": {
      "documentNumber": "text",
      "documentType": "sell",
      "linkedDocumentNumber": "text",
      "purchasedAt": "2025-06-14T23:48:03.040Z",
      "purchasePlace": "text",
      "labels": [
        {
          "key": "text",
          "value": "text"
        }
      ]
    },
    "customerData": {
      "customerId": "text",
      "name": "text",
      "email": "text",
      "phone": "text",
      "loyaltyCardNumber": "text",
      "nip": "text",
      "address": {
        "street": "text",
        "address1": "text",
        "address2": "text",
        "postal": "text",
        "city": "text",
        "province": "text",
        "country": "text"
      }
    },
    "channelId": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

--------------------------------

### Check for labels on transactions or customers

Source: https://help.openloyalty.io/main-features/expressions/expression-examples

These expressions demonstrate how to check if a transaction or customer object has a specific label. The first example checks for a label key 'k1', while the second checks for a label key 'k1' with a value 'v1'.

```JSON
{
"operator": "expression",
"data": "agg(transaction.labels).matchLabel('k1')"
}

{
"operator": "expression",
"data": "agg(customer.labels).matchLabel('k1', 'v1')"
}
```

--------------------------------

### Steps to Add a Reward in Admin Panel

Source: https://help.openloyalty.io/main-features/rewards/reward-list/creating-reward

A step-by-step guide on how to add a new reward within the Admin Panel, including navigation, required fields, and activation. It also clarifies the distinction between Reward Activity and Reward Visibility.

```APIDOC
To add a Reward:
1. Go to the Rewards -> List of Rewards
2. Click ADD REWARD
3. Choose the Reward type
4. Fill in all required fields
5. Set Reward status to Active
6. Click ADD REWARD

In the Rewards section, we have two separate settings:
- Reward Activity: period of time that the reward might be acquired with units.
- Reward Visibility: period of time that the reward is visible to the targeted Members.

Then we define a reward as available in OL if the following is true:
Period of time that reward is visible, Period of time that it is active, Target is matched with member's segment or tier.
```

--------------------------------

### Example HTTP Request to Create Achievement

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/create-campaign-1

A sample HTTP/1.1 request demonstrating how to call the /api/{storeCode}/achievement endpoint with a JSON payload for creating a new achievement. This includes headers for host, authorization, content type, and content length, along with a detailed JSON body.

```HTTP
POST /api/{storeCode}/achievement HTTP/1.1
Host: openloyalty.localhost
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 430

{
  "achievement": {
    "translations": {
      "en": {},
      "pl": {}
    },
    "activity": {
      "operator": "is_after"
    },
    "active": true,
    "rules": [
      {
        "completeRule": {
          "period": {
            "type": {},
            "consecutive": 1
          }
        },
        "aggregation": {
          "rule": "text",
          "type": "text"
        },
        "conditions": [
          {
            "attribute": "text",
            "operator": "expression"
          }
        ],
        "translations": {
          "en": {
            "name": "text",
            "description": "text"
          }
        },
        "event": "text",
        "uniqueReferee": true
      }
    ],
    "limit": {
      "value": 1,
      "interval": {
        "type": "calendarHours",
        "value": 1
      }
    }
  }
}
```

--------------------------------

### API Filtering Example: Using the 'IN' Operator

Source: https://help.openloyalty.io/technical-guide/api-fundamentals/how-to-query

Illustrates how to use the 'IN' operator in a GET request to filter redemption statuses, allowing for multiple possible values like 'approved' or 'issued'. This narrows down search results for specific groups or conditions.

```APIDOC
GET /api/{store}/redemption?status[in]=approved,issued
```

--------------------------------

### HTTP Request to Create Webhook Subscription

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/add-webhook

Example HTTP/1.1 request to create a new webhook subscription. Replace YOUR_API_KEY with a valid authorization token and customize the JSON body with the desired eventName, url, and optional headers.

```HTTP
POST /api/{storeCode}/webhook/subscription HTTP/1.1
Host: openloyalty.localhost
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 112

{
  "webhookSubscription": {
    "eventName": "text",
    "url": "text",
    "headers": [
      {
        "headerName": "text",
        "headerValue": "text"
      }
    ]
  }
}
```

--------------------------------

### API Reference: Get All Stores

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/member-registartion-configuration

This API endpoint retrieves a complete list of all created stores in the OpenLoyalty system. Results can be sorted using the `_orderBy` query parameter and filtered by various criteria such as name, code, currency, and active status. Pagination is also supported.

```APIDOC
Endpoint: GET /api/store
Description: This method returns a list of all created Stores in the system. If sorting is not chosen, the rows will be returned in an unspecified order. To sort a result, use an `_orderBy` parameter in query.
Host: http://openloyalty.localhost

Query Parameters:
- name (string, Optional): Filter by store name.
- code (string, Optional): Filter by store code.
- currency (string, Optional): Filter by store currency.
- active (boolean, Optional): Filter by store active status.
- _page (integer, Optional): Page number for pagination.
- _itemsOnPage (integer, Optional): Number of items per page (Maximum supported value is 50).
- _orderBy (string, Optional): Field to sort results by.

Responses:
- 200 OK (application/json):
  Description: List of stores.
  Schema:
    items (array of objects):
      storeId (string): Unique identifier of the store.
      code (string): Store code.
      currency (string): Store currency.
      name (string): Store name.
      active (boolean): Store active status.
      createdAt (string, date-time): Timestamp of creation.
      updatedAt (string, date-time): Timestamp of last update.
      createdBy (string): User who created the store.
      updatedBy (string): User who last updated the store.
    total (object):
      all (integer): Total number of items.
      filtered (integer): Number of filtered items.
      estimated (boolean): Indicates if total is estimated.
- 400 Bad Request (application/json):
  Description: Bad request.
- 401 Unauthorized (application/json):
  Description: Error.
- 403 Forbidden (application/json):
  Description: Forbidden.
```

--------------------------------

### API Endpoint: GET Member Rewards

Source: https://help.openloyalty.io/whats-new/2022

Fix for an issue where targets were not considered when displaying rewards for test data via the GET member/{member}/reward endpoint.

```APIDOC
GET member/{member}/reward
```

--------------------------------

### Successful Response for Create Webhook Subscription

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/add-webhook

Example JSON response body for a successful POST /api/{storeCode}/webhook/subscription request, returning the ID of the newly created webhook subscription.

```JSON
{
  "webhookSubscriptionId": "00000000-0000-0000-0000-000000000000"
}
```

--------------------------------

### OpenLoyalty Unit Transfer Import File Structure

Source: https://help.openloyalty.io/main-features/wallets/unit-transfers/importing-unit-transfers

Details the required and optional fields for JSON or XML files used to import unit transfers into OpenLoyalty, including customer identification, unit values, wallet types, and date specifications.

```APIDOC
OpenLoyalty Unit Transfer Import File Fields:

- Customer ID (required)
  Description: The unique identifier of the loyalty account to which the transfer applies. Use the identifier generated by Open Loyalty.

- Units (points) (required)
  Description: The number of units that need to be added or deducted.

- Wallet (walletTypeCode) (required)
  Description: The code of the wallet the units need to be added to or deducted from.

- Date (registeredOn) (optional)
  Description: The date of the transfer, typically in YYYY-MM-DD HH:mm:ss format. If not specified, the registeredOn date will be saved as the date of unit transfer creation.

- Expire Date (optional)
  Options:
    - expireAt: Specifies the exact date and time of expiry.
    - expiresInDays: Indicates how many days from the registration date the units will remain available.

- Pending Date (optional)
  Options:
    - lockedUntilDays: Indicates how many days from the registration date the units will remain pending (locked).

- Comment (optional)
  Description: Any additional text or comments about this unit transfer.
```

--------------------------------

### Check transaction item by label key and quantity

Source: https://help.openloyalty.io/main-features/expressions/expression-examples

This expression verifies if a transaction item possesses a specific label key 'k1' and if its quantity is greater than 2.

```JSON
{
"operator": "expression",
"data": "transaction.itemLabel('k1').qty > 2"
}
```

--------------------------------

### API Endpoints: New Fields for Member History and Redemption

Source: https://help.openloyalty.io/whats-new/2024

New fields have been added to the GET /api/{storeCode}/member/{member}/history and GET /api/{storeCode}/redemption/{issuedReward} API endpoints.

```APIDOC
GET /api/{storeCode}/member/{member}/history
GET /api/{storeCode}/redemption/{issuedReward}
```

--------------------------------

### API Documentation: Get All Webhook Events

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/add-webhook

This API endpoint allows retrieval of a list of all available webhook events in the Open Loyalty system. It requires a store code as a path parameter and supports authorization via an API key. A successful response returns a JSON array of event names.

```APIDOC
Endpoint: GET /api/{storeCode}/webhook/event
Host: openloyalty.localhost
Authorizations:
  - API_KEY (Header: Authorization)
Path Parameters:
  storeCode:
    Type: string
    Required: true
    Description: Store code
Responses:
  200:
    Description: List of webhook events
    Content-Type: application/json
    Body:
      items:
        Type: array
        Items: string
        Example: ["text"]
  401:
    Description: Error
    Content-Type: application/json
  403:
    Description: Forbidden.
    Content-Type: application/json
```

--------------------------------

### Successful Transaction Registration Response

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/add-transaction

Example JSON response returned upon successful registration of a new transaction, containing the unique transaction ID.

```JSON
{
  "transactionId": "00000000-0000-0000-0000-000000000000"
}
```

--------------------------------

### Create Custom Event HTTP Request

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/add-custom-event

Full HTTP POST request example for creating a custom event, including headers for authorization and content type, and a sample JSON body. This demonstrates how to interact with the custom event API endpoint.

```HTTP
POST /api/{storeCode}/customEvent HTTP/1.1
Host: openloyalty.localhost
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 213

{
  "event": {
    "type": "text",
    "customerData": {
      "customerId": "7239e6f7-e52e-466b-8c24-699709b64076",
      "email": "text",
      "phone": "text",
      "loyaltyCardNumber": "text"
    },
    "eventDate": "2025-06-14T22:12:35.840Z",
    "body": {
      "key": "value"
    }
  }
}
```

--------------------------------

### Custom Event JSON Payload Example

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/add-custom-event

Example JSON body for a custom event, including event type, date, and customer data. This payload is sent to the custom event endpoint to trigger actions like achievement progress.

```JSON
{
  "event": {
    "type": "app_login",
    "eventDate": "2024-05-01T00:00:00",
    "customerData": {
      "email": "john.smith@example.com"
    }
  }
}
```

--------------------------------

### Check transaction item by label key-value and quantity

Source: https://help.openloyalty.io/main-features/expressions/expression-examples

This expression checks if a transaction item has a specific label with key 'k1' and value 'v1', and if its quantity exceeds 2.

```JSON
{
"operator": "expression",
"data": "transaction.itemLabel('k1', 'v1').qty > 2"
}
```

--------------------------------

### HTTP Request to Create Custom Event Schema

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/add-custom-event-schema

An example of an HTTP POST request to create a custom event schema, including headers for authorization and content type, and a sample JSON body.

```HTTP
POST /api/{storeCode}/customEvent/schema HTTP/1.1
Host: openloyalty.localhost
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 129

{
  "customEventSchema": {
    "eventType": "text",
    "schema": {
      "fields": [
        {
          "type": "text",
          "description": "text",
          "name": "text"
        }
      ]
    },
    "name": "text"
  }
}
```

--------------------------------

### OpenLoyalty: Example Usage of percent_value_distribution

Source: https://help.openloyalty.io/main-features/campaigns/creating-campaigns/percent-value-distribution

Illustrates how to use the 'percent_value_distribution' function to apply different reward percentages based on transaction value ranges (e.g., 1% for 0-5000, 1.2% for 5000-7500, 1.5% for 7500-10000, and 0% above 10000).

```OpenLoyalty Expression
percent_value_distribution(event.body.progressChanges[0], [5000, 7500, 10000], [0.01, 0.012, 0.015, 0], event.body.progressStatuses[0].currentPeriodValue - event.body.progressChanges[0])
```

--------------------------------

### API Best Practice: Pagination and Filtering

Source: https://help.openloyalty.io/technical-guide/api-fundamentals/best-practices

Strategies for managing large datasets using pagination and enabling efficient data access through query parameters for filtering, sorting, and searching. For example, use "_itemsOnPage" and "_page" parameters.

```APIDOC
Pagination:
  - Break large data sets into smaller, manageable chunks.
  - Example Parameters:
    - _itemsOnPage: Controls the number of records returned.
    - _page: Controls the starting position within the data set.
Filtering, Sorting, and Searching:
  - Implement query parameters to help clients access relevant data efficiently.
```

--------------------------------

### Sum quantities of all transaction items

Source: https://help.openloyalty.io/main-features/expressions/expression-examples

This expression aggregates all items within a transaction and sums their quantities, then checks if the total sum is greater than 2.

```JSON
{
"operator": "expression",
"data": "agg(transaction.items).sumBy('qty') > 2"
}
```

--------------------------------

### Admin Login Successful Response

Source: https://help.openloyalty.io/technical-guide/authentication/admin-token

Example JSON response from the `/api/admin/login_check` endpoint upon successful authentication, providing a JWT token and a refresh token.

```JSON
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI...",
  "refresh_token": "def50200a2e8c9a2..."
}
```

--------------------------------

### Transaction Item Filtering and Aggregation Examples

Source: https://help.openloyalty.io/main-features/expressions/attributes-list

Illustrates how to filter and aggregate transaction items based on specific scenarios, returning total gross value or quantity.

```APIDOC
agg(filter(transaction.items,'scenario_1')).sumBy('grossValue'): Returns the total gross value of all items in the transaction that match scenario_1.
agg(filter(transaction.items,'scenario_1')).sumBy('qty'): Returns the total quantity of items in the transaction that match scenario_1.
```

--------------------------------

### Create Achievement API Request Body

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/create-campaign-1

Example JSON request body for creating a new achievement via the API endpoint `POST /api/{storeCode}/achievement`. This specific achievement monitors a member's login streak over the past 7 days, allowing for a single completion and engaging customers through gamification elements.

```json
{
    "achievement": {
        "active": true,
        "translations": {
            "en": {
                "name": "Maintain a 7-day login streak",
                "description": "Challenge members to achieve milestones within a custom event. This is a non-transactional achievement that engages customers through gamification elements."
            }
        },
        "limit": {
            "value": 1
        },
        "activity": {
            "data": null,
            "operator": ""
        },
        "rules": [
            {
                "aggregation": {
                    "type": "quantity"
                },
                "completeRule": {
                    "period": {
                        "type": "last_day",
                        "value": 7
                    },
                    "periodGoal": 1
                },
                "conditions": [],
                "event": "app_login",
                "limit": {
                    "interval": {
                        "type": "calendarDays",
                        "value": 1
                    },
                    "value": 1
                },
                "trigger": "custom_event",
                "type": "direct",
                "translations": {
                    "en": {
                        "name": "7-day login streak",
                        "description": ""
                    }
                }
            }
        ]
    }
}
```

--------------------------------

### API: Get All Webhook Subscriptions

Source: https://help.openloyalty.io/main-features/webhooks/configuration

This API endpoint allows retrieval of all webhook subscriptions for a given store. Results can be filtered and sorted using various query parameters such as URL, event name, or creation date. It returns a list of subscription objects or an error if unauthorized or forbidden.

```APIDOC
GET /api/{storeCode}/webhook/subscription
Description: Retrieve all webhook subscriptions for a given store.
Authorizations: API Key
Path Parameters:
  storeCode: string (Required) - Store code
Query Parameters:
  url: string (Optional)
  legacy: boolean (Optional)
  eventName: string (Optional)
  createdAt: string · date-time (Optional)
  _page: integer (Optional)
  _itemsOnPage: integer (Optional)
  _orderBy: string (Optional)
Responses:
  200: List of webhook subscriptions (application/json)
    Response Body:
      items: array of objects
        webhookSubscriptionId: string
        eventName: string
        url: string
        legacy: boolean
        createdAt: string · date-time
      total: object
        all: integer
        filtered: integer
  401: Error (application/json)
  403: Forbidden (application/json)
```

```HTTP
GET /api/{storeCode}/webhook/subscription HTTP/1.1
Host: openloyalty.localhost
Authorization: YOUR_API_KEY
Accept: */*
```

```json
{
  "items": [
    {
      "webhookSubscriptionId": "text",
      "eventName": "text",
      "url": "text",
      "legacy": true,
      "createdAt": "2025-06-14T09:16:22.526Z"
    }
  ],
  "total": {
    "all": 1,
    "filtered": 1
  }
}
```

--------------------------------

### Filter transaction items by maker, category, or SKU

Source: https://help.openloyalty.io/main-features/expressions/expression-examples

These expressions demonstrate how to filter transaction items based on specific attributes like the item's maker, category, or SKU, ensuring that at least one such item exists (quantity greater than 0).

```JSON
{
"operator": "expression",
"data": "transaction.maker('Company').qty > 0"
}

{
"operator": "expression",
"data": "transaction.category('C1').qty > 0"
}

{
"operator": "expression",
"data": "transaction.sku('AB1122').qty > 0"
}
```

--------------------------------

### Authenticate API Request with Access Token using Headers (cURL)

Source: https://help.openloyalty.io/technical-guide/authentication/access-token-api-key

This cURL command demonstrates how to authenticate an API GET request by including the Access Token in the 'X-AUTH-TOKEN' header. It specifies the API endpoint, HTTP method, and expected content type for a member resource.

```Shell
curl -L http://your-env-url/api/{storeCode}/member \
    -X "GET" -H "Accept: application/json" \
    -H "X-AUTH-TOKEN: customPermanentToken"
```

--------------------------------

### Webhook Body Example: Account Available Points Changed

Source: https://help.openloyalty.io/main-features/webhooks/configuration

This JSON structure represents the body of the 'account.available_points_amount_changed' webhook event. It provides detailed information about changes in a user's available points, including customer details, account ID, and the amount of change. This body can serve as a trigger for custom actions on the user's application side.

```json
{
"eventName": "string",
"storeCode": "string",
"createdAt": "2019-08-24T14:15:22Z",
"data": {
"customer": {},
"accountId": "string",
"amount": null,
"amountChange": null,
"amountChangeType": "string",
"wallet": {}
}
}
```

--------------------------------

### API Endpoint: GET Reward Photo

Source: https://help.openloyalty.io/whats-new/2022

Error handling added for the GET /api/DEFAULT/reward/{rewardId}/photo/{photoId} endpoint, which previously returned a 500 error when an image was not found.

```APIDOC
GET /api/DEFAULT/reward/{rewardId}/photo/{photoId}
```

--------------------------------

### Retrieve All OpenLoyalty System Settings

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/member-registartion-configuration

This API endpoint allows authenticated users to retrieve all system settings for a specified store. Results can be optionally sorted using the `_orderBy` query parameter. The response includes a JSON object containing an array of settings.

```APIDOC
Method: GET
Endpoint: http://openloyalty.localhost/api/{storeCode}/settings
Description: Returns all system settings. Sorting can be applied using the `_orderBy` query parameter.
Authorizations: Required
Path Parameters:
  storeCode:
    Type: string
    Required: true
    Description: Store code
Query Parameters:
  public:
    Type: boolean
    Optional: true
Responses:
  200 Success:
    Content-Type: application/json
    Description: Response object containing settings.
  403 Forbidden:
    Content-Type: application/json
  404 Not Found:
    Content-Type: application/json
```

```HTTP
GET /api/{storeCode}/settings HTTP/1.1
Host: openloyalty.localhost
Authorization: YOUR_API_KEY
Accept: */*
```

```JSON
{
  "settings": [
    {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  ]
}
```

--------------------------------

### API Endpoint: Create New Campaign

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/create-campaign

Documents the POST /api/{storeCode}/campaign endpoint, including path parameters, request body options for different campaign types, and possible HTTP responses.

```APIDOC
API Endpoint: POST /api/{storeCode}/campaign
Description: This method allows creating a new Campaign.

Authorizations:
  - YOUR_API_KEY (Authorization header)

Path Parameters:
  - storeCode:
    Type: string
    Required: true
    Description: Store code

Request Body:
  Type: one of
  Options:
    - object: Campaign
      Description: Standard campaign object.
    - object: MultiReferralCampaign
      Description: When campaign is referral type, you can specified multi level.
    - object: UniqueCodeCampaign
      Description: Campaign triggered by a unique code from custom event.

Responses:
  - 200:
    Description: Return created campaign ID.
    Content-Type: application/json
    Schema: object (Responseobject)
  - 400:
    Description: Bad request.
    Content-Type: application/json
  - 401:
    Description: Error.
    Content-Type: application/json
  - 403:
    Description: Forbidden.
    Content-Type: application/json
  - 404:
    Description: Not found.
    Content-Type: application/json
```

--------------------------------

### Import Campaigns from JSON File

Source: https://help.openloyalty.io/main-features/campaigns/managing-campaigns

Outlines the procedure for importing single or multiple campaigns (up to 50) from a .json file. After import, review the list of successful and pending campaigns.

```Steps
1. Go to Campaigns -> List of Campaigns
2. Click ADD CAMPAIGN -> Import campaigns
3. Follow the instructions from the popup window.
4. Click IMPORT to download the campaign file
5. After importing the campaign you will see the list of all successful and/or campaigns that require the action to edit.
```

--------------------------------

### Storing Events with Tenant's Timezone Offset

Source: https://help.openloyalty.io/faq/timezones

This example illustrates how Open Loyalty stores event timestamps. When an event is sent without a timezone, it is stored with the tenant's assigned timezone offset, ensuring all data aligns with the tenant's local time. The example uses Europe/Berlin (CEST, UTC+02:00) as the tenant's timezone.

```APIDOC
If tenant's timezone is Europe/Berlin (CEST, UTC+02:00):
Input timestamp: 2025-05-13T14:40:10
Stored timestamp: 2025-05-13T14:40:10+02:00
```

--------------------------------

### API: Simulate Campaign Effects

Source: https://help.openloyalty.io/sample-setups/promo-and-discounts-in-cart

Details for the POST /api/{storeCode}/campaign/simulate endpoint, used to test transaction scenarios and calculate potential promo effects without finalizing a transaction. Includes sample request payload and response.

```APIDOC
Endpoint: POST /api/{storeCode}/campaign/simulate
Purpose: Simulate the transaction to calculate promo effects.
Key Response Data: Campaign effects such as discounts or units that can be tracked for promos applied.
```

```JSON
{
    "simulate": {
        "customer": {
            "email": "example@example.com"
        },
        "transaction": {
            "purchasedAt": "2024-12-23 12:00+01:00",
            "documentNumber": "HDKA_2024",
            "labels": [
                {
                    "key": "type",
                    "value": "simulation"
                }
            ],
            "items": [
                {
                    "name": "Book Bundle",
                    "sku": "1001C",
                    "grossValue": 200,
                    "highPrecisionQuantity": 2
                }
            ]
        },
        "trigger": "transaction"
    }
}
```

```JSON
{
    "effects": [
        {
            "type": "give_reward",
            "campaign": {
                "campaignId": "737b4a04-f03e-4441-99c3-f0f6b527c52e",
                "...": "...",
                "name": "Simulation Campaign",
                "...": "..."
            },
            "target": "self",
            "rewardId": "a2cd2a4b-5c98-4c04-8fb7-f500d0836ab2",
            "couponValue": 20.0
        },
        {
            "type": "give_points",
            "campaign": {
                "campaignId": "737b4a04-f03e-4441-99c3-f0f6b527c52e",
                "...": "...",
                "name": "Simulation Campaign",
                "...": "..."
            },
            "target": "self",
            "points": 180.0,
            "wallet": "default",
            "expression": "<#>transaction.grossValue</#>  *0.9"
        }
    ],
    "evaluationWarnings": []
}
```

--------------------------------

### Converting Events with External Timezones to Tenant's Timezone

Source: https://help.openloyalty.io/faq/timezones

This example demonstrates Open Loyalty's behavior when an event is sent with an explicitly specified timezone (e.g., UTC). The system automatically converts the incoming timestamp to the tenant's configured timezone, maintaining data consistency across the platform. The example uses Berlin (UTC+02:00) as the tenant's timezone.

```APIDOC
Input timestamp (UTC): 2025-05-13T12:40:10Z or 2025-05-13T12:40:10+00:00
Tenant timezone: Berlin (UTC+02:00)
Stored timestamp (converted): 2025-05-13T14:40:10+02:00
```

--------------------------------

### Admin Login Request Payload

Source: https://help.openloyalty.io/technical-guide/authentication/admin-token

Example JSON payload for the POST request to the `/api/admin/login_check` endpoint, used to authenticate an admin user with their credentials.

```JSON
{
  "username": "admin@example.com",
  "password": "password123"
}
```

--------------------------------

### API Reference: Register New Member (POST /api/{storeCode}/member)

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/add-member

Detailed API documentation for registering a new member as an Admin. This endpoint allows specifying various customer properties in the request body and requires an admin token for authorization. It returns the registered member's ID and email upon success.

```APIDOC
Method: post
URL: http://openloyalty.localhost/api/{storeCode}/member
Description: This method allows registering a new Member as an Admin.

Authorizations:
  - Admin token required

Path parameters:
  - storeCode: string (Required) - Store code

Body:
  - customer: all of (Optional) - object (Optional)
    - Show properties
  - and: object (Optional)
    - Show properties

Responses:
  - 200: Return registered member id and email.
    - application/json
    - Response: object
      - Show properties
  - 400: Bad request. (application/json)
  - 401: Unauthorized. (application/json)
  - 403: Forbidden. (application/json)
  - 404: Not found. (application/json)
```

--------------------------------

### Configure Multi-level Referral Campaign

Source: https://help.openloyalty.io/main-features/campaigns/creating-campaigns/referral-campaign

Detailed steps to set up a multi-level referral campaign, allowing rewards for multiple levels of referrers. This configuration helps in incentivizing wider audience reach and customizing rewards per level by setting specific conditions and effects for each referral level.

```Configuration Steps
1. Set the Campaign type: Referral campaign
2. Select Multi-level campaign
3. Select Referral max levels to the desired level, for example: 2
4. Set the campaign trigger to a desired event - Transaction, Internal event, Custom event, Achievement
5. If you selected Internal event, Select event type for example - Member was activated
6. Configure Rules for the Referrer and a Referee
7. Add conditions - to target specific levels choose - "Current referral level for multi-level campaign" for example,
   a. Rule 1 "Current referral level for multi-level campaign" is equal: 1
   b. Add Effect - action type - Add units - 100
   c. Rule 2 "Current referral level for multi-level campaign" is equal: 2
   d. Add Effect - action type - Add units - 50
```

--------------------------------

### Check achievement progress status

Source: https://help.openloyalty.io/main-features/expressions/expression-examples

This expression evaluates the progress of an achievement by checking if the current period value of the first progress status in the event body is non-negative.

```JSON
{
"operator": "expression",
"data": "event.body.progressStatuses[0].currentPeriodValue >= 0"
}
```

--------------------------------

### JSON Response Body: Successful Member Registration (200 OK)

Source: https://help.openloyalty.io/technical-guide/getting-started-guide/add-member

This JSON object represents the successful response (HTTP 200 OK) after registering a new member. It returns the unique customer ID and the email address of the newly registered member.

```JSON
{
  "customerId": "00000000-0000-0000-0000-000000000000",
  "email": "text"
}
```

--------------------------------

### OpenLoyalty Campaign Basic Settings Schema

Source: https://help.openloyalty.io/main-features/campaigns/creating-campaigns

This APIDOC entry describes the configurable properties for creating and managing campaigns in OpenLoyalty. It covers mandatory and optional fields such as campaign name, description, start/end dates, custom attributes, and various visibility options, which dictate how a campaign is displayed to users.

```APIDOC
Campaign:
  Campaign Name: string (required)
  Campaign Description: string (optional)
    + Translation: object (optional) - translations for name and description
  Start Date: date (mandatory)
  End Date: date (optional) - must be after Start Date if provided
  Campaign Attributes: object (optional) - extra data or for filtering purposes
  Campaign Visibility: enum (required)
    Visible to Everyone: The campaign is visible to all users.
    Segment or Tier Visibility: Select specific segments or tiers that can view the campaign.
    Hidden: The campaign remains hidden from all users.
```

--------------------------------

### API Capabilities and Limitations for Staging Environment

Source: https://help.openloyalty.io/technical-guide/api-fundamentals/environments-capabilities

Outlines the specifications for the Staging environment, designed for proof of concept and functional testing. It details the lack of uptime/SLA guarantees, limited resources, upgrade policies, API throughput limits, and restricted regional availability. Storing personally identifiable information (PII) is not recommended.

```APIDOC
Staging Environment:
  Uptime & SLA: No guaranteed uptime or SLA
  Resources: Limited, no scaling options
  Upgrades: Zero-downtime
  Data Privacy: Storing PII not recommended
  API Throughput:
    Concurrent Requests Per Second (RPS): Limited to 50 (soft limit)
    Exceptions:
      /api/admin/login_check: 20 requests per minute (RPM)
      /api/token/refresh: 20 requests per minute (RPM)
  Regional Availability:
    eu-west-1 (Dublin, Ireland)
    us-east-2 (Ohio, USA)
    ap-southeast-2 (Sydney, Australia)
```

--------------------------------

### Refresh Token Successful Response

Source: https://help.openloyalty.io/technical-guide/authentication/admin-token

Example JSON response from the `/api/token/refresh` endpoint after a successful token refresh, providing a new JWT token and a new refresh token.

```JSON
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI...",
  "refresh_token": "ghi78900b3f1c9d3..."
}
```

--------------------------------

### Refresh Token Request Payload

Source: https://help.openloyalty.io/technical-guide/authentication/admin-token

Example JSON payload for the POST request to the `/api/token/refresh` endpoint, used to obtain a new JWT and refresh token before the current JWT expires.

```JSON
{
  "refresh_token": "def50200a2e8c9a2..."
}
```

--------------------------------

### Adding Referral Relations via API

Source: https://help.openloyalty.io/main-features/members/referred-members

To refer a Member, you can do it via the API. This snippet shows an example of a referrer token that can be used in an API request to establish a referral relation.

```APIDOC
"referrerToken": "96HEJHGV9"
```

--------------------------------

### Reward Type Configuration Fields

Source: https://help.openloyalty.io/main-features/rewards/reward-list/creating-reward

Defines the fields available for configuring the type of reward, including material or coupon options, wallet type allowed for redemption, and pricing in both currency and points.

```APIDOC
Type of reward fields:
- Type of reward: choose whether it's material or coupon type
  - Material
  - Coupon
- Wallet type allowed for redemption: Wallet type you want to use for reward redemption
- Price in (currency): the price the Member gets upon receiving the Reward
- Reward price in Points: Units which the Member spent to redeem the Reward
```

--------------------------------

### Reward Basic Settings Fields

Source: https://help.openloyalty.io/main-features/rewards/reward-list/creating-reward

Describes the fundamental settings for a reward, such as its name, description, optional translations, availability and visibility periods, targeting options (everyone, specific segment, or tier), and global or per-member redemption limits.

```APIDOC
Basic settings fields:
- Name: the name of the Reward
- Description: brief description
- + TRANSLATION (optional): adding translations to the reward
- Reward availability: time when the Reward will be active to Members
- Reward visibility in the catalog: the time when the Reward will be visible to Members
- Reward targeting: identifies the Member group that qualifies to receive the Reward
  - Available for everyone
  - Available for a specific segment
  - Available for a specific tier
- Redemption limit: defines the global limit of how many times the reward can be redeemed.
- Redemption limit per member: defines the limit on how many times the reward can be redeemed per member
```

--------------------------------

### Export Campaigns to JSON File

Source: https://help.openloyalty.io/main-features/campaigns/managing-campaigns

Learn how to export single or multiple campaigns (up to 50) into a .json file. This process allows for backup or transfer of campaign configurations.

```Steps
1. Go to Campaigns -> List of Campaigns
2. Click SELECT TO EXPORT
3. Select the campaigns you want to export to the JSON file
4. Click EXPORT TO .JSON FILE (X) to download the campaign file
```

--------------------------------

### S3 Bucket Data Export Overall Structure

Source: https://help.openloyalty.io/technical-guide/s3-bucket-data-exports/data-structure-and-types

Describes the top-level folder structure within the AWS S3 bucket where analytics data is exported, starting with the main 'analytics/' prefix.

```APIDOC
analytics/
  - Main folder (prefix) for all analytics data. All data is organized under this folder.
```

--------------------------------

### Webhook: CampaignEffectWasApplied Data Enhancement

Source: https://help.openloyalty.io/whats-new

The `CampaignEffectWasApplied` webhook now includes additional business data from transactions and custom events, providing richer context for integrations.

```APIDOC
Webhook Name: CampaignEffectWasApplied
Description: Now includes business data from transactions and custom events.
```

--------------------------------

### Retrieve Member Custom Attribute Value

Source: https://help.openloyalty.io/main-features/expressions/sample-use-cases/using-member-custom-attributes

This snippet demonstrates how to retrieve the value of a specific custom attribute from a customer's labels. For example, it returns the value associated with the 'post_date' key.

```Expression Language
agg(customer.labels).getLabelValue('post_date')
```

--------------------------------

### API Query Pagination Parameters

Source: https://help.openloyalty.io/technical-guide/api-fundamentals/how-to-query

Details the parameters for controlling the number of items returned per request (`_itemsOnPage`, max 50) and specifying the page number (`_page`). These parameters help in navigating large datasets efficiently.

```APIDOC
_itemsOnPage=10
_page=2
```

--------------------------------

### Get Translation Key Details API

Source: https://help.openloyalty.io/main-features/settings/translations

Documents the API endpoint for retrieving a specific translation key and its values across all supported languages, including authorization, path parameters, and possible responses.

```APIDOC
Endpoint: GET /api/translation/key/{key}
Description: This method returns one Translation key and its value in all Languages supported.
Authorizations: Bearer Token
Path Parameters:
  - key (string, Required)
Responses:
  - 200 Success (application/json):
    Schema:
      [
        {
          "languageCode": "text",
          "key": "text",
          "value": "text",
          "updatedAt": "2025-06-15T07:31:11.546Z"
        }
      ]
  - 401 Unauthorized (application/json)
  - 403 Forbidden (application/json)
  - 404 Not found (application/json)
```

```HTTP
GET /api/translation/key/{key} HTTP/1.1
Host: openloyalty.localhost
Authorization: YOUR_API_KEY
Accept: */*

```

```JSON
[
  {
    "languageCode": "text",
    "key": "text",
    "value": "text",
    "updatedAt": "2025-06-15T07:31:11.546Z"
  }
]

```

--------------------------------

### Administration Component Instance-Wide Limits

Source: https://help.openloyalty.io/technical-guide/api-fundamentals/limits

Outlines the maximum capacities for administrative components across the entire Open Loyalty instance, including admins, roles, tenants (stores), and webhook subscriptions.

```APIDOC
Administration (entire instance):
  Admins: Max 100
  Roles: Max 20
  Tenants (Stores): Max 50
  Webhooks Subscription: Max 30
```

--------------------------------

### Date Functions API Reference

Source: https://help.openloyalty.io/main-features/expressions/custom-functions

Documents functions for date and time manipulation, including converting strings to dates, extracting day/month, checking date relationships (before, after, between), getting timestamps, and adding days/months/years to dates.

```APIDOC
to_date(string): datetime
day(datetime): string
day_of_month(datetime): int
month(datetime): string
is_after(valueDate, afterDate): bool
is_before(valueDate, beforeDate): bool
is_between(valueDate, beforeDate, afterDate): bool
is_not_between(valueDate, beforeDate, afterDate): bool
is_time_between(valueDate, beforeDate, afterDate): bool
timestamp(datetime): int
add_days_to_date(datetime, numberOfDays): datetime
add_months_to_date(datetime, numberOfMonths): datetime
add_years_to_date(datetime, numberOfYears): datetime
```

--------------------------------

### API Query Filtering Parameters

Source: https://help.openloyalty.io/technical-guide/api-fundamentals/how-to-query

Explains how to filter data using an operator-based format or a simplified equality filter. Multiple filters can be combined using the logical AND operator to refine search results.

```APIDOC
fieldName[OPERATOR]=value
fieldName=value
fieldName[OPERATOR]=value&fieldName2[OPERATOR]=value2
```

--------------------------------

### Parse Custom Attribute to Date

Source: https://help.openloyalty.io/main-features/expressions/sample-use-cases/using-member-custom-attributes

This example shows how to convert a custom attribute's string value into a date object using the 'to_date' function. This is essential for performing date-based comparisons or calculations.

```Expression Language
to_date(agg(customer.labels).getLabelValue('post_date'))
```