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

# Use Cases

> Real-world scenarios and implementation examples for ClearLine POS API integration

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

<AccordionGroup>
  <Accordion title="Business Need" icon="store">
    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.
  </Accordion>

  <Accordion title="Technical Overview" icon="code">
    This workflow involves three key steps:

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

    **API Endpoints Used:**

    * `POST /pos/{posSystemId}/startInteraction` - [Initiate POS session](/api-reference/transactions/start-pos-interaction)
    * `POST /pos/{posSystemId}/transaction` - [Submit transaction data](/api-reference/transactions/create-pos-transaction)
  </Accordion>

  <Accordion title="Implementation Example" icon="terminal">
    ```javascript theme={null}
    // 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);
    }
    ```

    <Note>
      Include customer contact information in the transaction request to enable loyalty tracking and marketing campaign triggers.
    </Note>
  </Accordion>
</AccordionGroup>

<Card title="Learn More" icon="book" href="/api-reference/transactions/introduction">
  View complete transaction API reference →
</Card>

***

## 🎟️ Validate Coupon at Checkout

<AccordionGroup>
  <Accordion title="Business Need" icon="ticket">
    Enable cashiers to scan or enter coupon codes during checkout and validate them in real-time before applying discounts.
  </Accordion>

  <Accordion title="Technical Overview" icon="code">
    **Workflow:**

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

    **API Endpoints Used:**

    * `POST /v2/pos/{posSystemId}/coupon/couponCodes/lookup` - [Search for coupons](/api-reference/coupons-v2/lookup-coupons-by-code)
    * `POST /v2/pos/{posSystemId}/coupon/couponCodes/validate` - [Validate coupon](/api-reference/coupons-v2/validate-coupon)

    <Note>
      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.
    </Note>
  </Accordion>

  <Accordion title="Implementation Example" icon="terminal">
    ```javascript theme={null}
    // 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');
    }
    ```

    <Warning>
      These endpoints verify coupon existence and status. Your POS system must implement discount calculation logic based on the coupon details returned.
    </Warning>
  </Accordion>
</AccordionGroup>

<Card title="Learn More" icon="book" href="/api-reference/coupons/introduction">
  View complete coupons API reference →
</Card>

***

## 📺 Display Marketing Content with Widgets

<AccordionGroup>
  <Accordion title="Business Need" icon="tv">
    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.
  </Accordion>

  <Accordion title="Technical Overview" icon="code">
    **Workflow:**

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

    **API Endpoints Used:**

    * `POST /v2/pos/{posSystemId}/widget/list` - [Get available widgets](/api-reference/widgets/get-widgets-list)
    * `POST /v2/pos/{posSystemId}/widget/start` - [Start widget session](/api-reference/widgets/start-pos-widget-session)
    * `POST /v2/pos/{posSystemId}/widget/showQrCode` - [Generate QR code](/api-reference/widgets/show-qr-code)
    * `POST /v2/pos/{posSystemId}/widget/sendMessage` - [Send SMS/email](/api-reference/widgets/send-message)

    **Widget Types:**

    * Loyalty enrollment
    * Promotion signup
    * Digital receipt delivery
    * Survey/feedback collection
  </Accordion>

  <Accordion title="Implementation Example" icon="terminal">
    ```javascript theme={null}
    // 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);
    ```

    <Tip>
      Widgets are configured in the ClearLine admin portal. The list endpoint returns only active widgets for your location.
    </Tip>
  </Accordion>
</AccordionGroup>

<Card title="Learn More" icon="book" href="/api-reference/widgets/introduction">
  View complete widgets API reference →
</Card>

***

## 🔄 Sync Product Catalog

<AccordionGroup>
  <Accordion title="Business Need" icon="box">
    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.
  </Accordion>

  <Accordion title="Technical Overview" icon="code">
    **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](/api-reference/import/import-products-to-the-system)
    * `POST /pos/{posSystemId}/company/{posCompanyId}/import/productCategories` - [Import categories](/api-reference/import/import-products-categories-to-the-system)
    * `POST /pos/{posSystemId}/company/{posCompanyId}/import/promotions` - [Import promotions](/api-reference/import/import-promotions-to-the-system)

    **Data Requirements:**

    * Product ID (unique identifier)
    * Product name
    * Price and category
    * Manufacturer (optional)
  </Accordion>

  <Accordion title="Implementation Example" icon="terminal">
    ```javascript theme={null}
    // 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 * * *
    ```

    <Tip>
      **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
    </Tip>
  </Accordion>
</AccordionGroup>

<Card title="Learn More" icon="book" href="/api-reference/import/introduction">
  View complete import API reference →
</Card>

***

## 🔧 Error Recovery & Retry Logic

<AccordionGroup>
  <Accordion title="Business Need" icon="triangle-exclamation">
    Build resilient POS integrations that gracefully handle network failures, API errors, and timeout scenarios without losing transaction data or frustrating customers.
  </Accordion>

  <Accordion title="Technical Overview" icon="code">
    **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
  </Accordion>

  <Accordion title="Implementation Example" icon="terminal">
    ```javascript theme={null}
    // 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 */ })
    });
    ```

    <Tip>
      **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)
    </Tip>
  </Accordion>
</AccordionGroup>

<Card title="Learn More" icon="book" href="/api-reference/authentication/introduction#troubleshooting">
  View error handling best practices →
</Card>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start Guide" icon="rocket" href="/api-reference/quick-start">
    Get started with your first API integration
  </Card>

  {" "}

  <Card title="API Reference" icon="book" href="/api-reference/openapi-reference">
    Explore all available endpoints and parameters
  </Card>

  {" "}

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

  <Card title="POS Integration" icon="store" href="/pos-integration">
    Detailed guides for POS integration workflows
  </Card>
</CardGroup>