Item Variants API Documentation

This document describes the item variants endpoint for retrieving paginated lists of item variants in the optical store system. Item variants represent specific configurations of items (e.g., different lens prescriptions, treatments, or colors) and can be searched by barcode or name.

Endpoint Details

Base URL: https://joptic.jethings.com

Required Headers

x-store-id: <store_id>
Authorization: Bearer <token>

Authentication

All endpoints require user authentication. The user ID is extracted from the JWT token (req.user.sub), and store access is validated via the @StoreId() decorator. Only item variants belonging to products in the authenticated user’s store are returned.

Get All Item Variants

Retrieve a paginated list of item variants for the current store. Supports searching by barcode or item variant name. Endpoint: GET /item-variants

Query Parameters

Parameter	Type	Required	Default	Description
`search`	`string`	No	—	Search term to filter by barcode or item variant name
`page`	`number`	No	`1`	Page number (min: 1)
`limit`	`number`	No	`10`	Items per page (min: 1, max: 100)

Search Functionality

The search parameter performs a case-insensitive search across:

Barcodes: Searches in the barcode table and returns item variants associated with matching barcodes
Item Variant Names: Searches directly in item variant names

When searching, the system searches both barcodes and item variant names in parallel for optimal performance. Results are combined and deduplicated. If no matches are found, an empty array is returned with pagination metadata.

Success Response

