Use Cases

Explore common integration scenarios and learn how to implement them using the ClearLine POS API. Each use case includes a business overview, technical approach, required endpoints, and working code examples.

🛒 Process POS Transaction → Trigger Loyalty

Business Need

When a customer completes a purchase at the point of sale, automatically record the transaction and award loyalty points or trigger marketing actions based on their purchase behavior.

Technical Overview

This workflow involves three key steps:

Start Interaction - Initialize a POS session for the terminal
Send Transaction - Submit transaction details with customer data, items, amounts, and payment info
Handle Response - Process loyalty points awarded and any triggered campaigns

API Endpoints Used:

POST /pos/{posSystemId}/startInteraction - Initiate POS session
POST /pos/{posSystemId}/transaction - Submit transaction data

Implementation Example

// Step 1: Start POS session
const interactionResponse = await fetch('https://public-api-demo.clearline.me/pos/clover/startInteraction', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    terminalId: "TERM-05",
    posLocationId: "LOC123"
  })
});

const { data } = await interactionResponse.json();
const sessionId = data.sessionId;

// Step 2: Send transaction with customer data
const transactionResponse = await fetch('https://public-api-demo.clearline.me/pos/clover/transaction', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sessionId: sessionId,
    posLocationId: "LOC123",
    terminalId: "TERM-05",
    transactionId: "TXN-" + Date.now(),
    transactionAmount: 12.97,
    customer: {
      id: "CUST-001",
      firstName: "John",
      lastName: "Doe",
      contacts: [
        { type: "Email", value: "john.doe@example.com" },
        { type: "Phone", value: "+15555551234" }
      ]
    },
    products: [
      { 
        productId: "COFFEE-001", 
        productName: "Large Coffee", 
        price: 3.99, 
        quantity: 2,
        totalPrice: 7.98
      },
      { 
        productId: "MUFFIN-002", 
        productName: "Blueberry Muffin", 
        price: 4.99, 
        quantity: 1,
        totalPrice: 4.99
      }
    ]
  })
});

const result = await transactionResponse.json();
console.log('Transaction processed:', result);

// Check loyalty response
if (result.data.loyalty) {
  console.log('Loyalty points awarded:', result.data.loyalty);
}

Include customer contact information in the transaction request to enable loyalty tracking and marketing campaign triggers.

Learn More

View complete transaction API reference →

🎟️ Validate Coupon at Checkout

Business Need

Enable cashiers to scan or enter coupon codes during checkout and validate them in real-time before applying discounts.

Technical Overview

Workflow:

Lookup Coupon - Search for a coupon by code
Validate Coupon - Check coupon status and eligibility
Apply Discount - Use coupon information to calculate discount in your POS
Record Usage - Include coupon details in the transaction

API Endpoints Used:

POST /v2/pos/{posSystemId}/coupon/couponCodes/lookup - Search for coupons
POST /v2/pos/{posSystemId}/coupon/couponCodes/validate - Validate coupon

The validate endpoint confirms the coupon exists and is active. Your POS system is responsible for applying business rules like minimum purchase amounts and calculating the actual discount.

Implementation Example

// Step 1: Lookup coupon by code
const lookupResponse = await fetch('https://public-api-demo.clearline.me/v2/pos/clover/coupon/couponCodes/lookup', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    posLocationId: "LOC123",
    code: "SAVE20"
  })
});

const lookupResult = await lookupResponse.json();

if (!lookupResult.data?.couponCodes || lookupResult.data.couponCodes.length === 0) {
  console.error('Coupon not found');
  return;
}

const couponDetails = lookupResult.data.couponCodes[0];
console.log('Coupon found:', couponDetails);

// Step 2: Validate coupon
const validateResponse = await fetch('https://public-api-demo.clearline.me/v2/pos/clover/coupon/couponCodes/validate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    posLocationId: "LOC123",
    code: "SAVE20",
    rewardProvider: "TwoReward" // Optional: specify reward provider
  })
});

const validation = await validateResponse.json();

if (validation.success) {
  console.log('Coupon is valid and can be applied');
  // Your POS calculates the discount based on coupon details
} else {
  console.error('Coupon validation failed');
}

These endpoints verify coupon existence and status. Your POS system must implement discount calculation logic based on the coupon details returned.

Learn More

View complete coupons API reference →

📺 Display Marketing Content with Widgets

Business Need

Show interactive marketing content on customer-facing displays that customers can engage with to join loyalty programs, view offers, or receive digital receipts via QR code or SMS.

