> ## 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.

# Manual Flow in POS System Checkout

> Implement manual widget interaction flow in your POS checkout process

## Overview

After obtaining an access token, your POS system can interact with the Widgets platform through a 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 or SMS).

***

## Manual Flow Steps

<Steps>
  <Step title="Add Products to Cart">
    Merchant adds products to the shopping cart.
  </Step>

  <Step title="Proceed to Checkout">
    Merchant proceeds to the checkout process.
  </Step>

  <Step title="System Checks">
    During checkout, the POS system completes several checks:

    * Check if post-purchase transactions are enabled
    * Check if POS Rules are enabled
  </Step>

  <Step title="Show Confirmation Modal">
    If POS Rules are disabled, a confirmation modal is shown proposing to use ClearLine Marketing apps.
  </Step>

  <Step title="Display Marketing Apps">
    If merchant confirms to proceed with ClearLine Marketing, a modal is shown with the marketing apps list (tiles view).

    **Endpoint:** Get Available Widgets (Marketing Apps)
  </Step>

  <Step title="Select Marketing App">
    Merchant clicks on one of the marketing apps.

    **Endpoint:** Start a Widget Session (Display QR Code preview)
  </Step>

  <Step title="Complete Session">
    Merchant clicks the "Open QR Code" button or "Send" button.

    **Endpoint:** Complete the Widget Session
  </Step>

  <Step title="Deliver Content">
    ClearLine app shows the QR Code template (modal) or sends SMS/email to the customer.
  </Step>
</Steps>

***

## Get Available Widgets (Marketing Apps)

Retrieve 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.

<CodeGroup>
  ```bash Request theme={null}
  POST https://public-api-test.clearline.me/v2/pos/{posSystem}/widgets/list
  ```

  ```json Request Body theme={null}
  {
    "posLocationId": "string"
  }
  ```

  ```json Response theme={null}
  {
    "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"]
      }
    ]
  }
  ```
</CodeGroup>

### Headers

| Name          | Value                | Description                  |
| ------------- | -------------------- | ---------------------------- |
| Authorization | Bearer access\_token | Request authorization header |
| Content-Type  | application/json     | Content type                 |

### Path Parameters

| Field name | Description                                          |
| ---------- | ---------------------------------------------------- |
| posSystem  | The identifier of the POS system (e.g., pax, clover) |

### Request Body

| Field name    | Type   | Description                        |
| ------------- | ------ | ---------------------------------- |
| posLocationId | string | The identifier of the POS location |

### Response Fields

<ResponseField name="data" type="array">
  Array of available widget objects

  <Expandable title="Widget Object Properties">
    <ResponseField name="id" type="integer">
      Identifier of the marketing app
    </ResponseField>

    <ResponseField name="name" type="string">
      Name of the marketing app
    </ResponseField>

    <ResponseField name="icon" type="string">
      Icon in SVG format
    </ResponseField>

    <ResponseField name="description" type="string">
      Description of the marketing app
    </ResponseField>

    <ResponseField name="deliveryMethods" type="string[]">
      Allowed delivery methods (Sms, Email, QrCode)
    </ResponseField>

    <ResponseField name="flow" type="string[]">
      Identifies the flow of the widget execution (Default, Custom)
    </ResponseField>
  </Expandable>
</ResponseField>

### UI Example

<Frame>
  <img src="https://mintcdn.com/allmatics-7a6fd95a/WlD7hVDCVXS0g46B/images/integration-options/checkout-integration-app/manual-flow-in-pos-system-checkout-cmc/image_4f28b36d.png?fit=max&auto=format&n=WlD7hVDCVXS0g46B&q=85&s=30dd2d558bade015b384c49c5e9c8337" alt="Marketing apps selection modal" width="1295" height="757" data-path="images/integration-options/checkout-integration-app/manual-flow-in-pos-system-checkout-cmc/image_4f28b36d.png" />
</Frame>

***

## Start a Widget Session

Initiate a widget session and preview the QR code.

<CodeGroup>
  ```bash Request theme={null}
  POST https://public-api-test.clearline.me/v2/pos/{posSystemId}/widget/start
  ```

  ```json Request Body theme={null}
  {
    "posLocationId": "{posLocationId}",
    "widgetId": "{widgetId}",
    "terminalId": "{terminalId}",
    "couponId": "{couponId}"
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "sessionId": "string",
      "qrCodePreviewHtmlLinkUrl": "string"
    }
  }
  ```
</CodeGroup>

### Headers

| Name          | Value                | Description                  |
| ------------- | -------------------- | ---------------------------- |
| Authorization | Bearer access\_token | Request authorization header |
| Content-Type  | application/json     | Content type                 |

### Path Parameters

| Field name  | Type   | Description                                          |
| ----------- | ------ | ---------------------------------------------------- |
| posSystemId | string | The identifier of the POS system (e.g., pax, clover) |

### Request Body

| Field name    | Type    | Required | Description                                                         |
| ------------- | ------- | -------- | ------------------------------------------------------------------- |
| posLocationId | string  | Yes      | The identifier of the POS location                                  |
| widgetId      | integer | Yes      | The identifier of the widget                                        |
| terminalId    | string  | Yes      | The identifier of the POS terminal                                  |
| couponId      | string  | No       | The identifier of the coupon, required for Issue Coupon widget only |

### Response Fields