{
  "data": [
    {
      "id": "variant_123",
      "name": "1.50 PhGy BB +0.00 +0.25",
      "description": "Standard lens with anti-reflective coating",
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "variant_124",
      "name": "1.67 Clear AR -2.00 -0.50",
      "description": "High-index lens with blue light filter",
      "isActive": true,
      "createdAt": "2024-01-14T09:20:00.000Z",
      "updatedAt": "2024-01-14T09:20:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  }
}

Response Fields

id (string) - Unique identifier for the item variant
name (string | null) - Name of the item variant (e.g., “1.50 PhGy BB +0.00 +0.25”)
description (string | null) - Optional description of the item variant
isActive (boolean) - Whether the item variant is currently active
createdAt (Date) - Timestamp when the item variant was created
updatedAt (Date) - Timestamp when the item variant was last updated

Pagination Fields

page (number) - Current page number
limit (number) - Number of items per page
total (number) - Total number of item variants matching the criteria
totalPages (number) - Total number of pages available
hasNext (boolean) - Whether a next page exists
hasPrev (boolean) - Whether a previous page exists

Results are paginated for performance. Default sorting is by creation date (newest first). Only non-deleted item variants (deletedAt IS NULL) belonging to products in the authenticated user’s store are returned.

Example Request

curl -X GET "https://joptic.jethings.com/item-variants?search=1.50&page=1&limit=20" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>"

Example: Search by Barcode

curl -X GET "https://joptic.jethings.com/item-variants?search=1234567890123&page=1&limit=10" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>"

Example: Search by Name

curl -X GET "https://joptic.jethings.com/item-variants?search=PhGy&page=1&limit=10" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>"

Example: Get All Variants (No Search)

curl -X GET "https://joptic.jethings.com/item-variants?page=1&limit=10" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>"

Possible Errors

401 Unauthorized - Missing or invalid authentication token
403 Forbidden - User does not have access to the store
500 Internal Server Error - Server error

Business Logic

Item Variant Retrieval Process

Store Filtering

Store FilteringThe system automatically filters item variants by:

Joining item variants with items and products
Filtering products by the authenticated user’s store ID
Ensuring only variants from accessible stores are returned

This prevents unauthorized access to item variants from other stores.

Search Implementation

Search ImplementationWhen a search term is provided, the system:

Searches barcodes in parallel with item variant names
Finds matching barcodes and retrieves associated item variant IDs
Finds matching item variant names directly
Combines and deduplicates results
Filters the final results by store and deletion status

This dual-search approach allows finding variants by either their barcode or name.

Soft Delete Handling

Soft Delete HandlingThe system automatically excludes deleted item variants:

Only variants where deletedAt IS NULL are returned
Deleted variants are permanently excluded from results
This ensures data integrity and prevents access to archived items

Pagination

PaginationPagination is enforced with:

Minimum page: 1
Minimum limit: 1
Maximum limit: 100
Default values: page=1, limit=10
Results are ordered by creation date (newest first)

This ensures efficient data retrieval and prevents performance issues.

Barcode Association

Barcode AssociationWhen searching by barcode:

The system finds matching barcodes in the barcode table
Retrieves item variant IDs from the barcode-item association table
Only active barcode associations (isActive = true) are considered
Results are combined with name-based search results

This allows finding item variants by scanning or entering barcodes.

Item Variant States

Active Variants

Active (isActive: true)
Variant is currently available for use in inventory and sales

Inactive Variants

Inactive (isActive: false)
Variant exists but is not currently available

Deleted Variants

Deleted (deletedAt IS NOT NULL)
Soft-deleted variants are excluded from all queries

Barcode Linked

Barcode Association
Variants can be found by searching associated barcodes

Error Responses

All endpoints may return standard HTTP error codes:

401 Unauthorized - Missing or invalid authentication token
403 Forbidden - User does not have access to the store
500 Internal Server Error - Server error

Error Response Format

{
  "statusCode": 403,
  "message": "You do not have access to this store",
  "error": "Forbidden"
}

Common Error Scenarios

403 Forbidden - Store Access

{
  "statusCode": 403,
  "message": "You do not have access to this store"
}

Occurs when the user doesn’t have access to the specified store. 400 Bad Request - Invalid Pagination

{
  "statusCode": 400,
  "message": ["page must be a positive number", "limit must be between 1 and 100"],
  "error": "Bad Request"
}

Occurs when pagination parameters are invalid.

Usage Examples

Example 1: Get all item variants with default pagination

curl -X GET "https://joptic.jethings.com/item-variants" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>"

Example 2: Search by barcode

curl -X GET "https://joptic.jethings.com/item-variants?search=1234567890123" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>"

Example 3: Search by item variant name

curl -X GET "https://joptic.jethings.com/item-variants?search=PhGy&page=1&limit=20" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>"

Example 4: Get second page with custom limit

curl -X GET "https://joptic.jethings.com/item-variants?page=2&limit=50" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>"

Example 5: Search with pagination

curl -X GET "https://joptic.jethings.com/item-variants?search=1.67&page=1&limit=10" \
  -H "x-store-id: your-store-id" \
  -H "Authorization: Bearer <token>"

Best Practices

Search Optimization

Use specific search terms for better performance
Barcode searches are faster than name searches
Combine search with pagination for large result sets
Use appropriate limit values (10-50 for most cases)

Pagination

Use default pagination (page=1, limit=10) for most use cases
Increase limit (max 100) only when necessary
Always check hasNext and hasPrev for navigation
Implement proper error handling for invalid page numbers

Barcode Usage

Use barcode search for point-of-sale scenarios
Ensure barcodes are properly associated with item variants
Handle cases where barcode might not be found
Consider implementing barcode scanning in your application

Error Handling

Always check for 403 errors when accessing store data
Handle empty search results gracefully
Implement retry logic for 500 errors with exponential backoff
Validate pagination parameters before making requests

Performance

Cache frequently accessed item variants when possible
Use search filters to reduce result set size
Avoid fetching all variants without pagination
Consider implementing client-side filtering for small datasets

Data Consistency

Be aware that deleted variants are automatically excluded
Check isActive status for availability
Handle null values for name and description fields
Verify store access before displaying results to users

Item variants work in conjunction with other inventory management endpoints:

Item API (/items) - Create and manage items that contain variants
Item CRUD API (/items) - Update item variants and their properties
Stock Reconciliation API (/stock-reconciliation) - Reconcile inventory for specific item variants
Price List API (/price-lists) - Set prices for item variants

Item variants are automatically created when items are created. Use the Item API to create new items with variants, and use this endpoint to search and retrieve existing variants.

Summary

Endpoint	Method	Description
`/item-variants`	`GET`	Retrieve paginated list of item variants with optional search

Key Features

Search by Barcode: Find item variants by scanning or entering barcodes
Search by Name: Find item variants by name (case-insensitive)
Pagination: Efficient data retrieval with configurable page size
Store Filtering: Automatic filtering by authenticated user’s store
Soft Delete: Deleted variants are automatically excluded

Item API

Create and manage optical items

Item CRUD API

Update items and variants

Stock Reconciliation API

Reconcile inventory for item variants

Price List API

Manage prices for item variants

J-optic

​Item Variants API Documentation

​Endpoint Details

​Required Headers

​Authentication

​Get All Item Variants

​Query Parameters

​Search Functionality

​Success Response

​Response Fields

​Pagination Fields

​Example Request

​Example: Search by Barcode

​Example: Search by Name

​Example: Get All Variants (No Search)

​Possible Errors

​Business Logic

​Item Variant Retrieval Process

​Item Variant States

Active Variants

Inactive Variants

Deleted Variants

Barcode Linked

​Error Responses

​Error Response Format

​Common Error Scenarios

​Usage Examples

​Example 1: Get all item variants with default pagination

​Example 2: Search by barcode

​Example 3: Search by item variant name

​Example 4: Get second page with custom limit

​Example 5: Search with pagination

​Best Practices

​Related Endpoints

​Summary

​Key Features

Item API

Item CRUD API

Stock Reconciliation API

Price List API

Item Variants API Documentation

Endpoint Details

Required Headers

Authentication

Get All Item Variants

Query Parameters

Search Functionality

Success Response

Response Fields

Pagination Fields

Example Request

Example: Search by Barcode

Example: Search by Name

Example: Get All Variants (No Search)

Possible Errors

Business Logic

Item Variant Retrieval Process

Item Variant States

Error Responses

Error Response Format

Common Error Scenarios

Usage Examples

Example 1: Get all item variants with default pagination

Example 2: Search by barcode

Example 3: Search by item variant name

Example 4: Get second page with custom limit

Example 5: Search with pagination

Best Practices

Related Endpoints

Summary

Key Features