CFS Carousel

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.

POST https://public-api-test.clearline.me/v2/pos/{posSystemId}/carousel

{
  "posLocationId": "{posLocationId}",
  "terminalId": "{terminalId}"
}

{
  "data": {
    "url": "https://webtest.clearline.me/carousel/abc123?locationId=LOC123&terminalId=TERM-05"
  }
}

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

object

Carousel URL information

Show Properties

string

The full URL to the carousel web application. Load this URL in an iframe or webview on the customer-facing screen.

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

Implementation Guide

Request Carousel URL

Call the carousel endpoint when initializing your customer-facing screen or when you want to display marketing content.

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;

Display in Iframe

Load the carousel URL in an iframe on your customer-facing screen.

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

Handle Lifecycle

Manage the carousel lifecycle based on your POS workflow.

// 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;
}

Carousel Features

Auto-Rotation

Slides automatically rotate based on configured timing (typically 5-15 seconds per slide).

Responsive Design

Adapts to different screen sizes and orientations on various CFS devices.

Dynamic Content

Content updates automatically when templates are changed in ClearLine Marketing Center.

Analytics Tracking

Tracks impressions and engagement for each location and terminal.

Configuration

Configure Carousel Templates in ClearLine Marketing Center

To set up carousel content:

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

Changes take effect immediately and are reflected in the carousel URL.

Best Practices

Performance Optimization

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

User Experience

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

Troubleshooting

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

Integration Workflows

Always-On Display
Conditional Display
Hybrid with Widgets

Keep carousel visible at all times on a dedicated customer-facing screen.

// On POS startup
async function initializeCFS() {
  const carouselUrl = await getCarouselUrl();
  displayCarousel(carouselUrl);
  
  // Refresh daily
  setInterval(refreshCarousel, 24 * 60 * 60 * 1000);
}

Show carousel only during specific states (e.g., idle, post-checkout).

// 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);
});

Combine carousel with widget sessions for dynamic content.

// 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();
});

Next Steps

Widget Integration

Combine carousel with interactive widgets

Automated Flow

Set up automated widget triggering

CFS Web API Events

Learn about iframe communication

Checkout Integration

View complete integration workflow

Getting Started

Integration Options

POS Integration

API Reference

Overview

Get Carousel URL

Headers

Path Parameters

Request Body

Response Fields

Implementation Guide

Carousel Features

Auto-Rotation

Responsive Design

Dynamic Content

Analytics Tracking

Configuration

Best Practices

Integration Workflows

Next Steps

Widget Integration

Automated Flow

CFS Web API Events

Checkout Integration

​Overview

​Get Carousel URL

​Headers

​Path Parameters

​Request Body

​Response Fields

​Implementation Guide

​Carousel Features

Auto-Rotation

Responsive Design

Dynamic Content

Analytics Tracking

​Configuration

​Best Practices

​Integration Workflows

​Next Steps

Widget Integration

Automated Flow

CFS Web API Events

Checkout Integration

Overview

Get Carousel URL

Headers

Path Parameters

Request Body

Response Fields

Implementation Guide

Carousel Features

Configuration

Best Practices

Integration Workflows

Next Steps