{
  "openapi": "3.1.0",
  "info": {
    "title": "Luxe Glow Beauty Store API",
    "description": "AI-enabled beauty e-commerce API with WebMCP support for agentic commerce. All mutating endpoints (POST/PUT/DELETE) support the Idempotency-Key header to prevent duplicate operations. Include a unique UUID per request to ensure idempotency.",
    "version": "1.0.0",
    "contact": {
      "name": "Luxe Glow Support",
      "email": "support@luxeglow.demo"
    }
  },
  "servers": [
    {
      "url": "https://demo.aido-labs.co",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/": {
      "get": {
        "operationId": "getProductCatalog",
        "summary": "Get full product catalog",
        "description": "Returns all brands and products with pricing and availability",
        "responses": {
          "200": {
            "description": "Product catalog",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Catalog"
                }
              }
            }
          }
        }
      }
    },
    "/api/products/{productId}": {
      "get": {
        "operationId": "getProduct",
        "summary": "Get product details",
        "parameters": [
          {
            "name": "productId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Product details",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Product" }
              }
            }
          }
        }
      }
    },
    "/api/cart": {
      "get": {
        "operationId": "getCart",
        "summary": "Get current cart",
        "responses": {
          "200": {
            "description": "Cart contents",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Cart" }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "addToCart",
        "summary": "Add item to cart",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "productId": { "type": "string" },
                  "quantity": { "type": "integer", "default": 1 }
                },
                "required": ["productId"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated cart"
          }
        }
      }
    },
    "/api/checkout": {
      "post": {
        "operationId": "createCheckoutSession",
        "summary": "Create checkout session",
        "description": "Creates a Stripe checkout session for payment processing",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": { "type": "string", "format": "email" },
                  "shipping": { "$ref": "#/components/schemas/ShippingAddress" },
                  "payment_method": {
                    "type": "string",
                    "enum": ["card", "apple_pay", "google_pay", "klarna"]
                  }
                },
                "required": ["email", "shipping"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout session created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sessionId": { "type": "string" },
                    "redirectUrl": { "type": "string", "format": "uri" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/orders/{orderId}": {
      "get": {
        "operationId": "getOrder",
        "summary": "Get order details",
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Order details with tracking",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Order" }
              }
            }
          }
        }
      }
    },
    "/api/orders/{orderId}/cancel": {
      "post": {
        "operationId": "cancelOrder",
        "summary": "Cancel an order",
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Order cancelled"
          }
        }
      }
    },
    "/api/returns": {
      "post": {
        "operationId": "initiateReturn",
        "summary": "Initiate a return",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "orderId": { "type": "string" },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "productId": { "type": "string" },
                        "reason": { "type": "string" }
                      }
                    }
                  }
                },
                "required": ["orderId", "items"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Return initiated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "returnId": { "type": "string" },
                    "returnLabel": { "type": "string", "format": "uri" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/support": {
      "post": {
        "operationId": "createTicket",
        "summary": "Create support ticket",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": { "type": "string", "format": "email" },
                  "subject": { "type": "string" },
                  "message": { "type": "string" },
                  "orderId": { "type": "string" }
                },
                "required": ["email", "subject", "message"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ticket created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ticketId": { "type": "string" },
                    "status": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/webhooks": {
      "post": {
        "operationId": "webhook",
        "summary": "Receive webhooks",
        "description": "Endpoint for order and shipment webhook notifications",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "event": {
                    "type": "string",
                    "enum": ["order.created", "order.shipped", "order.delivered", "return.initiated"]
                  },
                  "data": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook received"
          }
        }
      }
    },
    "/api/inventory/{productId}": {
      "get": {
        "operationId": "checkInventory",
        "summary": "Check product inventory",
        "parameters": [
          {
            "name": "productId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Inventory status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "productId": { "type": "string" },
                    "inStock": { "type": "boolean" },
                    "quantity": { "type": "integer" },
                    "availability": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/tracking/{orderId}": {
      "get": {
        "operationId": "getTracking",
        "summary": "Get shipment tracking",
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Tracking information",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Tracking" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Catalog": {
        "type": "object",
        "properties": {
          "store": { "type": "string" },
          "currency": { "type": "string" },
          "brands": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Brand" }
          }
        }
      },
      "Brand": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "category": { "type": "string" },
          "products": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Product" }
          }
        }
      },
      "Product": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "price": { "type": "number" },
          "currency": { "type": "string", "default": "EUR" },
          "category": { "type": "string" },
          "inStock": { "type": "boolean" }
        }
      },
      "Cart": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "productId": { "type": "string" },
                "quantity": { "type": "integer" },
                "price": { "type": "number" }
              }
            }
          },
          "subtotal": { "type": "number" },
          "shipping": { "type": "number" },
          "total": { "type": "number" }
        }
      },
      "ShippingAddress": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "address": { "type": "string" },
          "city": { "type": "string" },
          "postcode": { "type": "string" },
          "country": { "type": "string" }
        },
        "required": ["name", "address", "city", "postcode", "country"]
      },
      "Order": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "status": {
            "type": "string",
            "enum": ["pending", "confirmed", "shipped", "delivered", "cancelled"]
          },
          "items": { "type": "array" },
          "total": { "type": "number" },
          "tracking": { "$ref": "#/components/schemas/Tracking" }
        }
      },
      "Tracking": {
        "type": "object",
        "properties": {
          "carrier": { "type": "string" },
          "trackingNumber": { "type": "string" },
          "status": { "type": "string" },
          "estimatedDelivery": { "type": "string", "format": "date" },
          "events": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "timestamp": { "type": "string", "format": "date-time" },
                "location": { "type": "string" },
                "status": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}