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

> Look up, validate, and apply customer coupons at checkout

Coupon endpoints allow you to search for customer coupons, validate coupon codes, and apply discounts at the point of sale. This enables you to integrate ClearLine's coupon system directly into your checkout flow.

## What are Coupons?

Coupons are digital or physical discount codes that customers can redeem during purchase. Using these endpoints, you can:

* **Search Coupons:** Find available coupons for a customer by phone, email, or loyalty card
* **Validate Codes:** Check if a coupon code is valid and eligible for use
* **Apply Discounts:** Calculate and apply coupon discounts to transactions
* **Track Usage:** Monitor which coupons are redeemed and by whom

## How It Works

<Steps>
  <Step title="Customer Provides Coupon" icon="ticket">
    Customer enters a coupon code or is identified by phone/email/loyalty card
    at checkout.
  </Step>

  <Step title="Look Up or Validate Coupon" icon="magnifying-glass">
    Use [lookup
    endpoints](/api-reference/coupons-api-v2/lookup-and-validate-coupon-codes)
    to find customer's available coupons or validate a specific code.
  </Step>

  <Step title="Apply Discount" icon="percent">
    Calculate discount amount based on coupon rules and apply to the transaction
    total.
  </Step>

  <Step title="Complete Transaction" icon="check">
    Send the transaction with coupon details to mark it as redeemed.
  </Step>
</Steps>

## Coupon Endpoints

<CardGroup cols={2}>
  <Card title="Lookup & Validate Coupon Codes" icon="magnifying-glass" href="/api-reference/coupons-api-v2/lookup-and-validate-coupon-codes">
    Find and validate customer coupons (V2)
  </Card>

  <Card title="Lookup Coupon Codes" icon="search" href="/api-reference/coupons-api-v2/lookup-coupon-codes">
    Search for available coupon codes (V2)
  </Card>

  <Card title="Lookup Coupons" icon="ticket" href="/api-reference/coupons-api-v2/lookup-coupons">
    Get coupons for a customer or location (V2)
  </Card>

  <Card title="Search User Coupons" icon="user-tag" href="/api-reference/coupons/search-user-coupons">
    Search coupons by customer parameters (V1)
  </Card>

  <Card title="Get Active Coupons by Location" icon="location-dot" href="/api-reference/coupons/get-active-coupons-by-location">
    List all active coupons for a location (V1)
  </Card>

  <Card title="Validate Coupon by Transaction" icon="check-double" href="/api-reference/coupons/validate-coupon-by-transaction">
    Validate coupon against transaction details (V1)
  </Card>
</CardGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Validate Before Applying" icon="shield-check" defaultOpen>
    Always validate coupons before applying discounts. Check expiration dates,
    usage limits, minimum purchase amounts, and product restrictions.
  </Accordion>

  <Accordion title="Show Available Coupons Proactively" icon="eye">
    When a customer identifies themselves (loyalty card, phone), automatically
    look up and display their available coupons to encourage usage.
  </Accordion>

  <Accordion title="Handle Multiple Coupons" icon="layer-group">
    Support applying multiple coupons when allowed. Validate each coupon
    individually and check for conflicts or stacking restrictions.
  </Accordion>

  <Accordion title="Display Clear Discount Amounts" icon="dollar-sign">
    Show customers the exact discount amount before completing the transaction.
    Make it clear how much they're saving.
  </Accordion>

  <Accordion title="Mark as Redeemed Immediately" icon="clock">
    Include coupon information in the transaction endpoint call to mark coupons
    as redeemed and prevent double usage.
  </Accordion>
</AccordionGroup>

## Coupon Types

ClearLine supports various coupon structures:

* **Percentage Off:** Discount percentage (e.g., 20% off)
* **Fixed Amount:** Specific dollar discount (e.g., \$5 off)
* **BOGO:** Buy one get one free or discounted
* **Free Item:** Specific product at no charge
* **Minimum Purchase:** Discounts requiring minimum spend
* **Product-Specific:** Valid only for certain items or categories

The endpoint responses include coupon type and discount rules for proper application.

## Next Steps

<CardGroup cols={2}>
  <Card title="Coupon API Reference" icon="code" href="/api-reference/coupons-api-v2/lookup-and-validate-coupon-codes">
    View complete API specification (V2)
  </Card>

  <Card title="Coupon Integration Guide" icon="book-open" href="/pos-integration/coupons">
    Step-by-step implementation guide with examples
  </Card>

  <Card title="Validate Coupons via Transaction" icon="receipt" href="/pos-integration/coupons/validate-coupon-via-transaction">
    Learn how to validate coupons during checkout
  </Card>

  <Card title="Sync Coupons to POS" icon="arrows-rotate" href="/pos-integration/coupons/coupons-sync-from-cmc-to-pos">
    Keep your POS system in sync with ClearLine coupons
  </Card>
</CardGroup>