{ "openapi": "3.0.3", "info": { "title": "Garden Flowers API & Agent Commerce Protocol", "version": "1.0.0", "description": "API for searching signature bouquets, scheduling flower delivery in Dubai, and processing instant order checkouts." }, "servers": [ { "url": "https://gardenflowers.ae/api/v1", "description": "Production API Server" } ], "x-service-info": { "category": "floristry_and_e-commerce", "provider": "Garden Flowers Dubai" }, "components": { "schemas": { "Variant": { "type": "object", "description": "A price/size variant of a product (e.g. Standard, Medium, Large).", "properties": { "id": { "type": "integer", "description": "Unique variant ID", "example": 101 }, "price": { "type": "number", "description": "Price in AED", "example": 450 }, "is_default": { "type": "boolean", "description": "Whether this is the default variant", "example": true }, "name": { "type": "string", "nullable": true, "description": "Variant label", "example": "Standard" }, "size": { "type": "string", "nullable": true, "description": "Size description", "example": "Medium" } }, "required": [ "id", "price", "is_default" ] }, "Category": { "type": "object", "description": "Product category.", "properties": { "id": { "type": "integer", "description": "Category ID", "example": 1 }, "name": { "type": "string", "description": "Category display name", "example": "Bouquets" }, "slug": { "type": "string", "description": "URL-friendly slug", "example": "bouquets" } }, "required": [ "id", "name", "slug" ] }, "Product": { "type": "object", "description": "A flower bouquet or arrangement available for order.", "properties": { "id": { "type": "integer", "description": "Product ID", "example": 42 }, "slug": { "type": "string", "description": "URL-friendly identifier", "example": "santorini" }, "name": { "type": "string", "description": "Product title", "example": "SANTORINI" }, "image_url": { "type": "string", "description": "Primary product image URL" }, "images": { "type": "array", "description": "Gallery images", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Image URL" }, "alt": { "type": "string", "nullable": true, "description": "Alt text for SEO/accessibility" } } } }, "category": { "$ref": "#/components/schemas/Category" }, "variants": { "type": "array", "description": "Price/size variants (first is default)", "items": { "$ref": "#/components/schemas/Variant" } }, "is_active": { "type": "boolean", "description": "Whether the product is in stock", "example": true }, "colors": { "type": "array", "description": "Color palette", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } }, "flowers": { "type": "array", "description": "Flower types used in arrangement", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } }, "required": [ "id", "slug", "name", "image_url", "category", "variants" ] }, "ProductDetail": { "type": "object", "description": "Full product details for the product detail page.", "properties": { "id": { "type": "integer", "example": 42 }, "slug": { "type": "string", "example": "santorini" }, "name": { "type": "string", "example": "SANTORINI" }, "type": { "type": "string", "nullable": true, "description": "Product type classification" }, "description": { "type": "string", "nullable": true, "description": "Rich product description (HTML or plain text)" }, "image_url": { "type": "string", "nullable": true }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "alt": { "type": "string" } } } }, "meta_title": { "type": "string", "nullable": true }, "meta_description": { "type": "string", "nullable": true }, "h1": { "type": "string", "nullable": true }, "seo_text": { "type": "string", "nullable": true }, "canonical_url": { "type": "string", "nullable": true, "format": "uri" }, "robots_meta": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "category": { "$ref": "#/components/schemas/Category" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Variant" } }, "colors": { "type": "array", "items": { "type": "string" }, "description": "Color names" }, "flowers": { "type": "array", "items": { "type": "string" }, "description": "Flower names" } } }, "CartResponse": { "type": "object", "description": "Current state of the user's shopping cart.", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Cart item ID" }, "product": { "$ref": "#/components/schemas/Product" }, "quantity": { "type": "integer", "example": 1 }, "price": { "type": "number", "example": 450 } } } }, "total": { "type": "number", "description": "Cart total in AED", "example": 1350 } } }, "CheckoutRequest": { "type": "object", "description": "Request body for creating an order.", "properties": { "customer_name": { "type": "string", "description": "Full name of the person placing the order", "example": "Anna Smith" }, "customer_phone": { "type": "string", "pattern": "^\\+\\d{7,15}$", "description": "Phone in international format (+971...)", "example": "+971501234567" }, "customer_email": { "type": "string", "format": "email", "description": "Email for order confirmation and receipts", "example": "anna@example.com" }, "preferred_contact": { "type": "string", "enum": [ "whatsapp", "telegram", "phone" ], "description": "Preferred communication channel for sales team", "example": "whatsapp" }, "telegram_username": { "type": "string", "nullable": true, "description": "Telegram @username (required if preferred_contact is telegram)", "example": "@annasmith" }, "recipient_name": { "type": "string", "description": "Full name of the person receiving the flowers", "example": "Maria" }, "recipient_phone": { "type": "string", "pattern": "^\\+\\d{7,15}$", "description": "Phone number of recipient for courier coordination", "example": "+971509876543" }, "delivery_address": { "type": "string", "description": "Full delivery address in Dubai/UAE (building, street, apartment/villa)", "example": "Downtown Dubai, Boulevard Point, Apt 1402" }, "delivery_city": { "type": "string", "nullable": true, "default": "Dubai", "description": "City in UAE", "example": "Dubai" }, "delivery_date": { "type": "string", "format": "date", "description": "Delivery date (YYYY-MM-DD), today or future", "example": "2026-08-20" }, "delivery_time": { "type": "string", "nullable": true, "description": "Preferred delivery time window", "example": "14:00 - 17:00" }, "delivery_type": { "type": "string", "nullable": true, "description": "Delivery method (e.g. courier_to_address)", "example": "courier_to_address" }, "courier_comments": { "type": "string", "nullable": true, "description": "Special instructions for courier (door code, reception, etc.)", "example": "Leave with concierge" }, "postcard_text": { "type": "string", "nullable": true, "description": "Personalized greeting card message included with bouquet", "example": "Happy Birthday!" }, "special_requests": { "type": "string", "nullable": true, "description": "Florist preparation notes or custom requests", "example": "Extra white ribbon" }, "discovery_source": { "type": "string", "enum": [ "recommendation", "influencer", "instagram_ad", "instagram", "google_maps", "other" ], "default": "other", "description": "How the customer found Garden Flowers", "example": "other" }, "discovery_other": { "type": "string", "nullable": true, "description": "Additional source details if discovery_source is other", "example": "AI Agent" }, "promocode": { "type": "string", "nullable": true, "description": "Discount promo code if available" }, "payment_method": { "type": "string", "nullable": true, "description": "Payment method (e.g. card_online, crypto_usdt)", "example": "card_online" }, "agreement": { "type": "boolean", "description": "Acceptance of terms of service (must be true)", "example": true } }, "required": [ "customer_name", "customer_phone", "customer_email", "preferred_contact", "recipient_name", "recipient_phone", "delivery_address", "delivery_date", "discovery_source", "agreement" ] }, "CheckoutResponse": { "type": "object", "description": "Successful order creation response.", "properties": { "payment_url": { "type": "string", "format": "uri", "description": "Redirect URL for payment" }, "order_id": { "type": "integer" }, "status": { "type": "string", "example": "pending" } } }, "PaginatedProducts": { "type": "object", "description": "Paginated list of products.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "total": { "type": "integer" } } }, "filters": { "type": "array", "items": { "type": "object" } }, "category": { "$ref": "#/components/schemas/Category" } } }, "CategoryList": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "is_visible": { "type": "boolean" }, "label_text": { "type": "string", "nullable": true } } } } } } } }, "paths": { "/catalog": { "get": { "summary": "Search and list flower catalog", "operationId": "searchCatalog", "tags": [ "Catalog" ], "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Category slug (bouquets, mono-bouquets, baskets, vases, boxes)", "example": "bouquets" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Free-text search across name and description", "example": "red roses" }, { "name": "max_price", "in": "query", "schema": { "type": "number" }, "description": "Maximum price filter in AED", "example": 500 }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "popularity", "price_asc", "price_desc" ] }, "description": "Sort order" }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Paginated list of products matching the query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedProducts" } } } } } } }, "/products/{slug}": { "get": { "summary": "Get full product detail by slug", "operationId": "getProduct", "tags": [ "Catalog" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Product slug", "example": "santorini" } ], "responses": { "200": { "description": "Full product details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProductDetail" } } } } } }, "404": { "description": "Product not found" } } } }, "/categories": { "get": { "summary": "List all product categories", "operationId": "listCategories", "tags": [ "Catalog" ], "responses": { "200": { "description": "List of visible product categories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryList" } } } } } } }, "/cart/items": { "post": { "summary": "Add item to cart", "operationId": "addToCart", "tags": [ "Cart" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variant_id": { "type": "integer", "description": "Variant ID from product.variants", "example": 101 }, "quantity": { "type": "integer", "default": 1, "description": "Quantity to add", "example": 1 } }, "required": [ "variant_id" ] } } } }, "responses": { "200": { "description": "Updated cart contents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } } } } }, "/checkout": { "post": { "summary": "Create flower order checkout session", "operationId": "createCheckout", "tags": [ "Orders" ], "x-payment-info": { "intent": "charge", "method": "stripe", "amount": "350.00", "currency": "AED", "description": "Payment for luxury flower bouquet delivery in Dubai" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutRequest" } } } }, "responses": { "200": { "description": "Checkout session initialized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutResponse" } } } }, "402": { "description": "Payment Required via x402 / MPP" } } } } } }