<ResponseField name="data" type="object">
  Widget session data

  <Expandable title="Properties">
    <ResponseField name="sessionId" type="string">
      Session identifier for tracking the widget interaction
    </ResponseField>

    <ResponseField name="qrCodePreviewHtmlLinkUrl" type="string">
      Preview QR code HTML link URL
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Show Widget QR Code

Display the widget QR code to the customer on the customer-facing screen.

<CodeGroup>
  ```bash Request theme={null}
  POST https://public-api-test.clearline.me/v2/pos/{posSystemId}/widget/showQrCode
  ```

  ```json Request Body theme={null}
  {
    "widgetId": 0,
    "sessionId": "string",
    "posLocationId": "string",
    "terminalId": "string",
    "profile": {
      "firstName": "string",
      "lastName": "string",
      "customerEmail": "string",
      "customerPhone": "string",
      "salesPerson": "string"
    },
    "couponId": "string"
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "qrCodeHtmlLinkUrl": "string"
    }
  }
  ```
</CodeGroup>

### Headers

| Name          | Value                | Description                  |
| ------------- | -------------------- | ---------------------------- |
| Authorization | Bearer access\_token | Request authorization header |
| Content-Type  | application/json     | Content type                 |

### Path Parameters

| Field name  | Type   | Description                                          |
| ----------- | ------ | ---------------------------------------------------- |
| posSystemId | string | The identifier of the POS system (e.g., pax, clover) |

### Request Body

| Field name    | Type    | Required | Description                                                         |
| ------------- | ------- | -------- | ------------------------------------------------------------------- |
| widgetId      | integer | Yes      | The identifier of the widget                                        |
| sessionId     | string  | Yes      | The session identifier from the start widget call                   |
| posLocationId | string  | Yes      | ID of the location where the transaction was made                   |
| terminalId    | string  | Yes      | The identifier of the POS terminal                                  |
| profile       | object  | No       | Customer profile information                                        |
| couponId      | string  | No       | The identifier of the coupon, required for Issue Coupon widget only |

### Profile Object

| Field name    | Type   | Description              |
| ------------- | ------ | ------------------------ |
| firstName     | string | Customer's first name    |
| lastName      | string | Customer's last name     |
| customerEmail | string | Customer's email address |
| customerPhone | string | Customer's phone number  |
| salesPerson   | string | Name of the sales person |

### Response Fields

<ResponseField name="data" type="object">
  QR code display data

  <Expandable title="Properties">
    <ResponseField name="qrCodeHtmlLinkUrl" type="string">
      QR code HTML link URL to display on the customer-facing screen
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Send Widget QR via Email or SMS

Send the widget QR code to the customer via email or SMS instead of displaying it on the customer-facing screen.

<CodeGroup>
  ```bash Request theme={null}
  POST https://public-api-test.clearline.me/v2/pos/{posSystemId}/widget/sendMessage
  ```

  ```json Request Body theme={null}
  {
    "widgetId": 0,
    "sessionId": "string",
    "posLocationId": "string",
    "terminalId": "string",
    "profile": {
      "firstName": "string",
      "lastName": "string",
      "customerEmail": "string",
      "customerPhone": "string",
      "salesPerson": "string"
    },
    "couponId": "string"
  }
  ```

  ```json Response theme={null}
  {
    "data": {}
  }
  ```
</CodeGroup>

### Headers

| Name          | Value                | Description                  |
| ------------- | -------------------- | ---------------------------- |
| Authorization | Bearer access\_token | Request authorization header |
| Content-Type  | application/json     | Content type                 |

### Path Parameters

| Field name  | Type   | Description                                          |
| ----------- | ------ | ---------------------------------------------------- |
| posSystemId | string | The identifier of the POS system (e.g., pax, clover) |

### Request Body

| Field name    | Type    | Required | Description                                                         |
| ------------- | ------- | -------- | ------------------------------------------------------------------- |
| widgetId      | integer | Yes      | The identifier of the widget                                        |
| sessionId     | string  | Yes      | The session identifier from the start widget call                   |
| posLocationId | string  | Yes      | ID of the location where the transaction was made                   |
| terminalId    | string  | Yes      | The identifier of the POS terminal                                  |
| profile       | object  | Yes      | Customer profile information (required for delivery)                |
| couponId      | string  | No       | The identifier of the coupon, required for Issue Coupon widget only |

### Profile Object

| Field name    | Type   | Required | Description              |
| ------------- | ------ | -------- | ------------------------ |
| firstName     | string | No       | Customer's first name    |
| lastName      | string | No       | Customer's last name     |
| customerEmail | string | No       | Customer's email address |
| customerPhone | string | No       | Customer's phone number  |
| salesPerson   | string | No       | Name of the sales person |

<Note>
  At least one of `customerEmail` or `customerPhone` must be provided to send the message.
</Note>

### Response Fields

<ResponseField name="data" type="object">
  Empty object returned on successful message delivery
</ResponseField>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Checkout Integration Flow" icon="diagram-project" href="/integration-options/checkout-integration-app/checkout-integration-flow-example">
    View the complete checkout integration workflow
  </Card>

  <Card title="Widget API Reference" icon="code" href="/api-reference/widgets/introduction">
    Explore all widget endpoints
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication/introduction">
    Learn how to authenticate API requests
  </Card>

  <Card title="POS Settings" icon="gear" href="/api/pos-integration/pos-system-settings">
    Configure manual vs automated flow
  </Card>
</CardGroup>