API Documentation

Integrate VeriShelf with your existing systems using our RESTful API. Access product data, manage locations, and sync expiry information programmatically.

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Requirements: API access requires an Enterprise plan subscription. Generate API keys using the POST /api/generate-api-key endpoint or from your dashboard settings.

Base URL

https://api.verishelf.com/api/v1

Note: If your API is deployed to a different domain (e.g., Heroku, Railway), use that domain instead. The base URL format is: https://YOUR_API_DOMAIN/api/v1

Getting Started

Step 1: Run Database Migration

First, run the API keys migration in your Supabase SQL Editor:

-- Run supabase/api_keys_migration.sql in Supabase SQL Editor

Step 2: Generate API Key

Generate an API key using the API endpoint (requires Enterprise plan):

POST https://YOUR_API_DOMAIN/api/generate-api-key
Content-Type: application/json

{
  "userId": "your-user-uuid"
}

Important: Store your API key securely. It will only be shown once.

Step 3: Make Your First API Call

curl -X GET https://YOUR_API_DOMAIN/api/v1/items \
  -H "Authorization: Bearer YOUR_API_KEY"

Endpoints

Get Items

Retrieve all items for your account.

GET /api/v1/items
Authorization: Bearer YOUR_API_KEY

Returns a list of all items with expiry dates, locations, and status.

Response:

{
  "data": [
    {
      "id": 123,
      "name": "Product Name",
      "barcode": "1234567890",
      "location": "Store #001",
      "aisle": "A3",
      "shelf": "S2",
      "expiry_date": "2025-12-31",
      "quantity": 1,
      "category": "Food",
      "price": 9.99,
      "status": "active"
    }
  ],
  "count": 1
}

Create Item

Add a new item to your inventory.

POST /api/v1/items
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "Product Name",
  "barcode": "1234567890",
  "location": "Store #001",
  "aisle": "A3",
  "shelf": "S2",
  "expiry_date": "2025-12-31",
  "quantity": 1,
  "category": "Food",
  "price": 9.99
}

Required: name

Optional: barcode, location, aisle, shelf, expiry_date, quantity, category, price

Update Item

Update an existing item.

PUT /api/v1/items/{item_id}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "expiry_date": "2025-12-31",
  "quantity": 2,
  "status": "discounted"
}

Status values: active, removed, discounted, re-merchandised

Get Single Item

Retrieve a specific item by ID.

GET /api/v1/items/{item_id}
Authorization: Bearer YOUR_API_KEY

Delete Item

Permanently delete an item.

DELETE /api/v1/items/{item_id}
Authorization: Bearer YOUR_API_KEY

Returns 204 No Content on success.

Get Locations

Retrieve all locations for your account.

GET /api/v1/locations
Authorization: Bearer YOUR_API_KEY

Get Expiring Items

Get items expiring within a specified timeframe.

GET /api/v1/items/expiring?days=7
Authorization: Bearer YOUR_API_KEY

Returns items expiring within the next N days (default: 7 days).

Bulk Create Items

Create multiple items in a single request (up to 100 items).

POST /api/v1/items/bulk
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "items": [
    {
      "name": "Product 1",
      "location": "Store #001",
      "expiry_date": "2025-12-31"
    },
    {
      "name": "Product 2",
      "location": "Store #001",
      "expiry_date": "2025-12-31"
    }
  ]
}

Efficient for importing large batches of items from POS/ERP systems.

Get Account Statistics

Get summary statistics for your account.

GET /api/v1/stats
Authorization: Bearer YOUR_API_KEY

Returns total items, expired count, expiring soon count, total value, and location/category counts.

Query Parameters & Filtering

GET /api/v1/items

The items endpoint supports advanced filtering, sorting, and pagination:

?page=1 - Page number (default: 1)
?limit=50 - Items per page (default: 50, max: 100)
?location=Store%20%23001 - Filter by location
?category=Food - Filter by category
?status=active - Filter by status (active, removed, discounted, re-merchandised)
?search=milk - Search in name and barcode
?sort_by=expiry_date - Sort field (name, expiry_date, added_at, quantity, cost, location)
?sort_order=asc - Sort order (asc, desc)

GET /api/v1/items?page=1&limit=50&status=active&sort_by=expiry_date&sort_order=asc
Authorization: Bearer YOUR_API_KEY

Rate Limits

API requests are rate-limited to ensure fair usage:

Professional Plan: 1,000 requests per hour
Enterprise Plan: 10,000 requests per hour

Webhooks

Subscribe to webhook events to receive real-time notifications:

item.expiring - Item is approaching expiration
item.expired - Item has expired
item.removed - Item was removed from shelf

Configure webhooks from your dashboard settings.

Code Examples

Here are working examples for common languages:

JavaScript/Node.js

const API_KEY = 'your-api-key-here';
const BASE_URL = 'https://YOUR_API_DOMAIN/api/v1';

// Get all items
async function getItems() {
  const response = await fetch(`${BASE_URL}/items`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });
  const data = await response.json();
  return data;
}

// Create item
async function createItem(item) {
  const response = await fetch(`${BASE_URL}/items`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(item)
  });
  return await response.json();
}

Python

import requests

API_KEY = 'your-api-key-here'
BASE_URL = 'https://YOUR_API_DOMAIN/api/v1'
HEADERS = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

# Get all items
def get_items():
    response = requests.get(f'{BASE_URL}/items', headers=HEADERS)
    return response.json()

# Create item
def create_item(item_data):
    response = requests.post(
        f'{BASE_URL}/items',
        headers=HEADERS,
        json=item_data
    )
    return response.json()

cURL

# Get all items
curl -X GET https://YOUR_API_DOMAIN/api/v1/items \
  -H "Authorization: Bearer YOUR_API_KEY"

# Create item
curl -X POST https://YOUR_API_DOMAIN/api/v1/items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Name",
    "location": "Store #001",
    "expiry_date": "2025-12-31"
  }'

JavaScript SDK (Browser/Node.js)

Download our simple JavaScript SDK for easy integration:

<!-- Include in HTML -->
<script src="verishelf-sdk.js"></script>
<script>
  const client = new VeriShelfClient('YOUR_API_KEY', 'https://YOUR_API_DOMAIN');
  const items = await client.getItems();
</script>

// Or in Node.js
const VeriShelfClient = require('./verishelf-sdk.js');
const client = new VeriShelfClient('YOUR_API_KEY', 'https://YOUR_API_DOMAIN');

Download verishelf-sdk.js

Note: Official npm/pip packages are coming soon. For now, use the JavaScript SDK above or the REST API directly.

Need Help?

For API support, integration assistance, or to request additional endpoints, contact our developer team.

Contact API Support