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

# CFS Carousel

> Display marketing slides on customer-facing screens using the Carousel API

## Overview

The CFS Carousel displays rotating marketing slides on a Customer-Facing Screen (CFS) connected to the POS terminal. This feature allows you to show promotional content, special offers, and branded messaging to customers while they wait at checkout or browse in-store.

The carousel uses pre-defined templates configured in the ClearLine Marketing Center and delivers a URL that can be loaded in an iframe or webview on your customer-facing display.

***

## Get Carousel URL

Retrieve the carousel URL for a specific POS location and terminal. This URL points to a web-based carousel that automatically rotates through configured marketing slides.

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

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

  ```json Response theme={null}
  {
    "data": {
      "url": "https://webtest.clearline.me/carousel/abc123?locationId=LOC123&terminalId=TERM-05"
    }
  }
  ```
</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      | ID of the POS location             |
| terminalId    | string | Yes      | The identifier of the POS terminal |

### Response Fields

<ResponseField name="data" type="object">
  Carousel URL information

  <Expandable title="Properties">
    <ResponseField name="url" type="string">
      The full URL to the carousel web application. Load this URL in an iframe or webview on the customer-facing screen.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  The carousel URL is session-specific and includes location and terminal identifiers for tracking and analytics.
</Note>

***

## Implementation Guide

<Steps>
  <Step title="Request Carousel URL">
    Call the carousel endpoint when initializing your customer-facing screen or when you want to display marketing content.

    ```typescript theme={null}
    const response = await fetch(
      'https://public-api-test.clearline.me/v2/pos/clover/carousel',
      {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          posLocationId: 'LOC123',
          terminalId: 'TERM-05'
        })
      }
    );

    const data = await response.json();
    const carouselUrl = data.data.url;
    ```
  </Step>

  <Step title="Display in Iframe">
    Load the carousel URL in an iframe on your customer-facing screen.

    ```html theme={null}
    <iframe 
      id="carousel-frame"
      src="https://webtest.clearline.me/carousel/abc123?locationId=LOC123&terminalId=TERM-05"
      width="100%"
      height="100%"
      frameborder="0"
      allow="autoplay"
    ></iframe>
    ```
  </Step>

  <Step title="Handle Lifecycle">
    Manage the carousel lifecycle based on your POS workflow.

    ```typescript theme={null}
    // Show carousel during idle time
    function showCarousel() {
      document.getElementById('carousel-frame').style.display = 'block';
    }

    // Hide carousel during checkout
    function hideCarousel() {
      document.getElementById('carousel-frame').style.display = 'none';
    }

    // Refresh carousel URL periodically (e.g., daily)
    async function refreshCarousel() {
      const newUrl = await getCarouselUrl();
      document.getElementById('carousel-frame').src = newUrl;
    }
    ```
  </Step>
</Steps>

***

## Carousel Features

<CardGroup cols={2}>
  <Card title="Auto-Rotation" icon="rotate">
    Slides automatically rotate based on configured timing (typically 5-15 seconds per slide).
  </Card>

  <Card title="Responsive Design" icon="mobile-screen">
    Adapts to different screen sizes and orientations on various CFS devices.
  </Card>

  <Card title="Dynamic Content" icon="wand-magic-sparkles">
    Content updates automatically when templates are changed in ClearLine Marketing Center.
  </Card>

  <Card title="Analytics Tracking" icon="chart-line">
    Tracks impressions and engagement for each location and terminal.
  </Card>
</CardGroup>

***

## Configuration

<Accordion title="Configure Carousel Templates in ClearLine Marketing Center" icon="gear">
  To set up carousel content:

  1. **Log in to ClearLine Marketing Center**
  2. **Navigate to Content > Carousel Templates**
  3. **Create or edit templates:**
     * Upload images or design custom slides
     * Set rotation timing (seconds per slide)
     * Configure which templates display at which locations
  4. **Assign templates to locations:**
     * Select specific POS locations
     * Set active date ranges
     * Preview how slides will appear
  5. **Save and publish**

  Changes take effect immediately and are reflected in the carousel URL.
</Accordion>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Performance Optimization" icon="gauge-high">
    * **Cache the carousel URL** locally and refresh periodically (e.g., once per day)
    * **Preload the iframe** during POS system initialization
    * **Use appropriate dimensions** to avoid unnecessary scaling
    * **Limit slide file sizes** to ensure smooth transitions
  </Accordion>

  <Accordion title="User Experience" icon="star">
    * **Hide carousel during active checkout** to avoid distracting customers
    * **Show carousel during idle time** to maximize marketing exposure
    * **Ensure audio is muted** if slides contain video content
    * **Test visibility** from typical customer viewing angles
  </Accordion>

  <Accordion title="Troubleshooting" icon="wrench">
    **Common issues and solutions:**

    | Issue               | Solution                                          |
    | ------------------- | ------------------------------------------------- |
    | Blank carousel      | Verify templates are configured for this location |
    | Slides not rotating | Check network connectivity and iframe load status |
    | Wrong content       | Confirm location ID and terminal ID are correct   |
    | Performance issues  | Reduce slide image sizes in Marketing Center      |
  </Accordion>
</AccordionGroup>

***

## Integration Workflows

<Tabs>
  <Tab title="Always-On Display">
    Keep carousel visible at all times on a dedicated customer-facing screen.

    ```typescript theme={null}
    // On POS startup
    async function initializeCFS() {
      const carouselUrl = await getCarouselUrl();
      displayCarousel(carouselUrl);
      
      // Refresh daily
      setInterval(refreshCarousel, 24 * 60 * 60 * 1000);
    }
    ```
  </Tab>

  <Tab title="Conditional Display">
    Show carousel only during specific states (e.g., idle, post-checkout).

    ```typescript theme={null}
    // Show during idle
    posSystem.on('idle', async () => {
      const carouselUrl = await getCarouselUrl();
      showCarousel(carouselUrl);
    });

    // Hide during checkout
    posSystem.on('checkout-start', () => {
      hideCarousel();
    });

    // Show after checkout
    posSystem.on('checkout-complete', async () => {
      const carouselUrl = await getCarouselUrl();
      showCarousel(carouselUrl);
    });
    ```
  </Tab>

  <Tab title="Hybrid with Widgets">
    Combine carousel with widget sessions for dynamic content.

    ```typescript theme={null}
    // Default: Show carousel
    showCarousel();

    // When widget triggers
    posSystem.on('widget-triggered', (widgetData) => {
      hideCarousel();
      showWidget(widgetData.url);
    });

    // After widget completes
    posSystem.on('widget-complete', () => {
      hideWidget();
      showCarousel();
    });
    ```
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Widget Integration" icon="window" href="/api-reference/widgets/introduction">
    Combine carousel with interactive widgets
  </Card>

  <Card title="Automated Flow" icon="robot" href="/integration-options/checkout-integration-app/automated-flow-in-pos-system-checkout">
    Set up automated widget triggering
  </Card>

  <Card title="CFS Web API Events" icon="plug" href="/integration-options/checkout-integration-app/pos-integration-cfs-web-api-events-iframe-postmessage">
    Learn about iframe communication
  </Card>

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