{
  "openapi": "3.1.0",
  "info": {
    "title": "Vortex IQ Catalogue API (preview)",
    "version": "0.1.0",
    "description": "**Preview: in development, not yet live.** Product search across BigCommerce and Adobe Commerce (including Magento Open Source) stores whose merchants have opted in to sharing their catalogue. Read-only. Prices are in each store's own currency and every product links to its page on the merchant's store, where the shopper buys.\n\nOnly opted-in stores are ever searched. Hidden and disabled products are never returned, and nothing internal (cost price, stock counts, sales, customer or order data) is ever exposed.",
    "contact": {
      "name": "Vortex IQ Support",
      "url": "https://www.vortexiq.ai/contact-us",
      "email": "support@vortexiq.ai"
    }
  },
  "servers": [
    {
      "url": "https://app.vortexiq.ai/api/v1/catalog",
      "description": "Vortex IQ platform (planned)"
    }
  ],
  "security": [
    {
      "partnerAuth": []
    }
  ],
  "paths": {
    "/products/search": {
      "get": {
        "operationId": "searchProducts",
        "summary": "Search products",
        "description": "Free-text product search across all opted-in stores, or one store. Results are ranked by relevance.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 200
            },
            "description": "What the shopper is looking for.",
            "example": "waterproof walking boots"
          },
          {
            "name": "merchant",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Limit to one merchant id from List merchants."
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Category name to filter on."
          },
          {
            "name": "min_price",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            },
            "description": "Lowest price, in each store's own currency."
          },
          {
            "name": "max_price",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": 0
            },
            "description": "Highest price, in each store's own currency."
          },
          {
            "name": "in_stock",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            },
            "description": "Only products that are in stock or on preorder."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25,
              "default": 10
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "`next_cursor` from the previous page."
          }
        ],
        "responses": {
          "200": {
            "description": "Matching products.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "products",
                    "next_cursor"
                  ],
                  "properties": {
                    "products": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Product"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Pass as `cursor` for the next page; null on the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters, for example a missing `q`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached. Retry after the number of seconds in `Retry-After`.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/products/{product_id}": {
      "get": {
        "operationId": "getProduct",
        "summary": "Get a product",
        "description": "One product by its id. Returns 404 if the product is hidden, disabled or deleted, or if its store has stopped sharing.",
        "parameters": [
          {
            "name": "product_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "bc_3kgh3kz_1234"
          }
        ],
        "responses": {
          "200": {
            "description": "The product.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Product"
                }
              }
            }
          },
          "404": {
            "description": "No shareable product with that id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached. Retry after the number of seconds in `Retry-After`.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/merchants": {
      "get": {
        "operationId": "listMerchants",
        "summary": "List merchants",
        "description": "Stores whose merchants have opted in to catalogue sharing.",
        "parameters": [
          {
            "name": "platform",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "bigcommerce",
                "adobe_commerce"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Opted-in merchants.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "merchants",
                    "next_cursor"
                  ],
                  "properties": {
                    "merchants": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Merchant"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached. Retry after the number of seconds in `Retry-After`.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "partnerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "A bearer token issued to approved partners such as Meta, sent as `Authorization: Bearer <token>`. Partner credentials are issued during onboarding; shoppers never sign in."
      }
    },
    "schemas": {
      "Money": {
        "type": "object",
        "required": [
          "amount",
          "currency"
        ],
        "properties": {
          "amount": {
            "type": "string",
            "description": "Decimal amount as a string, so no precision is lost.",
            "examples": [
              "49.99"
            ]
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 code of the store's currency.",
            "examples": [
              "GBP"
            ]
          }
        }
      },
      "Merchant": {
        "type": "object",
        "required": [
          "id",
          "name",
          "domain",
          "platform",
          "currency"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable merchant id.",
            "examples": [
              "m_7f3c2a"
            ]
          },
          "name": {
            "type": "string",
            "examples": [
              "Example Outdoor Co"
            ]
          },
          "domain": {
            "type": "string",
            "description": "The store's public domain. Product links point here.",
            "examples": [
              "www.example-outdoor.com"
            ]
          },
          "platform": {
            "type": "string",
            "enum": [
              "bigcommerce",
              "adobe_commerce"
            ],
            "description": "Adobe Commerce includes Magento Open Source."
          },
          "currency": {
            "type": "string",
            "examples": [
              "GBP"
            ]
          }
        }
      },
      "Product": {
        "type": "object",
        "required": [
          "id",
          "merchant",
          "title",
          "price",
          "availability",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable product id, unique across all merchants.",
            "examples": [
              "bc_3kgh3kz_1234"
            ]
          },
          "merchant": {
            "$ref": "#/components/schemas/Merchant"
          },
          "title": {
            "type": "string",
            "examples": [
              "Trail Runner 2 Waterproof Boot"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Short plain-text description, no HTML."
          },
          "brand": {
            "type": [
              "string",
              "null"
            ]
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "examples": [
              [
                "Footwear",
                "Walking Boots"
              ]
            ]
          },
          "price": {
            "$ref": "#/components/schemas/Money",
            "description": "The price the store shows on the product page."
          },
          "sale_price": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Money"
              },
              {
                "type": "null"
              }
            ],
            "description": "Present only while a sale price applies."
          },
          "availability": {
            "type": "string",
            "enum": [
              "in_stock",
              "out_of_stock",
              "preorder"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The product page on the merchant's own store. Shoppers buy there.",
            "examples": [
              "https://www.example-outdoor.com/trail-runner-2/"
            ]
          },
          "image_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "sku": {
            "type": [
              "string",
              "null"
            ]
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "error_description"
        ],
        "properties": {
          "error": {
            "type": "string",
            "examples": [
              "invalid_request"
            ]
          },
          "error_description": {
            "type": "string"
          }
        }
      }
    }
  }
}