Skip to main content

​
Intro

After obtaining an access token, your POS system can interact with the Widgets platform through the following sequence of API calls. This flow allows you to retrieve available widgets, initiate a widget session, and display the resulting QR code on the customer-facing screen (CFS) or deliver it via other supported methods (e.g., email).

​
Base Flow:

  1. Merchant adds products to cart
  2. Merchant proceeds to Checkout
  3. During the Checkout process the POS System completes several checks
    1. Check if post-purchase Transactions are enabled
    2. Check if POS Rules are enabled
  4. If POS Rules are disabled then a confirmation modal is shown proposing to use Clearline Marketing apps
  5. If Merchant confirms to proceed with Clearline Marketing, then a CMC Modal is shown with Marketing apps list(tiles view)
    1. Endpoint: Get Available Widgets(Marketing Apps)
  6. Merchant clicks on one of marketing apps
    1. Endpoint: Start a Widget session (Display QrCode preview)
  7. Merchant clicks the Open QR Code button or Send button
    1. Endpoint: Compete the Widget session
  8. Clearline app shows the QR Code template(modal) or sends sms/email

​
Get Available Widgets(Marketing Apps)

This endpoint retrieves a list of widgets available for a specific POS location. These widgets can be used to engage customers through various delivery methods like QR codes, emails, or sms. POST https://public-api-test.clearline.me/v2/pos//widgets/list

​
Headers

NameValueDescription
AuthorizationBearer Request authorization header
Content-Typeapplication/jsonContent type

​
Input Request

{
    "posLocationId": "string"
}

​
Input parameters

Field nameDescription
posSystemThe identifier of the POS system (e.g., pax, clover)
posLocationThe identifier of the POS location

​
Response

{
  "data": [
    {
      "id": 1,
      "name": "Digital Coupons",
      "icon": "https://web.clearline.me/widget/IssueCoupon/icon",
      "description": "How It Works\\nWhen you decide that your business..."
      "deliveryMethods": [ Sms, Email, QrCode ],
      "flow": [Default, Custom]
    },
    ...
  ]
}

​
Response parameters

Field nameDescription
data.idIdentifier of the marketing app
data.nameName of the marketing app
data.iconIcon in swg format
data.descriptionDescription of the marketing app
data.deliveryMethodsAllowed delivery methods (Sms, Email, QrCode)
data.flowIdentifies the flow of the widget execution (Default, Custom)

​
UI Sample

image-20250727-184955.png

​
Start a Widget session (Display QrCode preview)

Initiate a widgets session and preview the QR code. POST https://public-api-test.clearline.me/v2/pos//widget/start

​
Headers

NameValueDescription
AuthorizationBearer Request authorization header
Content-Typeapplication/jsonContent type

​
Input parameters

Field nameDescription
posSystemThe identifier of the POS system (e.g., pax, clover)
widgetIdThe identifier of the widget
posLocationIdThe identifier of the POS location
terminalIdThe identifier of the POS Terminal
couponIdThe identifier of the coupon, required for Issue Coupon widget only

​
Input request

{
    "posLocationId": "{posLocationId}",
    "widgetId": "{widgetId}",
    "terminalId": "{terminalId}",
    "couponId": "{couponId}"
}

​
Response

{
  "data": {
    "sessionId": "string",
    "qrCodePreviewHtmlLinkUrl": "string"
  }
}

​
Response parameters

Field nameDescription
data.qrCodePreviewHtmlLinkUrlPreview QrCode html link url
data.sessionIdSession identifier

​
Show Widget QR code

Show widget QR code POST https://public-api-test.clearline.me/v2/pos//widget/showQrCode

​
Headers

NameValueDescription
AuthorizationBearer Request authorization header
Content-Typeapplication/jsonContent type

​
Input parameters

Field nameDescription
posSystemThe identifier of the POS system (e.g., pax, clover)
widgetIdThe identifier of the widget
posLocationIdID of the location where the transaction was made
terminalIdThe identifier of POS Terminal
couponIdThe identifier of the coupon, required for Issue Coupon widget only
profileCustomer profile information

​
Input request

{
  "widgetId": 0,
  "sessionId": "string",
  "posLocationId": "string",
  "terminalId": "string",
  "profile": {
    "firstName": "string",
    "lastName": "string",
    "customerEmail": "string",
    "customerPhone": "string",
    "salesPerson": "string"
  },
  "couponId": "string"
}

​
Response

{
  "data": {
    "qrCodeHtmlLinkUrl": "string"
  }
}

​
Response parameters

Field nameDescription
data.qrCodeHtmlLinkUrlQrCode html link url

​
Send Widget QR via email or sms

Show widget QR code POST https://public-api-test.clearline.me/v2/pos//widget/sendMessage

​
Headers

NameValueDescription
AuthorizationBearer Request authorization header
Content-Typeapplication/jsonContent type

​
Input parameters

Field nameDescription
posSystemThe identifier of the POS system (e.g., pax, clover)
widgetIdThe identifier of the widget
posLocationIdID of the location where the transaction was made
terminalIdThe identifier of POS Terminal
couponIdThe identifier of the coupon, required for Issue Coupon widget only
profileCustomer profile information

​
Input request

{
  "widgetId": 0,
  "sessionId": "string",
  "posLocationId": "string",
  "terminalId": "string",
  "profile": {
    "firstName": "string",
    "lastName": "string",
    "customerEmail": "string",
    "customerPhone": "string",
    "salesPerson": "string"
  },
  "couponId": "string"
}

​
Response

{
  "data": {}
}