{
  "openapi": "3.1.0",
  "info": {
    "title": "Collection Kit storefront contract v1",
    "version": "1",
    "description": "What a Collection Kit bundle built against contract v1 reads from Mercury. Frozen: the server keeps satisfying it for as long as the version is supported.\n\nStatus: supported; frozen (sha256 of every file in api-types/src/kit-contract/lock.json).",
    "x-audience": "public",
    "x-kit-contract": {
      "version": "v1",
      "supported": true,
      "files": [
        "index.ts",
        "manifest.ts",
        "preview.ts",
        "search-api.ts",
        "theme.ts"
      ]
    }
  },
  "servers": [
    {
      "url": "https://mercury.plutocracy.io",
      "description": "Storefront (view) API: every region, latency-routed"
    }
  ],
  "paths": {
    "/search/collection/{handle}": {
      "get": {
        "operationId": "v1.collection",
        "summary": "A collection page. `handle` is the Shopify collection handle, URL-encoded.",
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "take",
            "in": "query",
            "required": true,
            "description": "Page size, 1-50. The bundle never sends page/pageNumber.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "skip",
            "in": "query",
            "required": true,
            "description": "Offset, >= 0.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "JSON-encoded QueryClause[].",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "bypassToken",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "currency",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "grid_config",
            "in": "query",
            "required": false,
            "description": "\"1\" to include grid_config in the response. Never \"false\".",
            "schema": {
              "type": "string",
              "const": "1"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageResponse"
                }
              }
            }
          }
        },
        "x-kit-route": "collection"
      }
    },
    "/search/product/handles/{handles}": {
      "get": {
        "operationId": "v1.productsByHandles",
        "summary": "Products by handle (comma-separated, at most 20); responds with Product[] (or one Product).",
        "parameters": [
          {
            "name": "handles",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "bypassToken",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "currency",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Product"
                      }
                    },
                    {
                      "$ref": "#/components/schemas/Product"
                    }
                  ]
                }
              }
            }
          }
        },
        "x-kit-route": "productsByHandles"
      }
    },
    "/search/query/{term}": {
      "get": {
        "operationId": "v1.search",
        "summary": "A search results page. `term` is the URL-encoded search term.",
        "parameters": [
          {
            "name": "term",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "take",
            "in": "query",
            "required": true,
            "description": "Page size, 1-50. The bundle never sends page/pageNumber.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "skip",
            "in": "query",
            "required": true,
            "description": "Offset, >= 0.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "JSON-encoded QueryClause[].",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "bypassToken",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "currency",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "grid_config",
            "in": "query",
            "required": false,
            "description": "\"1\" to include grid_config in the response. Never \"false\".",
            "schema": {
              "type": "string",
              "const": "1"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageResponse"
                }
              }
            }
          }
        },
        "x-kit-route": "search"
      }
    }
  },
  "components": {
    "schemas": {
      "Badge": {
        "description": "A merchandising badge as the server sends it. Positions use \"centery\"/\"centerx\" for centred.",
        "type": "object",
        "properties": {
          "content": {
            "type": "string"
          },
          "background": {
            "type": "string"
          },
          "colour": {
            "type": "string"
          },
          "positiony": {
            "type": "string"
          },
          "positionx": {
            "type": "string"
          },
          "classes": {
            "type": "string",
            "description": "CSS classes for the badge."
          },
          "type": {
            "type": "string"
          }
        },
        "required": [
          "content",
          "background",
          "colour",
          "positiony",
          "positionx"
        ],
        "x-source": "api-types/src/kit-contract/v1/search-api.ts"
      },
      "Bundle": {
        "description": "Collection Kit storefront contract v1: the MERCURY.KIT shop metafield (JSON), read by the theme\nblock and kit.js. FROZEN: never edit; add v2 instead (see ../README.md).",
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "https URL of the ES module (Shopify Files)."
          },
          "integrity": {
            "type": "string",
            "description": "\"sha384-<base64>\"; the loader verifies it before running the module."
          },
          "filename": {
            "type": "string"
          },
          "slots": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "fileId": {
            "type": "string"
          },
          "publishedAt": {
            "type": "string"
          }
        },
        "required": [
          "url"
        ],
        "x-source": "api-types/src/kit-contract/v1/manifest.ts"
      },
      "Campaign": {
        "type": "object",
        "properties": {
          "id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ]
          },
          "title": {
            "type": "string"
          },
          "blocks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CampaignTile"
            }
          }
        },
        "x-source": "api-types/src/kit-contract/v1/search-api.ts"
      },
      "CampaignTile": {
        "type": "object",
        "properties": {
          "id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ]
          },
          "blockId": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ]
          },
          "content": {
            "anyOf": [
              {
                "type": "null"
              },
              {
                "type": "string"
              },
              {
                "type": "object",
                "additionalProperties": {}
              }
            ],
            "description": "An object, or a JSON string of one."
          },
          "link": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "sizes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CampaignTileSize"
            }
          }
        },
        "x-source": "api-types/src/kit-contract/v1/search-api.ts"
      },
      "CampaignTileSize": {
        "description": "Stored sizes use minwidth/colSpan/colRow (row span); the editor also writes viewportIndex/rowSpan.",
        "type": "object",
        "properties": {
          "viewportIndex": {
            "type": "number"
          },
          "breakpoint": {
            "type": "number"
          },
          "minwidth": {
            "type": "number"
          },
          "index": {
            "type": [
              "number",
              "null"
            ]
          },
          "colSpan": {
            "type": "number"
          },
          "rowSpan": {
            "type": "number"
          },
          "colRow": {
            "type": "number",
            "description": "Row span."
          }
        },
        "x-source": "api-types/src/kit-contract/v1/search-api.ts"
      },
      "Facets": {
        "type": "object",
        "properties": {
          "count": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ],
            "description": "Total matching products (drives the count and pagination)."
          },
          "vendors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "vendor": {
                  "type": "string"
                },
                "count": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "number"
                    }
                  ]
                }
              },
              "required": [
                "vendor"
              ]
            }
          },
          "types": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                },
                "count": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "number"
                    }
                  ]
                }
              },
              "required": [
                "type"
              ]
            }
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "string"
                },
                "count": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "number"
                    }
                  ]
                }
              },
              "required": [
                "value"
              ]
            }
          }
        },
        "required": [
          "count"
        ],
        "x-source": "api-types/src/kit-contract/v1/search-api.ts"
      },
      "GridConfig": {
        "description": "The grid_config document (only with grid_config=1). Its layout keys match theme.MercuryConfig's\ncamelCase forms; the bundle falls back to it when the page has no window._mercury.",
        "type": "object",
        "properties": {
          "grid": {
            "type": "object",
            "additionalProperties": {}
          },
          "currency": {
            "type": "string"
          },
          "locale": {
            "type": "string"
          },
          "delimiter": {
            "type": "string"
          },
          "sizeMapping": {},
          "colourMapping": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "imageMapping": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "facetMapping": {}
        },
        "x-source": "api-types/src/kit-contract/v1/search-api.ts"
      },
      "Manifest": {
        "type": "object",
        "properties": {
          "sdk": {
            "type": "string",
            "description": "SDK major the bundles target (\"0\")."
          },
          "app": {
            "$ref": "#/components/schemas/Bundle",
            "description": "The store's app bundle (overrides and kit in one module). When present, the theme block loads it\nas <script type=\"module\" integrity> instead of kit.js, and `bundles` is empty."
          },
          "bundles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Bundle"
            },
            "description": "Override-only bundles kit.js loads onto itself (when there is no app bundle)."
          },
          "flags": {
            "type": "object",
            "properties": {
              "strict": {
                "type": "boolean",
                "description": "Surface override errors instead of falling back to the default slot."
              }
            }
          }
        },
        "required": [
          "sdk",
          "bundles"
        ],
        "x-source": "api-types/src/kit-contract/v1/manifest.ts"
      },
      "MercuryConfig": {
        "description": "window._mercury: the MERCURY.* shop metafields and page context, lowercase keys.",
        "type": "object",
        "properties": {
          "locale": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "delimiter": {
            "type": [
              "string",
              "null"
            ]
          },
          "sizemapping": {},
          "colourmapping": {
            "anyOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              }
            ]
          },
          "facetmapping": {},
          "imagemapping": {
            "anyOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                }
              }
            ]
          },
          "grid": {
            "anyOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": {}
              }
            ],
            "description": "The store's grid layout (MERCURY.GRID). When absent the bundle requests grid_config."
          },
          "bypasstoken": {
            "type": [
              "string",
              "null"
            ],
            "description": "Storefront bypass token (MERCURY.BYPASSTOKEN)."
          },
          "myshopify": {
            "type": "string",
            "description": "The shop's myshopify domain (used for preview links)."
          },
          "collection": {
            "type": "string",
            "description": "Collection handle, or \"search\"."
          },
          "designmode": {
            "type": "boolean"
          },
          "kit": {
            "anyOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Manifest"
              }
            ],
            "description": "The MERCURY.KIT metafield."
          }
        },
        "x-source": "api-types/src/kit-contract/v1/theme.ts"
      },
      "MissingProduct": {
        "description": "A product that could not be found arrives as {} in its slot; the bundle skips it.",
        "type": "object",
        "additionalProperties": {
          "not": {}
        },
        "x-source": "api-types/src/kit-contract/v1/search-api.ts"
      },
      "MountElement": {
        "description": "The element a bundle mounts into: <mercury-kit>, with these data attributes (all optional). A bundle\nmounts every <mercury-kit> on the page that has neither data-mounted nor data-manual.",
        "type": "object",
        "properties": {
          "tag": {
            "type": "string",
            "const": "mercury-kit"
          },
          "dataset": {
            "type": "object",
            "properties": {
              "collection": {
                "type": "string",
                "description": "Collection handle, or \"search\". Defaults to the /collections/<handle> URL."
              },
              "search": {
                "type": "string",
                "description": "Search term (search template)."
              },
              "api": {
                "type": "string",
                "description": "API base URL override."
              },
              "bypassToken": {
                "type": "string"
              },
              "currency": {
                "type": "string"
              },
              "urlSync": {
                "type": "string",
                "description": "\"false\" to keep filters/sort/page out of the URL."
              },
              "measure": {
                "type": "string",
                "description": "\"container\" to size breakpoints by the element instead of the window."
              },
              "mounted": {
                "type": "string",
                "description": "Set by the bundle once mounted."
              },
              "manual": {
                "type": "string",
                "description": "Present: the page mounts it itself."
              }
            }
          }
        },
        "required": [
          "tag",
          "dataset"
        ],
        "x-source": "api-types/src/kit-contract/v1/theme.ts"
      },
      "PageQuery": {
        "description": "Query parameters the bundle sends to the collection and search routes. All strings on the wire.",
        "type": "object",
        "properties": {
          "take": {
            "type": "string",
            "description": "Page size, 1-50. The bundle never sends page/pageNumber."
          },
          "skip": {
            "type": "string",
            "description": "Offset, >= 0."
          },
          "sort": {
            "type": "string"
          },
          "query": {
            "type": "string",
            "description": "JSON-encoded QueryClause[]."
          },
          "bypassToken": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "grid_config": {
            "type": "string",
            "const": "1",
            "description": "\"1\" to include grid_config in the response. Never \"false\"."
          }
        },
        "required": [
          "take",
          "skip"
        ],
        "x-source": "api-types/src/kit-contract/v1/search-api.ts"
      },
      "PageResponse": {
        "description": "Response of the collection and search routes.",
        "type": "object",
        "properties": {
          "id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ]
          },
          "title": {
            "type": "string"
          },
          "handle": {
            "type": "string"
          },
          "body_html": {
            "type": "string"
          },
          "image": {},
          "metafields": {
            "type": "object",
            "additionalProperties": {}
          },
          "sort_order": {
            "type": "string"
          },
          "config": {
            "type": "object",
            "additionalProperties": {}
          },
          "campaign": {
            "anyOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Campaign"
              }
            ]
          },
          "facets": {
            "$ref": "#/components/schemas/Facets"
          },
          "products": {
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "$ref": "#/components/schemas/Product"
                },
                {
                  "$ref": "#/components/schemas/MissingProduct"
                }
              ]
            }
          },
          "query": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QueryClause"
            },
            "description": "Echo of the parsed query clauses."
          },
          "search": {
            "type": "string",
            "description": "The search term executed (search route)."
          },
          "suggested": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "redirect": {
            "type": [
              "string",
              "null"
            ]
          },
          "grid_config": {
            "anyOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/GridConfig"
              }
            ]
          }
        },
        "required": [
          "facets",
          "products"
        ],
        "x-source": "api-types/src/kit-contract/v1/search-api.ts"
      },
      "PresentmentPrice": {
        "description": "A price in one presentment currency. Numbers, or decimal strings.",
        "type": "object",
        "properties": {
          "price": {
            "anyOf": [
              {
                "type": "null"
              },
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ]
          },
          "compare_at_price": {
            "anyOf": [
              {
                "type": "null"
              },
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ]
          }
        },
        "required": [
          "price"
        ],
        "x-source": "api-types/src/kit-contract/v1/search-api.ts"
      },
      "Product": {
        "description": "A product. Required fields are guaranteed by the server (the server's contract spec checks them);\noptional ones may be absent.",
        "type": "object",
        "properties": {
          "handle": {
            "type": "string"
          },
          "id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ]
          },
          "title": {
            "type": "string"
          },
          "vendor": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "min_price": {
            "type": [
              "number",
              "null"
            ],
            "description": "Absent (or null) when zero."
          },
          "compare_at_min_price": {
            "type": [
              "number",
              "null"
            ]
          },
          "on_sale": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "number"
              }
            ],
            "description": "Boolean or 0/1."
          },
          "total_stock": {
            "type": "number"
          },
          "created_date": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "image": {
            "type": "string"
          },
          "images": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "variants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Variant"
            }
          },
          "prices": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/PresentmentPrice"
            },
            "description": "Prices per presentment currency code."
          },
          "related": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/RelatedProduct"
                }
              }
            ],
            "description": "Related products: a JSON string of RelatedProduct[] (or the array itself)."
          },
          "imploded": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Product"
            },
            "description": "Products imploded into this one (same shape)."
          },
          "meta": {
            "type": "object",
            "properties": {
              "badges": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Badge"
                }
              }
            },
            "additionalProperties": {}
          }
        },
        "required": [
          "handle",
          "id",
          "title",
          "vendor",
          "type",
          "on_sale",
          "total_stock",
          "created_date",
          "tags",
          "image",
          "images",
          "variants",
          "prices"
        ],
        "additionalProperties": {},
        "x-source": "api-types/src/kit-contract/v1/search-api.ts"
      },
      "QueryClause": {
        "description": "One filter clause of the `query` parameter (and its echo in responses).",
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "\"tag\", \"vendor\", \"type\", \"price\", \"min_price\", \"id\", \"title\", or a store's own facet type."
          },
          "operator": {
            "type": "string"
          },
          "condition": {
            "type": "string"
          },
          "value": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "disjunctive": {
            "type": "boolean"
          }
        },
        "required": [
          "type",
          "value"
        ],
        "x-source": "api-types/src/kit-contract/v1/search-api.ts"
      },
      "RelatedProduct": {
        "description": "A related product (from the `related` JSON string).",
        "type": "object",
        "properties": {
          "handle": {
            "type": "string"
          },
          "id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ]
          },
          "junoId": {
            "type": "string"
          },
          "hidden": {
            "type": "boolean"
          },
          "image": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "color": {
            "type": "string"
          }
        },
        "required": [
          "handle"
        ],
        "x-source": "api-types/src/kit-contract/v1/search-api.ts"
      },
      "Variant": {
        "type": "object",
        "properties": {
          "id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ]
          },
          "title": {
            "type": "string"
          },
          "price": {
            "anyOf": [
              {
                "type": "null"
              },
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ],
            "description": "Decimal string (\"119.95\") or number."
          },
          "compare_at_price": {
            "anyOf": [
              {
                "type": "null"
              },
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ],
            "description": "Decimal string, \"\" or null when unset."
          },
          "inventory": {
            "anyOf": [
              {
                "type": "null"
              },
              {
                "type": "string"
              },
              {
                "type": "number"
              }
            ]
          },
          "option1": {
            "type": [
              "string",
              "null"
            ]
          },
          "option2": {
            "type": [
              "string",
              "null"
            ]
          },
          "option3": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "title",
          "price"
        ],
        "additionalProperties": {},
        "x-source": "api-types/src/kit-contract/v1/search-api.ts"
      }
    }
  }
}