API Documentation

Complete REST API reference for building integrations with StuffList. All endpoints require authentication unless specified as public.

Quick Start

Base URL

https://stufflist.nobregas.org/api/

Authentication

All authenticated endpoints require a CSRF token in the request headers:

X-CSRF-TOKEN: your_csrf_token_here

The token is available in the page via the CSRF_TOKEN JavaScript variable.

Response Format

All responses are in JSON format with a consistent structure:

{
  "success": true|false,
  "message": "Human readable message",
  "data": { /* Response data */ }
}

Categories API

Manage product categories and subcategories

GET /api/categories.php

Retrieve all categories for the authenticated user's store.

Response:

{
  "success": true,
  "categories": [
    {
      "id": 1,
      "store_id": 1,
      "parent_id": null,
      "name": "Electronics",
      "slug": "electronics",
      "description": "Electronic devices and accessories",
      "icon": "fas fa-laptop",
      "is_active": 1,
      "sort_order": 0,
      "item_count": 15,
      "created_at": "2026-01-08 12:00:00",
      "updated_at": "2026-01-08 12:00:00"
    }
  ]
}
GET /api/categories.php?id={id}

Retrieve a single category by ID.

Parameters:

  • id (integer) - Category ID

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Electronics",
    "slug": "electronics",
    "description": "Electronic devices",
    "icon": "fas fa-laptop",
    "is_active": 1,
    "item_count": 15
  }
}
POST /api/categories.php

Create a new category or update existing (if id is provided).

Headers:

  • Content-Type: application/json
  • X-CSRF-TOKEN: {token}

Request Body:

{
  "id": 0,                    // Optional: 0 or omit for create, ID for update
  "name": "Smartphones",      // Required
  "description": "Latest phones",
  "parent_id": 1,             // Optional: for subcategories
  "icon": "fas fa-mobile-alt",
  "is_active": 1
}

Response:

{
  "success": true,
  "message": "Category created",
  "category_id": 5
}
PATCH /api/categories.php

Toggle category active status.

Request Body:

{
  "id": 5,
  "is_active": 0  // 0 = inactive, 1 = active
}

Response:

{
  "success": true,
  "message": "Status updated"
}
PUT /api/categories.php

Reorder categories by updating sort_order.

Request Body:

{
  "action": "reorder",
  "items": [
    { "id": 1, "sort_order": 0 },
    { "id": 3, "sort_order": 1 },
    { "id": 2, "sort_order": 2 }
  ]
}
DELETE /api/categories.php?id={id}

Delete a category. Items in this category will be uncategorized.

Parameters:

  • id (integer) - Category ID to delete

Response:

{
  "success": true,
  "message": "Category deleted"
}

Items API

Manage catalog items and products

GET /api/items.php

Retrieve items with optional filtering and pagination.

Query Parameters:

  • category_id (integer) - Filter by category
  • status (string) - Filter by availability status
  • search (string) - Search in name/description
  • page (integer) - Page number (default: 1)
  • limit (integer) - Items per page (default: 20, max: 50)

Response:

{
  "success": true,
  "items": [
    {
      "id": 1,
      "name": "iPhone 15 Pro",
      "slug": "iphone-15-pro",
      "description": "Latest flagship smartphone",
      "price": 999.99,
      "compare_price": 1199.99,
      "availability": "in_stock",
      "category_id": 1,
      "category_name": "Smartphones",
      "image": "/uploads/items/abc123.jpg",
      "is_featured": 1,
      "is_active": 1
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "limit": 20,
    "pages": 3
  }
}
POST /api/items.php

Create a new item in the catalog.

Request Body Example:

{
  "name": "iPhone 15 Pro",
  "description": "Latest flagship smartphone with A17 Pro chip",
  "category_id": 1,
  "price": 999.99,
  "compare_price": 1199.99,
  "price_display": "visible",  // visible, contact, hidden
  "availability": "in_stock",  // in_stock, out_of_stock, pre_order
  "sku": "IPHONE15PRO",
  "is_featured": 1,
  "is_active": 1
}
DELETE /api/items.php?id={id}

Delete an item and all associated data.

Store API

Manage store settings and information

GET /api/store.php

Get current user's store information.

{
  "success": true,
  "store": {
    "id": 1,
    "slug": "mystore",
    "name": "My Awesome Store",
    "description": "Best products in town",
    "business_type": "retail",
    "phone": "+1234567890",
    "whatsapp": "+1234567890",
    "email": "store@example.com",
    "is_published": 1
  }
}
POST/PUT /api/store.php

Create or update store information.

Request Body:

{
  "name": "My Store",
  "description": "Store description",
  "business_type": "retail",
  "phone": "+1234567890",
  "whatsapp": "+1234567890",
  "email": "contact@store.com",
  "website": "https://store.com",
  "address": "123 Main St",
  "city": "New York",
  "country": "USA",
  "is_published": 1
}

Upload API

Upload images for items, logos, and covers

POST /api/upload.php

Upload an image file (max 5MB).

Headers:

  • Content-Type: multipart/form-data
  • X-CSRF-TOKEN: {token}

Form Data:

  • file - The image file
  • type - Upload type: item, logo, cover, category
  • item_id - Required if type=item
  • csrf_token - CSRF token

Supported Formats:

JPEG, PNG, WebP, GIF

Response:

{
  "success": true,
  "url": "/uploads/items/abc123def456.jpg",
  "image_id": 42
}

Analytics API

Track events and retrieve analytics data

POST /api/analytics.php PUBLIC

Track analytics events (no authentication required).

Request Body:

{
  "store_id": 1,
  "category_id": 5,     // Optional
  "item_id": 42,        // Optional
  "event_type": "view"  // view, qr_scan, cta_whatsapp, cta_phone, cta_email, cta_website, share
}

Event Types:

  • view - Page view
  • qr_scan - QR code scanned
  • cta_whatsapp - WhatsApp button clicked
  • cta_phone - Phone button clicked
  • cta_email - Email button clicked
  • cta_website - Website link clicked
  • share - Share button used
GET /api/analytics.php

Get analytics summary for authenticated user's store.

Query Parameters:

  • range - Time range: 7d, 30d, 90d (default: 7d)

Response:

{
  "success": true,
  "stats": {
    "views": 1542,
    "qr_scans": 87,
    "cta_clicks": 245,
    "unique_visitors": 892
  },
  "top_items": [...],
  "device_breakdown": {...},
  "daily_stats": [...]
}

HTTP Status Codes

200 OK

Request succeeded

400 Bad Request

Invalid request parameters

401 Unauthorized

Authentication required

403 Forbidden

Invalid CSRF token or insufficient permissions

404 Not Found

Resource not found

500 Internal Server Error

Server error occurred

Important Notes

  • All timestamps are in UTC
  • All authenticated endpoints require valid session and CSRF token
  • File uploads limited to 5MB per file
  • Pagination maximum limit is 50 items per page
  • Category limits depend on user's subscription plan
Back to Home