Technical Overview

Workflow:

List Widgets - Get available marketing actions for the location
Start Widget Session - Launch a widget for customer interaction
Show QR Code - Display QR code for mobile engagement
Send Message - Deliver content via SMS/email

API Endpoints Used:

POST /v2/pos/{posSystemId}/widget/list - Get available widgets
POST /v2/pos/{posSystemId}/widget/start - Start widget session
POST /v2/pos/{posSystemId}/widget/showQrCode - Generate QR code
POST /v2/pos/{posSystemId}/widget/sendMessage - Send SMS/email

Widget Types:

Loyalty enrollment
Promotion signup
Digital receipt delivery
Survey/feedback collection

Implementation Example

// Step 1: Get available widgets
const widgetsResponse = await fetch('https://public-api-demo.clearline.me/v2/pos/clover/widget/list', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    posLocationId: "LOC123"
  })
});

const { data: widgets } = await widgetsResponse.json();
console.log('Available widgets:', widgets);

// Step 2: Start widget session
const startResponse = await fetch('https://public-api-demo.clearline.me/v2/pos/clover/widget/start', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    posLocationId: "LOC123",
    terminalId: "TERM-05",
    widgetId: widgets[0].id
  })
});

const { data: session } = await startResponse.json();

// Step 3: Show QR code
const qrResponse = await fetch('https://public-api-demo.clearline.me/v2/pos/clover/widget/showQrCode', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sessionId: session.sessionId,
    posLocationId: "LOC123"
  })
});

const { data: qrData } = await qrResponse.json();
console.log('QR code URL:', qrData.qrCodeHtmlLinkUrl);

Widgets are configured in the ClearLine admin portal. The list endpoint returns only active widgets for your location.

Learn More

View complete widgets API reference →

🔄 Sync Product Catalog

Business Need

Maintain an up-to-date product catalog in ClearLine by automatically syncing products, categories, and promotions from your POS or inventory management system on a scheduled basis.

Technical Overview

Sync Strategies:

Strategy	When to Use	Performance
Full Sync	Initial setup, weekly refresh	Slower, comprehensive
Incremental Sync	Daily updates, changed items only	Faster, efficient
On-Demand Sync	Immediate updates for specific items	Fastest, targeted

API Endpoints Used:

POST /pos/{posSystemId}/company/{posCompanyId}/import/products - Import products
POST /pos/{posSystemId}/company/{posCompanyId}/import/productCategories - Import categories
POST /pos/{posSystemId}/company/{posCompanyId}/import/promotions - Import promotions

Data Requirements:

Product ID (unique identifier)
Product name
Price and category
Manufacturer (optional)

Implementation Example

// Scheduled nightly sync
async function nightlyCatalogSync() {
  try {
    console.log('Starting nightly catalog sync...');
    
    // Fetch products from your POS system
    const posProducts = await fetchProductsFromPOS();
    
    // Transform to ClearLine format
    const products = posProducts.map(p => ({
      productId: p.itemId,
      productName: p.itemName,
      price: p.unitPrice,
      productCategoryId: p.categoryCode,
      manufacturer: p.manufacturer
    }));
    
    // Import products in batches
    const response = await fetch('https://public-api-demo.clearline.me/pos/clover/company/comp123/import/products', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        items: products
      })
    });
    
    const result = await response.json();
    console.log('Import result:', result);
    
  } catch (error) {
    console.error('Catalog sync failed:', error);
  }
}

// Run at 2 AM daily
// cron: 0 2 * * *

Optimization Tips:

Batch products in groups of 500-1000 for optimal performance
Schedule during off-peak hours (2-5 AM)
Implement retry logic with exponential backoff
Monitor sync completion and error rates

Learn More

View complete import API reference →

🔧 Error Recovery & Retry Logic

Business Need

Build resilient POS integrations that gracefully handle network failures, API errors, and timeout scenarios without losing transaction data or frustrating customers.

Technical Overview

Common Error Scenarios:

Network timeouts (slow connection)
5xx server errors (temporary API issues)
4xx client errors (invalid requests)
Authentication failures (expired tokens)
Rate limiting (too many requests)

Retry Strategies:

Error Type	Retry Strategy	Max Retries
Network Timeout	Exponential backoff	3
5xx Server Error	Exponential backoff	3
429 Rate Limit	Wait for Retry-After header	2
401 Unauthorized	Refresh token once	1
4xx Client Error	No retry (fix request)	0

