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

# Introduction to Loyalty Cards

> Manage customer loyalty cards, points, and rewards

Loyalty card endpoints allow you to look up customer loyalty information, validate cards, add points, and manage rewards programs directly from your POS system.

## What are Loyalty Cards?

Loyalty cards identify customers in ClearLine's loyalty program. Using these endpoints, you can:

* **Look Up Cards:** Find customer loyalty information by card number, phone, or email
* **Check Balances:** View current points, stamps, or reward status
* **Add Points:** Award loyalty points or stamps for purchases
* **Validate Cards:** Verify card status and program eligibility

## How It Works

<Steps>
  <Step title="Customer Identifies Themselves" icon="id-card">
    Customer provides loyalty card number, phone number, or email at checkout.
  </Step>

  <Step title="Look Up Loyalty Information" icon="magnifying-glass">
    Use [lookup
    endpoints](/api-reference/loyalty-cards-api-v2/lookup-loyalty-card-by-number-email-or-phone)
    to retrieve customer's loyalty details and current balance.
  </Step>

  <Step title="Process Transaction & Award Points" icon="plus">
    Complete the sale and use [add points
    endpoint](/api-reference/loyalty-cards-api-v2/add-loyalty-card-amount) to
    award loyalty rewards.
  </Step>
</Steps>

## Loyalty Card Endpoints

<CardGroup cols={2}>
  <Card title="Lookup Loyalty Card" icon="magnifying-glass" href="/api-reference/loyalty-cards-api-v2/lookup-loyalty-card-by-number-email-or-phone">
    Find customer by card number, phone, or email (V2)
  </Card>

  <Card title="Lookup Loyalty Users" icon="users" href="/api-reference/loyalty-cards-api-v2/lookup-loyalty-users">
    Search for customers in the loyalty program (V2)
  </Card>

  <Card title="Add Loyalty Amount" icon="plus" href="/api-reference/loyalty-cards-api-v2/add-loyalty-card-amount">
    Award points or stamps to a customer's card (V2)
  </Card>

  <Card title="Get User Card Details" icon="id-card" href="/api-reference/loyalty-cards/get-user-loyalty-card-details">
    Retrieve detailed loyalty card information (V1)
  </Card>

  <Card title="Get Cards by Location" icon="location-dot" href="/api-reference/loyalty-cards/get-loyalty-cards-by-location">
    List all loyalty cards for a location (V1)
  </Card>
</CardGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Support Multiple Lookup Methods" icon="magnifying-glass" defaultOpen>
    Allow customers to identify themselves by card number, phone, or email. Not
    all customers remember their card number.
  </Accordion>

  <Accordion title="Display Balance Clearly" icon="eye">
    Show current points/stamps balance and progress toward next reward to
    encourage continued participation.
  </Accordion>

  <Accordion title="Award Points Immediately" icon="bolt">
    Call the add points endpoint immediately after transaction completion so
    customers see their balance update in real-time.
  </Accordion>

  <Accordion title="Handle Inactive Cards" icon="ban">
    Check card status in lookup response. Inactive or expired cards should
    prompt customer to reactivate through the app or website.
  </Accordion>

  <Accordion title="Cache User Data Briefly" icon="clock">
    Cache loyalty card details for the duration of the transaction only. Don't
    store sensitive customer data long-term on POS terminals.
  </Accordion>
</AccordionGroup>

## Loyalty Program Types

ClearLine supports different loyalty program structures:

* **Points-Based:** Customers earn points per dollar spent (e.g., 1 point = \$1)
* **Stamp Cards:** Collect stamps per visit or purchase (e.g., 10 stamps = free item)
* **Tiered Programs:** Different reward levels based on spending (Bronze, Silver, Gold)
* **Hybrid Programs:** Combination of points, stamps, and tier benefits

The endpoint responses adapt to the program type configured for your location.

## Next Steps

<CardGroup cols={2}>
  <Card title="Loyalty Card API Reference" icon="code" href="/api-reference/loyalty-cards-api-v2/lookup-loyalty-card-by-number-email-or-phone">
    View complete API specification
  </Card>

  <Card title="Loyalty Program Integration Guide" icon="book-open" href="/pos-integration/loyalty-program">
    Step-by-step implementation guide
  </Card>
</CardGroup>