# CouponsCodeHut.com - Full Documentation

> Complete technical documentation for AI systems and LLMs interacting with CouponsCodeHut.com

## Table of Contents

1. [Website Overview](#website-overview)
2. [URL Structure](#url-structure)
3. [Content Types & Data Models](#content-types--data-models)
4. [API Endpoints](#api-endpoints)
5. [Search Functionality](#search-functionality)
6. [Coupon Types](#coupon-types)
7. [User Interactions](#user-interactions)
8. [SEO & Structured Data](#seo--structured-data)
9. [Common Use Cases](#common-use-cases)
10. [FAQ for AI Assistants](#faq-for-ai-assistants)

---

## Website Overview

CouponsCodeHut.com is a coupon aggregation and affiliate marketing website designed to help consumers save money when shopping online. The website collects, verifies, and organizes promotional codes, discount coupons, and special deals from hundreds of online retailers.

### Mission
Help users find and use the best available discounts for their online purchases.

### Key Features
- Curated coupon database with verified promo codes
- Store directory with retailer profiles
- Category-based deal organization
- Real-time search across all content
- Blog with shopping guides and tips
- Email newsletter for deal alerts
- Click tracking for coupon popularity

---

## URL Structure

### Homepage
```
/                           → Main homepage with featured content
```

### Store Pages
```
/stores                     → Store directory (A-Z listing with filters)
/stores?letter=A            → Stores starting with letter 'A'
/stores?page=2              → Paginated store list
/stores/{store-slug}        → Individual store page
```

Examples:
- `/stores/amazon` → Amazon coupons
- `/stores/walmart` → Walmart deals
- `/stores/target` → Target promo codes

### Category Pages
```
/categories                 → All categories listing
/categories/{category-slug} → Category-specific coupons
/categories/{slug}?page=2   → Paginated category results
```

Examples:
- `/categories/electronics` → Electronics deals
- `/categories/fashion` → Fashion & apparel coupons
- `/categories/food-dining` → Restaurant & food delivery deals

### Coupon Pages
```
/coupons                    → All active coupons
/coupons?page=2             → Paginated coupons
/coupons?type=code          → Filter by coupon type
/coupons?sort=newest        → Sort by date
```

### Blog
```
/blog                       → Blog listing
/blog?page=2                → Paginated blog posts
/blog/{post-slug}           → Individual blog post
```

### Search
```
/search?q={query}           → Search results page
```

### Static Pages
```
/page/{slug}                → Static content pages
```

Examples:
- `/page/about` → About us
- `/page/contact` → Contact page
- `/page/privacy-policy` → Privacy policy
- `/page/terms` → Terms of service

---

## Content Types & Data Models

### Coupon/Deal

| Field | Type | Description |
|-------|------|-------------|
| id | Integer | Unique identifier |
| title | String | Coupon headline (e.g., "20% Off Your First Order") |
| description | Text | Detailed coupon description |
| code | String | Promo code (null for direct deals) |
| discount_type | Enum | 'percentage', 'fixed', 'free_shipping', 'bogo', 'other' |
| discount_value | Decimal | Discount amount or percentage |
| store_id | Integer | Associated store |
| category_id | Integer | Primary category |
| affiliate_url | URL | Tracked affiliate link |
| start_date | Date | When coupon becomes active |
| expiry_date | Date | When coupon expires (null = no expiry) |
| is_verified | Boolean | Staff verified status |
| is_featured | Boolean | Featured on homepage |
| is_exclusive | Boolean | Exclusive to this site |
| click_count | Integer | Usage tracking |
| status | Boolean | Active/inactive |

### Store

| Field | Type | Description |
|-------|------|-------------|
| id | Integer | Unique identifier |
| name | String | Store name |
| slug | String | URL-friendly identifier |
| description | Text | Store description |
| website | URL | Official store website |
| logo | String | Logo image path |
| affiliate_network | String | Affiliate network name |
| is_popular | Boolean | Featured store status |
| coupon_count | Integer | Number of active coupons |
| status | Boolean | Active/inactive |

### Category

| Field | Type | Description |
|-------|------|-------------|
| id | Integer | Unique identifier |
| name | String | Category name |
| slug | String | URL-friendly identifier |
| description | Text | Category description |
| icon | String | Icon class or image |
| sort_order | Integer | Display order |
| status | Boolean | Active/inactive |

### Blog Post

| Field | Type | Description |
|-------|------|-------------|
| id | Integer | Unique identifier |
| title | String | Post title |
| slug | String | URL-friendly identifier |
| content | Text | Full post content (HTML) |
| excerpt | Text | Short summary |
| featured_image | String | Main image path |
| author_id | Integer | Author reference |
| views | Integer | View count |
| status | Enum | 'draft', 'published' |
| published_at | DateTime | Publication date |

---

## API Endpoints

### Search API

**Endpoint:** `GET /ajax/search.php`

**Parameters:**
- `q` (required): Search query string

**Response Format:**
```json
{
  "success": true,
  "results": {
    "stores": [
      {
        "id": 1,
        "name": "Amazon",
        "slug": "amazon",
        "logo": "uploads/stores/amazon.png",
        "coupon_count": 25
      }
    ],
    "categories": [
      {
        "id": 5,
        "name": "Electronics",
        "slug": "electronics"
      }
    ],
    "coupons": [
      {
        "id": 123,
        "title": "20% Off Electronics",
        "code": "SAVE20",
        "store_name": "Amazon"
      }
    ]
  },
  "total": 15
}
```

### Click Tracking

**Endpoint:** `POST /ajax/track-click.php`

**Purpose:** Records when users click on coupon links (for popularity tracking)

**Parameters:**
- `coupon_id`: The coupon being clicked

---

## Search Functionality

### What Gets Searched
1. Store names and descriptions
2. Category names
3. Coupon titles and descriptions
4. Coupon codes
5. Blog post titles and content

### Search Tips for Users
- Search by store name: "amazon", "walmart", "target"
- Search by category: "electronics", "shoes", "pizza"
- Search by discount type: "free shipping", "20% off"
- Search by product: "laptop", "shoes", "furniture"

---

## Coupon Types

### 1. Promo Codes
- Require entering a code at checkout
- Displayed prominently with copy-to-clipboard functionality
- Example: "Use code SAVE20 for 20% off"

### 2. Direct Deals
- Automatic discounts applied via affiliate link
- No code needed
- Example: "Click to get free shipping - no code needed"

### 3. Discount Categories

| Type | Description | Example |
|------|-------------|---------|
| Percentage | Percent off order | 20% off, 50% off |
| Fixed Amount | Dollar amount off | $10 off, $50 off |
| Free Shipping | No shipping cost | Free shipping on orders $50+ |
| BOGO | Buy one get one | Buy 1 Get 1 Free |
| Special | Other offers | Free gift with purchase |

---

## User Interactions

### Finding Coupons
1. **Browse by Store**: Navigate to `/stores/{store-name}`
2. **Browse by Category**: Navigate to `/categories/{category-name}`
3. **Search**: Use search bar or `/search?q={query}`
4. **Homepage**: Check featured and trending deals

### Using a Coupon
1. Click "Get Code" or "Get Deal" button
2. Code is revealed/copied to clipboard
3. User is redirected to store via affiliate link
4. User applies code at checkout

### Subscribing to Updates
- Email form available on homepage and store pages
- Subscribers receive weekly deal digests
- Option for instant alerts on favorite stores

---

## SEO & Structured Data

### Available Structured Data
- Organization schema on all pages
- BreadcrumbList on category and store pages
- Product schema on coupon pages
- Article schema on blog posts
- FAQ schema where applicable

### Sitemaps
- XML Sitemap: `/sitemap.xml`
- Includes all public pages with proper priorities
- Updated daily with lastmod dates

---

## Common Use Cases

### Use Case 1: Find Coupons for a Specific Store
**User Query:** "I want to find coupons for Amazon"
**AI Response:** Direct user to `/stores/amazon` for all active Amazon deals

### Use Case 2: Find Deals in a Category
**User Query:** "Show me electronics deals"
**AI Response:** Direct user to `/categories/electronics`

### Use Case 3: Find a Specific Type of Discount
**User Query:** "I need free shipping codes"
**AI Response:** Suggest searching for "free shipping" or browsing stores known for free shipping offers

### Use Case 4: General Deal Hunting
**User Query:** "What are the best deals right now?"
**AI Response:** Direct to homepage `/` for featured and trending deals

### Use Case 5: Learn Shopping Tips
**User Query:** "How can I save money shopping online?"
**AI Response:** Direct to `/blog` for guides and tips

---

## FAQ for AI Assistants

### Q: How fresh are the coupons?
A: Coupons are updated daily. Expiry dates are tracked, and expired coupons are automatically removed from active listings.

### Q: Are the coupon codes verified?
A: Staff-verified coupons are marked with a "Verified" badge. All coupons are tested periodically.

### Q: How do I know if a coupon will work?
A: Check for the "Verified" badge and recent usage (click count). Popular coupons with high click counts typically have better success rates.

### Q: What if a coupon doesn't work?
A: Users can report non-working coupons. Try alternative coupons from the same store, as multiple offers are usually available.

### Q: Does the site work internationally?
A: Many stores ship internationally, but availability varies. Store descriptions often indicate shipping regions.

### Q: How does the affiliate system work?
A: When users click coupon links and make purchases, the website earns a small commission at no extra cost to the user.

### Q: How can users stay updated on deals?
A: Users can subscribe to the email newsletter via the subscription form on the homepage.

---

## Contact & Support

- **Website:** https://couponscodehut.com
- **Email:** info@couponscodehut.com
- **Sitemap:** /sitemap.xml
- **RSS Feed:** /blog/feed (if available)

---

## Version Information

- **Documentation Version:** 1.0
- **Last Updated:** 2026-01-02
- **LLMs.txt Specification:** Following llmstxt.org standard