> ## Documentation Index > Fetch the complete documentation index at: https://docs.clearline.me/llms.txt > Use this file to discover all available pages before exploring further. # Loyalty Program These endpoints are used by POS systems to post transaction data into the ClearLine system.\ Based on this data, ClearLine identifies the customer and executes business rules to process it and apply Loyalty Program logic (calculate points, stamps, change user’s tier, grant rewards, etc.). 20251003_POS_integration.drawio.png 1. ClearLine retrieves its configuration from POS system using Get POS Settings 2. POS system initializes a session with Start POS Interaction 3. ClearLine sends a webhook with customer details (loyalty card, email, phone, name) for customer check-in 4. POS system posts transaction data into ClearLine using the Transaction endpoint; ClearLine applies loyalty logic (points, stamps, tier changes, rewards) 5. POS system can fetch customer coupons using couponCode/search 6. POS system can validate a coupon against a transaction using Validate Coupon by Transaction # 1. Transaction ## 1. Get POS Settings **Endpoint:**\ `GET https://apitest.clearline.me/v2/pos/{posSystemId}/settings/lookup` **Description:**\ Retrieves POS system settings.\ If the integration works only with one POS provider (**Cova**, **Clover**, or **Pax**), the response will contain settings only for that provider. **Path Parameters:** * `posSystemId` *(string, required)* – POS system identifier. ### Responses **200 (Success)** ``` { "data": { "companySettings": { "isCheckInMenuEnabled": true, "isTransactionsEnabled": true, "isPosRulesEnabled": true, "isReceiptPromotionEnabled": true, "isCouponsEnabled": true, "isProductsImportEnabled": true }, "notificationSettings": { "status": "Enabled", "channel": "PubNub", "configuration": { "publishKey": "pub-c-xxxxxxxxxxxxxxxxxxxxxxxxxx", "subscribeKey": "sub-c-xxxxxxxxxxxxxxxxxxxxxxxxxx", "terminalChannel": "pos_system_message-{terminalId}", "broadcastChannel": "pos_system_message-[all]" } } } ``` ### Response parameters | Field name | Description | | ------------------------- | -------------------------------------------------------------------------------- | | data | Data Block | | companySettings | Data Block | | isCheckInMenuEnabled | Identifies if CheckIn menu is enabled | | isTransactionsEnabled | Identifies if transaction synchronization enabled on this account | | isPosRulesEnabled | Identifies if automatic POS Rules enabled on this account | | isReceiptPromotionEnabled | Identifies if QR code generation enabled to print it on receipts on this account | | isCouponsEnabled | Identifies if Coupons are enabled | | isProductsImportEnabled | Identifies if automatic Product Catalog import enabled on this account | | notificationSettings | Data Block | | status | Status of notifications \[Enabled, Disabled] | | channel | Identifies the notification channel \[None, Webhook, PubNub] | | configuration | Data Block (PubSub sample) | | publishKey | Publish key | | subscribeKey | Subscribe key | | terminalChannel | Terminal channel, used to send messages to a specific terminal | | broadcastChannel | Broadcast channel, used to send messages to all terminals on the account | ## 2. Start POS Interaction **Endpoint:**\ `POST https://apitest.clearline.me/pos/{posSystemId}/startInteraction` **Description:**\ Initializes a POS session with ClearLine. **Path Parameters:** * `posSystemId` *(string, required)* – POS system identifier. ### Example Request ``` { "terminalId": "string", "posLocationId": "string" } ``` ### Example Response (200 Success) ``` { "data": { "terminalId": "string", "posLocationId": "string", "sessionId": "string", "posStatus": "Accepted" } } ``` **Schema:** * `StartInteractionRequestDto` * `terminalId` *(string, required)* – Terminal identifier * `posLocationId` *(string, required)* – POS Location identifier ## 3. Submit Transaction **Endpoint:**\ `POST https://apitest.clearline.me/pos/{posSystemId}/transaction` **Description:**\ Sends transaction data from POS to ClearLine.\ Requires `sessionId` obtained from `/startInteraction`. **Path Parameters:** * `posSystemId` *(string, required)* – POS system identifier. ### Example Request ``` { "sessionId": "string", "customer": { "id": "string", "firstName": "string", "lastName": "string", "birthDate": "2025-09-24T06:13:50.402Z", "contacts": [ { "email": "string", "phone": "string" } ] }, "salesPerson": { "id": "string", "firstName": "string", "lastName": "string" }, "purchaseName": "string", "purchaseId": "string", "purchaseQuantity": 0, "purchasePrice": "string", "transactionId": "string", "transactionType": "Undefined", "transactionAmount": 0, "transactionDate": "2025-09-24T06:13:50.402Z", "terminalId": "string", "posLocationId": "string", "products": [ { "productId": "string", "productName": "string", "manufacturer": "string", "productCategory": "string", "quantity": 0 } ], "loyalty": { "cardNumber": "string" } } ``` ### Example Response (200 Success) ``` { "data": { "id": "string", "qrCodeWidget": { "shortLinkUrl": "string", "qrCode": { "htmlLinkUrl": "string", "previewHtmlLinkUrl": "string" }, "notificationMessageId": "string", "profile": { "id": "string", "firstName": "string", "lastName": "string", "customerEmail": "string", "customerPhone": "string", "salesPerson": "string", "purchaseName": "string", "purchaseId": "string", "purchaseCategory": "string", "purchasePrice": "string", "gender": "string" }, "sessionId": "string" }, "cfsTemplate": { "accountTemplateId": 0, "cfsCarouselUrl": "string" }, "posStatus": "Accepted", "loyalty": { "status": "Applied", "awardDescription": "string", "qrCode": { "linkUrl": "string", "qrCodeLinkUrl": "string", "primaryText": "string", "secondaryText": "string" } } } } ``` **Schema Highlights:** * `NewPosTransactionRequestDto` * `sessionId` *(string, required)* – Session identifier * `customer` *(PosTransactionCustomerDto, optional)* – Customer info * `salesPerson` *(PosTransactionSalesPersonDto, optional)* – Sales person info * `purchaseName`, `purchaseId`, `purchaseQuantity`, `purchasePrice` * `transactionId` *(string, required)* – Transaction identifier * `transactionType` *(enum, optional)* * `transactionAmount` *(number, optional)* * `transactionDate` *(datetime, required)* * `terminalId`, `posLocationId` *(string, required)* * `products[]` *(PosTransactionProductDto, optional)* * `loyalty` *(PosTransactionLoyaltyProgramDto, optional)* – Loyalty card number * `NewPosTransactionResponseDtoApiResponse` * `id` *(string, optional)* – Transaction Id * `qrCodeWidget` *(WidgetMessageResultDto)* – QR code & notification details * `cfsTemplate` *(CfsTemplateMessageResultDto)* – CFS campaign template data * `posStatus` *(enum: Accepted, Disabled, NotAvailable)* * `loyalty` *(PosTransactionLoyaltyResponseDto)* – Loyalty program reward details After a transaction, the POS system receives the following data in the response, which can be printed on the customer’s receipt: * \*\*Description \*\*– Loyalty details such as the updated customer balance and the number of points earned * **QR Code** – An image URL linking to the Loyalty Program * \*\*Primary & Secondary Text \*\*– Brief information about the Loyalty Program or additional promotional details # 2. Customer Check-In & Loyalty Card retrieval ## 1. Get a Webhook with the Customer Details Once a customer is checked in via **CFS** or **CMC**, ClearLine sends a **webhook notification** with the following customer details: * Loyalty Card Number * Loyalty User ID * Email * Phone * First Name * Last Name * SentAd To display customer details at the POS, the system can use the **User Card Details** endpoint: ## 2. Get Loyalty Card details **Endpoint:** #### GET [https://apitest.clearline.me/v2/pos/\{posSystemId}/loyaltyCard/lookup](https://apitest.clearline.me/v2/pos/\{posSystemId}/loyaltyCard/lookup) Retrieve loyalty card details for a specific location. **Path Parameters:** * `posSystemId` *(string, required)* – POS system identifier. ### Request ``` {     "posLocationId": "{{PosLocationId}}" } ``` ### Responses **Code 200 – success** ``` { "data": { "loyaltyCard": { "id": "string", "name": "string", "title": "string", "description": "string", "frontImage": "string", "loyaltyCardType": 1, "location": { "id": "string", "name": "string" } } } } ``` ### Schema **LoyaltyCard** * `id` *(string, nullable)* – Loyalty card unique identifier * `name` *(string, nullable)* – Loyalty card name * `title` *(string, nullable)* – Loyalty card title * `description` *(string, nullable)* – Loyalty card description * `frontImage` *(string, nullable)* – Front image URL **Location** * `id` *(string, nullable)* – Location unique identifier * `name` *(string, nullable)* – Location name # 3. Coupon validation ## 1. Get customer coupons **Endpoint:**\ `POST https://apitest.clearline.me/pos/{posSystemId}/coupon/couponCode/search` **Description:**\ Returns customer coupons by search parameters **Path Parameters:** * `posSystemId` *(string, required)* – POS system identifier. ### Example Request ``` { "code": "string", "email": "string", "phone": "string", "posLocationId": "string" } ``` **Schema** * `code` *(string, nullable)* – Filter by coupon code * `email` *(string, nullable)* – Filter by customer email * `phone` *(string, nullable)* – Filter by customer phone number * `posLocationId` *(string, nullable)* – POS location identifier ### Responses **200 (Success)** ``` { "data": [ { "rewardProvider": "TwoReward", "code": "string", "name": "string", "title": "string", "pictureUrl": "string", "availableUntil": "2025-09-25T07:52:57.104Z", "status": "Issued", "info": [ { "title": "string", "items": { "additionalProp1": "string", "additionalProp2": "string", "additionalProp3": "string" } } ] } ], "page": { "page": 0, "pageSize": 0, "total": 0 }, "posStatus": "Accepted" } ``` **Schema** **CouponCodeDisplayDtoPosApiListResponse**\ Represents the response containing a list of coupon codes available to the POS system. * `data` *(array of CouponCodeDisplayDto, nullable)* – List of coupon codes * `page` *(PageModel)* – Pagination metadata * `posStatus` *(enum: Accepted, Disabled, NotAvailable)* – POS response status **CouponCodeDisplayDto**\ Represents coupon code display data. * `rewardProvider` *(enum: TwoReward, PJM)* – Reward provider type * `code` *(string, nullable)* – Coupon code * `name` *(string, nullable)* – Coupon name * `title` *(string, nullable)* – Coupon title * `pictureUrl` *(string, nullable)* – URL to the coupon image * `availableUntil` *(string, date-time, nullable)* – Expiration date of the coupon * `status` *(enum: Issued, Redeemed, Cancelled, Expired)* – Coupon status * `info` *(array of CouponCodeDisplayInfoDto, nullable)* – Additional coupon information **CouponCodeDisplayInfoDto**\ Represents an additional information section for a coupon. * `title` *(string, nullable)* – Section title * `items` *(object, nullable)* – Key-value data for the section **PageModel** * `page` *(integer)* – Current page * `pageSize` *(integer)* – Number of items per page * `total` *(integer)* – Total number of items ## 2. Validate coupon **Endpoint:**\ `POST https://apitest.clearline.me/pos/{posSystemId}/coupon/validate/byTransaction` **Description:**\ Validates customer coupon by transaction Requires `sessionId` obtained from `/startInteraction`. **Path Parameters:** * `posSystemId` *(string, required)* – POS system identifier. ### Example Request ``` { "sessionId": "string", "campaignId": "string", "transactionId": "string", "couponUser": { "firstName": "string", "lastName": "string", "gender": "string", "phone": "string", "email": "string" } } ``` ### Responses **200 (Success)** ``` { "posStatus": "Accepted", "data": { "externalSessionId": "string", "status": "string", "validationDate": "2025-09-25T08:08:35.448Z", "errorMessage": "string" } } ``` **Schema** **ValidateCouponSessionDtoPosApiResponse**\ Represents the response returned when validating a coupon session. * `posStatus` *(enum: Accepted, Disabled, NotAvailable)* – POS response status * `data` *(ValidateCouponSessionDto)* – Coupon session validation result **ValidateCouponSessionDto**\ Represents the result of a coupon session validation. * `externalSessionId` *(string, nullable)* – External coupon session identifier * `status` *(string, nullable)* – Validation status of the coupon * `validationDate` *(string, date-time, nullable)* – Date and time of validation * `errorMessage` *(string, nullable)* – Error message if validation fails