Best Practices:

Implement exponential backoff (1s, 2s, 4s, 8s…)
Log all retry attempts for debugging
Queue failed transactions for later submission
Display clear error messages to cashiers
Provide manual retry option in POS UI

Implementation Example

// Robust API client with retry logic
class ClearLineAPIClient {
  constructor(accessToken) {
    this.accessToken = accessToken;
    this.baseUrl = 'https://public-api-demo.clearline.me';
    this.maxRetries = 3;
  }

  async makeRequest(endpoint, options, retryCount = 0) {
    try {
      const response = await fetch(`${this.baseUrl}${endpoint}`, {
        ...options,
        headers: {
          'Authorization': `Bearer ${this.accessToken}`,
          'Content-Type': 'application/json',
          ...options.headers
        },
        timeout: 30000 // 30 second timeout
      });

      // Handle rate limiting
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 5;
        console.log(`Rate limited. Retrying after ${retryAfter} seconds...`);

        if (retryCount < 2) {
          await this.sleep(retryAfter * 1000);
          return this.makeRequest(endpoint, options, retryCount + 1);
        }
      }

      // Handle authentication failures
      if (response.status === 401) {
        console.log('Access token expired. Refreshing...');
        await this.refreshAccessToken();
        return this.makeRequest(endpoint, options, retryCount + 1);
      }

      // Handle server errors with exponential backoff
      if (response.status >= 500 && retryCount < this.maxRetries) {
        const backoffTime = Math.pow(2, retryCount) * 1000; // 1s, 2s, 4s
        console.log(`Server error. Retrying in ${backoffTime}ms...`);

        await this.sleep(backoffTime);
        return this.makeRequest(endpoint, options, retryCount + 1);
      }

      // Handle client errors (4xx) - don't retry
      if (response.status >= 400 && response.status < 500) {
        const error = await response.json();
        throw new Error(`Client error: ${error.message || response.statusText}`);
      }

      return await response.json();

    } catch (error) {
      // Network/timeout errors
      if (error.name === 'AbortError' || error.message.includes('timeout')) {
        if (retryCount < this.maxRetries) {
          const backoffTime = Math.pow(2, retryCount) * 1000;
          await this.sleep(backoffTime);
          return this.makeRequest(endpoint, options, retryCount + 1);
        }
      }

      // Queue for later retry
      await this.queueFailedRequest(endpoint, options);
      throw error;
    }
  }

  sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }

  async queueFailedRequest(endpoint, options) {
    // Store in local database for later retry
    console.log('Request queued for later retry');
  }

  async refreshAccessToken() {
    // Implement token refresh logic
  }
}

// Usage
const client = new ClearLineAPIClient('YOUR_ACCESS_TOKEN');
await client.makeRequest('/pos/clover/transaction', {
  method: 'POST',
  body: JSON.stringify({ /* transaction data */ })
});

Monitoring & Alerting:

Track retry rates in your monitoring system
Alert on high failure rates (>5% of requests)
Monitor average retry count per request
Set up alerts for queue depth (>100 failed requests)

Learn More

View error handling best practices →

Next Steps

Quick Start Guide

Get started with your first API integration

API Reference

Explore all available endpoints and parameters

Authentication Guide

Learn how to authenticate with ClearLine API

POS Integration

Detailed guides for POS integration workflows

Getting Started

Integration Options

POS Integration

API Reference

🛒 Process POS Transaction → Trigger Loyalty

Learn More

🎟️ Validate Coupon at Checkout

Learn More

📺 Display Marketing Content with Widgets

Learn More

🔄 Sync Product Catalog

Learn More

🔧 Error Recovery & Retry Logic

Learn More

Next Steps

Quick Start Guide

API Reference

Authentication Guide

POS Integration

​🛒 Process POS Transaction → Trigger Loyalty

Learn More

​🎟️ Validate Coupon at Checkout

Learn More

​📺 Display Marketing Content with Widgets

Learn More

​🔄 Sync Product Catalog

Learn More

​🔧 Error Recovery & Retry Logic

Learn More

​Next Steps

Quick Start Guide

API Reference

Authentication Guide

POS Integration

🛒 Process POS Transaction → Trigger Loyalty

🎟️ Validate Coupon at Checkout

📺 Display Marketing Content with Widgets

🔄 Sync Product Catalog

🔧 Error Recovery & Retry Logic

Next Steps