{
  "openapi": "3.1.0",
  "info": {
    "title": "Black Jewel Caviar Storefront API",
    "version": "1.0.0",
    "description": "Public read-only access to Black Jewel Caviar products, catalog search and related products. Requests use Shopify storefront context. Use the UCP profile for agent shopping, carts and checkout."
  },
  "servers": [{"url": "https://blackjewelcaviar.com"}],
  "externalDocs": {
    "description": "Storefront API documentation",
    "url": "https://blackjewelcaviar.com/pages/storefront-api"
  },
  "security": [],
  "paths": {
    "/search/suggest.json": {
      "get": {
        "operationId": "searchStorefrontProducts",
        "summary": "Find matching caviar, seafood and gifts",
        "description": "Search by a shopper's words. Set resources[type] to product to restrict results to products. Predictive search prices are decimal strings in the shopper's presentment currency.",
        "parameters": [
          {"name": "q", "in": "query", "required": true, "description": "Search terms, such as siberian caviar or gift box.", "schema": {"type": "string", "minLength": 1}, "example": "caviar"},
          {"name": "resources[type]", "in": "query", "description": "Result type. Use product for shopping queries.", "schema": {"type": "string", "enum": ["product"]}},
          {"name": "resources[limit]", "in": "query", "description": "Maximum number of results to request.", "schema": {"type": "integer", "minimum": 1, "maximum": 10}}
        ],
        "responses": {
          "200": {
            "description": "Search results. A search with no matches returns an empty product array.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SearchResults"}}}
          },
          "429": {"description": "Shopify rate limit. Back off and respect Retry-After when present."}
        }
      }
    },
    "/products/{handle}.js": {
      "get": {
        "operationId": "getStorefrontProduct",
        "summary": "Get current product variants and prices",
        "description": "Read a published product by its storefront handle. Price integers use Shopify's presentment-currency subunit representation. Verify the selected variant's availability before recommending it.",
        "parameters": [
          {"name": "handle", "in": "path", "required": true, "description": "Product handle from its storefront URL or search result.", "schema": {"type": "string", "minLength": 1, "pattern": "^[a-z0-9-]+$"}, "example": "siberian-caviar"}
        ],
        "responses": {
          "200": {
            "description": "JSON product document served with Shopify's JavaScript MIME type.",
            "content": {"text/javascript": {"schema": {"$ref": "#/components/schemas/Product"}}}
          },
          "404": {"description": "The handle does not match a product published in the store."},
          "429": {"description": "Shopify rate limit. Back off and respect Retry-After when present."}
        }
      }
    },
    "/recommendations/products.json": {
      "get": {
        "operationId": "getRelatedStorefrontProducts",
        "summary": "Find related products for a published product",
        "description": "Use the numeric product ID from a product or search result. Results may be empty if Shopify has no recommendations for that product.",
        "parameters": [
          {"name": "product_id", "in": "query", "required": true, "description": "Numeric Shopify product ID, distinct from a variant ID.", "schema": {"type": "integer", "format": "int64"}, "example": 15426747597115},
          {"name": "limit", "in": "query", "description": "Maximum recommendations to return.", "schema": {"type": "integer", "minimum": 1, "maximum": 10}}
        ],
        "responses": {
          "200": {
            "description": "Related products in the same format as the product endpoint.",
            "content": {"application/json": {"schema": {"type": "object", "required": ["products"], "properties": {"products": {"type": "array", "items": {"$ref": "#/components/schemas/Product"}}}}}}
          },
          "404": {
            "description": "The product ID is not published in this storefront.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ShopifyError"}}}
          },
          "429": {"description": "Shopify rate limit. Back off and respect Retry-After when present."}
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchResults": {
        "type": "object",
        "required": ["resources"],
        "properties": {
          "resources": {
            "type": "object",
            "required": ["results"],
            "properties": {
              "results": {"type": "object", "properties": {"products": {"type": "array", "items": {"$ref": "#/components/schemas/SearchProduct"}}}}
            }
          }
        }
      },
      "SearchProduct": {
        "type": "object",
        "required": ["id", "handle", "title", "available", "url", "price"],
        "properties": {
          "id": {"type": "integer", "format": "int64"},
          "handle": {"type": "string"},
          "title": {"type": "string"},
          "available": {"type": "boolean"},
          "url": {"type": "string", "description": "Relative storefront link."},
          "price": {"type": "string", "description": "Decimal price in the shopper's presentment currency."}
        }
      },
      "Product": {
        "type": "object",
        "required": ["id", "handle", "title", "available", "price_min", "price_max", "variants"],
        "properties": {
          "id": {"type": "integer", "format": "int64"},
          "handle": {"type": "string"},
          "title": {"type": "string"},
          "available": {"type": "boolean"},
          "description": {"type": ["string", "null"], "description": "Product description as HTML."},
          "price_min": {"type": "integer", "description": "Lowest variant price in Shopify currency subunits."},
          "price_max": {"type": "integer", "description": "Highest variant price in Shopify currency subunits."},
          "variants": {"type": "array", "items": {"$ref": "#/components/schemas/Variant"}}
        }
      },
      "Variant": {
        "type": "object",
        "required": ["id", "title", "available", "price"],
        "properties": {
          "id": {"type": "integer", "format": "int64"},
          "title": {"type": "string"},
          "available": {"type": "boolean"},
          "price": {"type": "integer", "description": "Variant price in Shopify currency subunits."},
          "options": {"type": "array", "items": {"type": "string"}}
        }
      },
      "ShopifyError": {
        "type": "object",
        "required": ["status", "message", "description"],
        "properties": {
          "status": {"type": "integer"},
          "message": {"type": "string"},
          "description": {"type": "string"}
        }
      }
    }
  }
}