{ "openapi": "3.1.0", "info": { "title": "Colombo Cosmetics Public Catalog & Commerce API", "version": "1.0.0", "summary": "Machine-readable REST API for Colombo Cosmetics beauty retail catalog, product search, categories, brands, bundle deals, store policies, and order tracking in Sri Lanka (LKR).", "description": "Colombo Cosmetics (https://colombocosmetics.lk) is Sri Lanka's premier beauty retail store for 100% authentic makeup, skincare, haircare, designer perfumes, and concentrated attars. This public read-only API allows AI agents, shopping assistants, and developer integrations to search products, inspect live stock and LKR pricing, browse categories and bundle offers, verify shipping and return policies, and look up customer order status without requiring an API key.", "contact": { "name": "Colombo Cosmetics Developer & Customer Support", "url": "https://colombocosmetics.lk/contact", "email": "colombocosmetics.lk@gmail.com" }, "license": { "name": "Proprietary — Public Catalog Read Access", "url": "https://colombocosmetics.lk/terms" } }, "servers": [ { "url": "https://colombocosmetics.lk", "description": "Production Server (Sri Lanka)" } ], "tags": [ { "name": "Catalog", "description": "Search and retrieve authentic beauty products, variants, and LKR pricing." }, { "name": "Taxonomy", "description": "Browse hierarchical beauty categories, subcategories, and brands." }, { "name": "Bundles", "description": "Retrieve curated value bundles with automatic free island-wide delivery." }, { "name": "Store & Orders", "description": "Store shipping/return policies, contact details, and customer order tracking." }, { "name": "Feeds", "description": "XML sitemaps and Google Merchant Center product feeds." } ], "paths": { "/api/public/products": { "get": { "operationId": "listProducts", "summary": "Search and filter beauty products", "description": "Returns a paginated list of active beauty, makeup, skincare, haircare, and fragrance products from Colombo Cosmetics. Supports full-text keyword search (`q`), category/subcategory filtering, brand filtering, LKR price range bounds, stock availability filtering, minimum customer rating, and sorting. Rate limit: 60 requests per minute per IP.", "tags": [ "Catalog" ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search query keyword matched against product name, brand, category, and description (e.g. 'vitamin c serum', 'lattafa', 'lipstick').", "schema": { "type": "string", "minLength": 1, "maxLength": 120 } }, { "name": "category", "in": "query", "required": false, "description": "Filter by top-level category slug or name (e.g. 'skincare', 'fragrance', 'makeup').", "schema": { "type": "string" } }, { "name": "subcategory", "in": "query", "required": false, "description": "Filter by subcategory slug or name (e.g. 'serums', 'lipsticks', 'attars').", "schema": { "type": "string" } }, { "name": "brand", "in": "query", "required": false, "description": "Filter by exact brand name (case-insensitive, e.g. 'The Ordinary', 'Chemist at Play').", "schema": { "type": "string" } }, { "name": "minPrice", "in": "query", "required": false, "description": "Minimum product price in Sri Lankan Rupees (LKR).", "schema": { "type": "number", "minimum": 0 } }, { "name": "maxPrice", "in": "query", "required": false, "description": "Maximum product price in Sri Lankan Rupees (LKR).", "schema": { "type": "number", "minimum": 0 } }, { "name": "inStock", "in": "query", "required": false, "description": "When true, returns only products currently in stock (stock > 0).", "schema": { "type": "boolean" } }, { "name": "minRating", "in": "query", "required": false, "description": "Minimum average customer review rating between 1 and 5.", "schema": { "type": "number", "minimum": 1, "maximum": 5 } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order for matching products.", "schema": { "type": "string", "enum": [ "featured", "price_asc", "price_desc", "rating", "newest" ], "default": "featured" } }, { "name": "page", "in": "query", "required": false, "description": "1-indexed page number for pagination.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "Number of products per page (1 to 48).", "schema": { "type": "integer", "minimum": 1, "maximum": 48, "default": 16 } } ], "responses": { "200": { "description": "Paginated list of matching products in LKR.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" } } } }, "400": { "description": "Invalid query parameter provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Unexpected catalog server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/public/products/{slug}": { "get": { "operationId": "getProductBySlug", "summary": "Get detailed product information by slug", "description": "Retrieves complete details for a single active product by its URL slug, including full description, LKR price, compare-at price, live stock count, product variants (shades/sizes), image gallery, customer rating summary, and Sri Lanka shipping calculation.", "tags": [ "Catalog" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "URL slug of the product (e.g. 'chemist-at-play-underarm-roll-on').", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Detailed product record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDetailResponse" } } } }, "404": { "description": "Product not found or inactive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "500": { "description": "Server error while retrieving product.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/public/categories": { "get": { "operationId": "listCategories", "summary": "List product categories and subcategories", "description": "Returns the hierarchical category tree (top-level categories and nested subcategories) with active product counts and direct shop filter URLs.", "tags": [ "Taxonomy" ], "responses": { "200": { "description": "Category tree with product counts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryListResponse" } } } }, "500": { "description": "Server error while retrieving categories.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/public/brands": { "get": { "operationId": "listBrands", "summary": "List all available cosmetic and perfume brands", "description": "Returns all active cosmetic, skincare, haircare, and fragrance brands stocked by Colombo Cosmetics along with active product counts and brand filter URLs.", "tags": [ "Taxonomy" ], "responses": { "200": { "description": "List of brands and product counts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandListResponse" } } } }, "500": { "description": "Server error while retrieving brands.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/public/bundles": { "get": { "operationId": "listBundles", "summary": "List curated value bundle offers", "description": "Returns all active multi-product beauty and fragrance value bundles, including bundle price in LKR, compare-at price, stock availability, and constituent items. Bundles ordered alone qualify for free standard delivery island-wide.", "tags": [ "Bundles" ], "responses": { "200": { "description": "List of active product bundles.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleListResponse" } } } }, "500": { "description": "Server error while retrieving bundles.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/public/store-info": { "get": { "operationId": "getStoreInfo", "summary": "Get store identity, shipping rates, payment methods, and return policy", "description": "Returns structured metadata about Colombo Cosmetics, including physical address in Kattankudy (Batticaloa, Sri Lanka), customer support channels (WhatsApp, phone, email), island-wide shipping fees (Rs. 300 standard, free over Rs. 10,000, Rs. 100 COD handling fee), accepted payment methods, and the 7-day merchant-fault return policy.", "tags": [ "Store & Orders" ], "responses": { "200": { "description": "Structured store metadata and policy rules.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreInfoResponse" } } } }, "500": { "description": "Server error while retrieving store info.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/public/track-order": { "get": { "operationId": "trackOrderStatus", "summary": "Look up customer order status by order number and phone", "description": "Checks the live fulfillment status of a Colombo Cosmetics order using the numeric `order_number` and the customer `phone` number used at checkout. Rate limit: 10 requests per 15 minutes per IP.", "tags": [ "Store & Orders" ], "parameters": [ { "name": "order_number", "in": "query", "required": true, "description": "Numeric order number received at checkout (e.g. 1042).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "phone", "in": "query", "required": true, "description": "Customer phone number used when placing the order (e.g. '0771234567').", "schema": { "type": "string", "minLength": 9, "maxLength": 15 } } ], "responses": { "200": { "description": "Matching order status details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackOrderResponse" } } } }, "400": { "description": "Missing or invalid order_number or phone parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "description": "No order matched the provided order_number and phone.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "429": { "description": "Rate limit exceeded for order tracking lookups.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }, "/api/public/sitemap": { "get": { "operationId": "getSitemapXml", "summary": "Get dynamic XML sitemap of all active store pages and products", "description": "Returns the live XML sitemap containing all static store pages, category filter URLs, active product URLs, and bundle offer URLs.", "tags": [ "Feeds" ], "responses": { "200": { "description": "XML Sitemap document.", "content": { "application/xml": { "schema": { "type": "string" } } } } } } }, "/api/public/google-merchant-feed": { "get": { "operationId": "getGoogleMerchantFeedXml", "summary": "Get Google Merchant Center RSS 2.0 XML product feed", "description": "Returns the live Google Merchant Center RSS 2.0 XML feed containing all active products with LKR prices, availability, images, brands, and Sri Lanka shipping attributes.", "tags": [ "Feeds" ], "responses": { "200": { "description": "Google Merchant RSS 2.0 XML document.", "content": { "application/xml": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "ApiErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "status", "resolution", "docs_url" ], "properties": { "code": { "type": "string", "description": "Machine-readable uppercase error code (e.g. INVALID_PARAMETER, PRODUCT_NOT_FOUND)." }, "message": { "type": "string", "description": "Human-readable explanation of what went wrong." }, "status": { "type": "integer", "description": "HTTP status code mirrored in the payload." }, "resolution": { "type": "string", "description": "Actionable remediation hint for agents and developers." }, "docs_url": { "type": "string", "format": "uri", "description": "Link to the API documentation page." }, "details": { "type": "object", "additionalProperties": true, "description": "Optional structured context about the error." } } } } }, "ProductSummary": { "type": "object", "required": [ "id", "name", "slug", "url", "category", "price_lkr", "currency", "in_stock", "stock", "is_featured", "image_url" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "category": { "type": "string" }, "brand": { "type": [ "string", "null" ] }, "price_lkr": { "type": "number", "description": "Selling price in Sri Lankan Rupees (LKR)." }, "compare_at_price_lkr": { "type": [ "number", "null" ], "description": "Original price in LKR prior to discount, if discounted." }, "currency": { "type": "string", "enum": [ "LKR" ] }, "in_stock": { "type": "boolean" }, "stock": { "type": "integer", "minimum": 0 }, "is_featured": { "type": "boolean" }, "avg_rating": { "type": [ "number", "null" ] }, "review_count": { "type": "integer", "minimum": 0 }, "variant_count": { "type": "integer", "minimum": 0 }, "image_url": { "type": "string", "format": "uri" } } }, "ProductListResponse": { "type": "object", "required": [ "products", "pagination", "currency" ], "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSummary" } }, "pagination": { "type": "object", "required": [ "total", "page", "pageSize", "totalPages" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1 }, "totalPages": { "type": "integer", "minimum": 1 } } }, "currency": { "type": "string", "enum": [ "LKR" ] } } }, "ProductVariant": { "type": "object", "required": [ "id", "name", "price_lkr", "stock", "in_stock" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "price_lkr": { "type": "number" }, "compare_at_price_lkr": { "type": [ "number", "null" ] }, "stock": { "type": "integer", "minimum": 0 }, "in_stock": { "type": "boolean" }, "image_url": { "type": [ "string", "null" ] } } }, "ProductDetailResponse": { "type": "object", "required": [ "product" ], "properties": { "product": { "type": "object", "required": [ "id", "name", "slug", "url", "description", "category", "price_lkr", "currency", "in_stock", "stock", "variants", "shipping" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "category": { "type": "string" }, "brand": { "type": [ "string", "null" ] }, "price_lkr": { "type": "number" }, "compare_at_price_lkr": { "type": [ "number", "null" ] }, "currency": { "type": "string", "enum": [ "LKR" ] }, "in_stock": { "type": "boolean" }, "stock": { "type": "integer", "minimum": 0 }, "is_featured": { "type": "boolean" }, "avg_rating": { "type": [ "number", "null" ] }, "review_count": { "type": "integer", "minimum": 0 }, "image_url": { "type": "string", "format": "uri" }, "images": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "image_url": { "type": "string", "format": "uri" }, "sort_order": { "type": "integer" } } } }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/ProductVariant" } }, "shipping": { "type": "object", "properties": { "standard_delivery_fee_lkr": { "type": "number" }, "free_delivery_threshold_lkr": { "type": "number" }, "cod_handling_fee_lkr": { "type": "number" }, "estimated_delivery_days": { "type": "string" } } } } } } }, "CategoryNode": { "type": "object", "required": [ "id", "name", "slug", "url", "product_count", "subcategories" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "product_count": { "type": "integer", "minimum": 0 }, "subcategories": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "slug", "url", "product_count" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "product_count": { "type": "integer", "minimum": 0 } } } } } }, "CategoryListResponse": { "type": "object", "required": [ "categories", "total" ], "properties": { "categories": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryNode" } }, "total": { "type": "integer", "minimum": 0 } } }, "BrandListResponse": { "type": "object", "required": [ "brands", "total" ], "properties": { "brands": { "type": "array", "items": { "type": "object", "required": [ "name", "product_count", "url" ], "properties": { "name": { "type": "string" }, "product_count": { "type": "integer", "minimum": 0 }, "url": { "type": "string", "format": "uri" } } } }, "total": { "type": "integer", "minimum": 0 } } }, "BundleListResponse": { "type": "object", "required": [ "bundles", "total", "currency" ], "properties": { "bundles": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "slug", "url", "price_lkr", "currency", "in_stock", "stock", "items" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "price_lkr": { "type": "number" }, "compare_at_price_lkr": { "type": [ "number", "null" ] }, "currency": { "type": "string", "enum": [ "LKR" ] }, "in_stock": { "type": "boolean" }, "stock": { "type": "integer", "minimum": 0 }, "is_featured": { "type": "boolean" }, "free_delivery_alone": { "type": "boolean" }, "image_url": { "type": "string", "format": "uri" }, "items": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" }, "variant_id": { "type": [ "string", "null" ] }, "product_name": { "type": "string" }, "variant_name": { "type": [ "string", "null" ] }, "quantity": { "type": "integer", "minimum": 1 } } } } } } }, "total": { "type": "integer", "minimum": 0 }, "currency": { "type": "string", "enum": [ "LKR" ] } } }, "StoreInfoResponse": { "type": "object", "required": [ "store" ], "properties": { "store": { "type": "object", "required": [ "name", "url", "country", "currency", "address", "contact", "shipping_policy", "payment_methods", "return_policy", "resources" ], "properties": { "name": { "type": "string" }, "legal_name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "country": { "type": "string" }, "currency": { "type": "string" }, "founded_year": { "type": "integer" }, "description": { "type": "string" }, "address": { "type": "object", "additionalProperties": true }, "contact": { "type": "object", "additionalProperties": true }, "shipping_policy": { "type": "object", "additionalProperties": true }, "payment_methods": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "return_policy": { "type": "object", "additionalProperties": true }, "resources": { "type": "object", "additionalProperties": true } } } } }, "TrackOrderResponse": { "type": "object", "required": [ "order" ], "properties": { "order": { "type": "object", "required": [ "order_number", "status", "total_lkr", "currency", "payment_method", "created_at", "tracking_url" ], "properties": { "order_number": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "payment_pending", "payment_processing", "confirmed", "shipped", "delivered", "cancelled", "refunded", "partially_refunded", "processing_failed" ] }, "total_lkr": { "type": "number" }, "currency": { "type": "string", "enum": [ "LKR" ] }, "payment_method": { "type": "string", "enum": [ "cod", "card" ] }, "created_at": { "type": "string", "format": "date-time" }, "tracking_url": { "type": "string", "format": "uri" } } } } } } } }