Get Product

This endpoint retrieves the details of a specific product or lists multiple products with filtering, sorting, and pagination options.

🔒 Authentication

Header	Required	Description
Content-Type	Yes	Must be application/json
Authorization	Yes	Format: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature

🔍 Available Endpoints

1. Get Single Product

GET /api/v1/products/{productId}

Path Parameters

Parameter	Type	Required	Description
productId	string	Yes	The unique identifier of the product

2. List Products

GET /api/v1/products

Query Parameters

Parameter	Type	Description	Default
page	number	Page number for pagination	1
limit	number	Items per page (max 100)	20
category	string	Filter by category	-
active	boolean	Filter by active status	-
query	string	Search in name/description	-
sort	string	Sort field (name,created,updated)	created
order	string	Sort order (asc,desc)	desc
tags	string[]	Filter by tags	-

📝 Usage Examples

Get Single Product

curl -X GET "https://openapi.onlive.site/api/v1/products/123e4567-e89b-12d3-a456-426614174000" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

List Active Products in Category

curl -X GET "https://openapi.onlive.site/api/v1/products?category=Apparel&active=true&limit=50" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

Search Products

curl -X GET "https://openapi.onlive.site/api/v1/products?query=premium&sort=name&order=asc" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

📤 Response Format

Single Product Response

{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Premium T-Shirt",
    "active": true,
    "category": "Apparel",
    "currency": "EUR",
    "descriptionHtml": "<p>High-quality cotton t-shirt</p>",
    "externalId": "SHIRT-001",
    "images": [
        "https://example.com/shirt-front.webp",
        "https://example.com/shirt-back.webp"
    ],
    "options": [
        {
            "name": "Size",
            "values": ["Small", "Medium", "Large"]
        },
        {
            "name": "Color",
            "values": ["Black", "White"]
        }
    ],
    "variants": [
        {
            "id": "789e0123-c45b-67d8-e901-234567890000",
            "sku": "TS-BLK-S",
            "price": 29.99,
            "currency": "EUR",
            "stock": 50,
            "selectedOptions": [
                {
                    "name": "Size",
                    "value": "Small"
                },
                {
                    "name": "Color",
                    "value": "Black"
                }
            ],
            "images": [
                "https://example.com/shirt-black-small.webp"
            ]
        }
    ],
    "price": 29.99,
    "stock": 50,
    "tags": ["premium", "apparel"],
    "providerType": "onlive",
    "createdAt": "2025-05-22T10:00:00Z",
    "updatedAt": "2025-05-22T10:00:00Z"
}

Product List Response

{
    "items": [
        {
            // Product object as above
        }
    ],
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
}

📘 Response Interpretation

Product Fields

• id: Unique product identifier
• name, category: Basic product info
• active: Product visibility status
• price: Lowest variant price
• stock: Total available stock
• options: Available customization options
• variants: Individual product variations
• createdAt, updatedAt: Timestamps

Pagination Fields

• page: Current page number
• limit: Items per page
• total: Total items available
• pages: Total number of pages

🔍 Filtering Options

1. Basic Filters

   • Category-based filtering
   • Active status filtering
   • Tag-based filtering

2. Search Options

   • Name search
   • Description search
   • SKU search

3. Advanced Filters

   • Price range
   • Stock availability
   • Creation date

❌ Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid query parameter",
  "errors": [
    {
      "field": "limit",
      "message": "Must be a number between 1 and 100"
    }
  ]
}

401 Unauthorized

{
  "statusCode": 401,
  "message": "Invalid or missing authorization credentials"
}

403 Forbidden

{
  "statusCode": 403,
  "message": "Insufficient permissions to access this product"
}

404 Not Found

{
  "statusCode": 404,
  "message": "Product not found"
}

429 Too Many Requests

{
  "statusCode": 429,
  "message": "Rate limit exceeded",
  "retryAfter": 60
}

💡 Best Practices

1. Performance

   • Use pagination for large lists
   • Cache frequently accessed products
   • Limit requested fields when possible
   • Implement rate limiting

2. Data Handling

   • Handle empty results gracefully
   • Parse timestamps correctly
   • Cache responses when appropriate
   • Handle currency formatting

3. Error Handling

   • Implement proper error handling
   • Retry on network errors
   • Handle rate limiting
   • Log failed requests

🔗 Related Endpoints

• Create Product: Create new products
• Update Product: Modify existing products
• Delete Product: Remove products

📘 Notes

• Results are paginated by default
• Maximum 100 items per page
• Timestamps are in ISO 8601 format
• Prices include VAT where applicable
• Stock levels are real-time
• Images are WebP format
• Currency follows ISO 4217