FavoriteLists API
Introduction
The Favorite Lists Service is a comprehensive microservice for managing personalized product collections. It enables users to create, organize, and maintain curated lists of products and product clusters with flexible ownership models and powerful search capabilities.
Key Features
- ** Multi-Entity Support**: Lists can belong to companies, contacts, or customers
- ** Flexible Content**: Support for both individual products and product clusters
- ** Advanced Search**: Comprehensive filtering by ownership, content, dates, and metadata
- ** Dual API**: Both REST and GraphQL endpoints for maximum integration flexibility
- ** Smart Organization**: Automatic slug generation and default list support
- ** Secure Access**: OAuth2 authentication with proper authorization controls
- ** Real-time Updates**: Event-driven architecture for data consistency
- ** Pagination**: Built-in pagination support for large datasets
Use Cases
- B2B Commerce: Company-specific product catalogs and procurement lists
- Customer Management: Personal shopping lists and product recommendations
- Sales Tools: Curated product collections for sales representatives
- Inventory Management: Organized product groupings for easier management
- Cross-Platform Integration: Support for external system references via source identifiers
API Overview
This REST API provides complete CRUD operations for favorite lists with the following endpoints:
- GET
/v2/favoritelists/{id}- Retrieve a specific favorite list by ID - POST
/v2/favoritelists- Create a new favorite list - PATCH
/v2/favoritelists/{id}- Update an existing favorite list - DELETE
/v2/favoritelists/{id}- Delete a favorite list permanently - GET
/v2/favoritelists- [DEPRECATED] List favorite lists with basic filtering - POST
/v2/favoritelists/search- Advanced search with comprehensive filtering - PATCH
/v2/favoritelists/{id}/add-items- Add products/clusters to a list - PATCH
/v2/favoritelists/{id}/remove-items- Remove products/clusters from a list - PATCH
/v2/favoritelists/{id}/clear-items- Clear all or specific item types
Authentication
All endpoints require OAuth2 authentication using the client credentials flow. Include the access token in the Authorization header:
Authorization: Bearer <your-access-token>
Data Format
All requests and responses use JSON format. Dates are in ISO 8601 format (UTC).
Error Handling
The API returns standard HTTP status codes and structured error responses:
- 200: Success
- 201: Created successfully
- 400: Bad request (validation errors)
- 401: Unauthorized (invalid/missing token)
- 403: Forbidden (insufficient permissions)
- 404: Not found
- 500: Internal server error
Favorite List Structure
| Field | Type | Description | Validation | Example |
|---|---|---|---|---|
id | string | Unique identifier (ObjectId format) | Required, 24-char hex | 67d2a7d52dfe2a405d3bd5b9 |
name | string | Descriptive name | Required, max 64 chars | Monthly Office Supplies |
companyId | number | Company owner ID (mutually exclusive) | Optional, positive integer | 1482 |
contactId | number | Contact owner ID (mutually exclusive) | Optional, positive integer | 15083 |
customerId | number | Customer owner ID (mutually exclusive) | Optional, positive integer | 14383 |
productIds | number[] | Array of product identifiers | Optional, unique integers | [71516, 114258, 69237] |
clusterIds | number[] | Array of cluster identifiers | Optional, unique integers | [2920, 764, 1437] |
isDefault | boolean | Default list flag | Optional, default false | true |
slug | string | URL-friendly identifier | Auto-generated | monthly-office-supplies |
createdAt | string | Creation timestamp (ISO 8601) | Auto-generated | 2025-01-15T10:30:00.000Z |
updatedAt | string | Last update timestamp (ISO 8601) | Auto-updated | 2025-01-15T14:45:00.000Z |
Authentication
- OAuth 2.0: OAuth2
OAuth2 Authorization
Security Scheme Type: | oauth2 |
|---|---|
OAuth Flow (clientCredentials): | Token URL: https://api.helice.cloud/oauth2/token/ Scopes: |