{
  "openapi": "3.1.0",
  "info": {
    "title": "Boutique Rugs Storefront API",
    "summary": "Machine-callable storefront API for Boutique Rugs.",
    "description": "Public Shopify Ajax endpoints for catalog browse, cart management, and checkout handoff. All read endpoints are public and stateless. Cart and checkout endpoints require a session cookie. Payment is completed in Shopify's hosted checkout — agents must hand the checkout URL to the user.",
    "version": "1.0.0",
    "contact": {
      "name": "Boutique Rugs",
      "email": "support@boutiquerugs.com",
      "url": "https://boutiquerugs.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://boutiquerugs.com/policies/terms-of-service"
    },
    "x-machine-payment-protocol": {
      "version": "0.1",
      "checkout_handoff": {
        "type": "redirect",
        "url": "https://boutiquerugs.com/checkout",
        "description": "After cart is built, the agent must redirect the user to this URL. Payment, shipping address, and customer info are collected in Shopify's hosted checkout."
      },
      "supported_payment_methods": [
        "card",
        "shop_pay",
        "apple_pay",
        "google_pay",
        "paypal",
        "afterpay",
        "klarna"
      ],
      "currency": "USD",
      "currencies_supported": ["USD"],
      "tax_inclusive": false,
      "shipping_required": true,
      "agent_capabilities": {
        "build_cart": true,
        "complete_payment": false,
        "view_invoice": false,
        "subscribe": false,
        "refund": false
      },
      "auth": {
        "cart_session": "cookie",
        "customer_account": "oauth2",
        "oauth_protected_resource": "https://boutiquerugs.com/.well-known/oauth-protected-resource"
      }
    }
  },
  "servers": [
    {
      "url": "https://boutiquerugs.com",
      "description": "Boutique Rugs storefront (production)"
    }
  ],
  "tags": [
    { "name": "catalog", "description": "Browse products and collections" },
    { "name": "cart", "description": "Build and modify the cart session" },
    { "name": "checkout", "description": "Hand off to Shopify hosted checkout" },
    { "name": "policy", "description": "Store policies (shipping, returns, privacy, terms)" }
  ],
  "paths": {
    "/search/suggest.json": {
      "get": {
        "tags": ["catalog"],
        "operationId": "searchProducts",
        "summary": "Predictive product search",
        "description": "Free-text search across the catalog.",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Free-text query" },
          { "name": "resources[type]", "in": "query", "required": true, "schema": { "type": "string", "const": "product" } },
          { "name": "resources[limit]", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 10 } }
        ],
        "responses": {
          "200": {
            "description": "Matching products",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } }
          }
        }
      }
    },
    "/products/{handle}.json": {
      "get": {
        "tags": ["catalog"],
        "operationId": "getProduct",
        "summary": "Get product detail",
        "parameters": [
          { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Product handle" }
        ],
        "responses": {
          "200": {
            "description": "Product detail",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDetailResponse" } } }
          },
          "404": { "description": "Product not found" }
        }
      }
    },
    "/products.json": {
      "get": {
        "tags": ["catalog"],
        "operationId": "listProducts",
        "summary": "List products (paginated)",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 30, "maximum": 250 } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }
        ],
        "responses": {
          "200": {
            "description": "Product list",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } } } }
          }
        }
      }
    },
    "/collections.json": {
      "get": {
        "tags": ["catalog"],
        "operationId": "listCollections",
        "summary": "List collections",
        "responses": {
          "200": { "description": "Collection list", "content": { "application/json": {} } }
        }
      }
    },
    "/collections/{handle}/products.json": {
      "get": {
        "tags": ["catalog"],
        "operationId": "getCollectionProducts",
        "summary": "Get products in a collection",
        "parameters": [
          { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 30 } }
        ],
        "responses": { "200": { "description": "Products in collection", "content": { "application/json": {} } } }
      }
    },
    "/cart.js": {
      "get": {
        "tags": ["cart"],
        "operationId": "getCart",
        "summary": "Get current cart",
        "description": "Returns the active cart for the session cookie. If no cookie is set, an empty cart is returned and Set-Cookie initializes one.",
        "responses": {
          "200": {
            "description": "Cart state",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } }
          }
        }
      }
    },
    "/cart/add.js": {
      "post": {
        "tags": ["cart"],
        "operationId": "addToCart",
        "summary": "Add item to cart",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": { "type": "integer", "description": "Variant ID" },
                        "quantity": { "type": "integer", "minimum": 1, "default": 1 }
                      },
                      "required": ["id"]
                    }
                  }
                },
                "required": ["items"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Updated line items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartLineItem" } } } },
          "422": { "description": "Variant unavailable or out of stock" }
        }
      }
    },
    "/cart/update.js": {
      "post": {
        "tags": ["cart"],
        "operationId": "updateCart",
        "summary": "Update cart line quantities",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "updates": {
                    "type": "object",
                    "additionalProperties": { "type": "integer", "minimum": 0 }
                  }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Updated cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } } }
      }
    },
    "/cart/clear.js": {
      "post": {
        "tags": ["cart"],
        "operationId": "clearCart",
        "summary": "Clear the cart",
        "responses": { "200": { "description": "Empty cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } } } }
      }
    },
    "/checkout": {
      "get": {
        "tags": ["checkout"],
        "operationId": "startCheckout",
        "summary": "Start checkout (redirect)",
        "description": "Redirects (302) to Shopify's hosted checkout for the active cart cookie. Agents must hand the URL to the user — payment is collected here, not by the agent.",
        "x-machine-payment-handoff": true,
        "responses": {
          "302": {
            "description": "Redirect to hosted checkout",
            "headers": {
              "Location": { "schema": { "type": "string", "format": "uri" } }
            }
          }
        }
      }
    },
    "/policies/{handle}": {
      "get": {
        "tags": ["policy"],
        "operationId": "getPolicy",
        "summary": "Get a store policy",
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["shipping-policy", "refund-policy", "privacy-policy", "terms-of-service"]
            }
          }
        ],
        "responses": { "200": { "description": "Policy HTML", "content": { "text/html": {} } } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "cartCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "cart",
        "description": "Shopify cart session cookie. Set automatically by the storefront on first request."
      },
      "customerOAuth2": {
        "type": "oauth2",
        "description": "Shopify Customer Account OAuth (for authenticated customer skills, not required for cart/checkout).",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://shopify.com/authentication/<SHOP_ID>/oauth/authorize",
            "tokenUrl": "https://shopify.com/authentication/<SHOP_ID>/oauth/token",
            "scopes": {
              "openid": "OpenID Connect",
              "email": "Customer email",
              "customer-account-api:full": "Full customer account access"
            }
          }
        }
      }
    },
    "schemas": {
      "Product": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "handle": { "type": "string" },
          "title": { "type": "string" },
          "body_html": { "type": "string" },
          "vendor": { "type": "string" },
          "product_type": { "type": "string" },
          "tags": { "type": "array", "items": { "type": "string" } },
          "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Variant" } },
          "images": { "type": "array", "items": { "$ref": "#/components/schemas/Image" } }
        }
      },
      "Variant": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "title": { "type": "string" },
          "price": { "type": "string" },
          "available": { "type": "boolean" },
          "sku": { "type": "string" },
          "option1": { "type": "string", "nullable": true },
          "option2": { "type": "string", "nullable": true },
          "option3": { "type": "string", "nullable": true }
        }
      },
      "Image": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "src": { "type": "string", "format": "uri" },
          "alt": { "type": "string", "nullable": true }
        }
      },
      "ProductDetailResponse": {
        "type": "object",
        "properties": { "product": { "$ref": "#/components/schemas/Product" } }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "resources": {
            "type": "object",
            "properties": {
              "results": {
                "type": "object",
                "properties": {
                  "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }
                }
              }
            }
          }
        }
      },
      "Cart": {
        "type": "object",
        "properties": {
          "token": { "type": "string" },
          "currency": { "type": "string", "example": "USD" },
          "item_count": { "type": "integer" },
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/CartLineItem" } },
          "total_price": { "type": "integer", "description": "In cents" },
          "items_subtotal_price": { "type": "integer" },
          "checkout_url": { "type": "string", "format": "uri" }
        }
      },
      "CartLineItem": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "description": "Variant ID" },
          "quantity": { "type": "integer" },
          "title": { "type": "string" },
          "price": { "type": "integer", "description": "In cents" },
          "line_price": { "type": "integer" },
          "product_id": { "type": "integer" },
          "variant_id": { "type": "integer" },
          "url": { "type": "string", "format": "uri" }
        }
      }
    }
  }
}