{
  "openapi": "3.1.0",
  "info": {
    "title": "ShopData API",
    "version": "1.0.0",
    "summary": "Real-Time E-Commerce Product, BuyBox Price, SKU Matrix, Reviews, TikTok Shop, Facebook Marketplace & 1688 Wholesale Intelligence API",
    "description": "ShopData API (https://shopdataapi.com) provides normalized, sub-second REST and Remote MCP endpoints for Amazon, Walmart, Etsy, Facebook Marketplace, TikTok Shop, Shopee, 1688 Wholesale, and Taobao / Tmall. Up to 90% cheaper than Rainforest API & Keepa ($1.00 = 10,000 Credits; 2 Credits/item on search & reviews, 3 Credits/call on TikTok Shop product detail, 5 Credits/call on Facebook Marketplace search & item, 10 Credits/call on Amazon/Walmart/1688/Taobao full SKU detail; 0 Credits on empty/error). Claim 12,000 free sandbox credits ($1.20) instantly with no credit card at https://shopdataapi.com/signup.",
    "contact": {
      "name": "ShopData API Engineering",
      "url": "https://shopdataapi.com/docs",
      "email": "support@shopdataapi.com"
    }
  },
  "servers": [
    {
      "url": "https://api.shopdataapi.com",
      "description": "Production Global E-Commerce REST & MCP Gateway"
    },
    {
      "url": "https://mcp.shopdataapi.com",
      "description": "Dedicated OAuth 2.1 Remote MCP Connector Server"
    }
  ],
  "security": [
    { "ApiKeyHeader": [] },
    { "BearerAuth": [] }
  ],
  "tags": [
    { "name": "Amazon", "description": "Real-time Amazon search, ASIN BuyBox product details, SKU variation matrices, and verified customer reviews across 18 countries." },
    { "name": "Walmart", "description": "Real-time Walmart keyword search, Rollback pricing, seller details, fulfillment speed, and full product/SKU payloads." },
    { "name": "Etsy", "description": "Real-time Etsy handmade & vintage marketplace listings, Star Seller badges, and buyer reviews." },
    { "name": "1688 Wholesale", "description": "Direct China 1688.com factory wholesale product search, MOQ tiered price ladders (CNY + USD), repurchase rates, and SKU stock matrices." },
    { "name": "Taobao & Tmall", "description": "Real-time Taobao and Tmall retail product search, monthly sales volume, and full SKU property combinations." },
    { "name": "Global Social & SEA", "description": "TikTok Shop viral product search & full SKU/reviews product detail, plus Shopee Southeast Asia (SG, MY, TH, VN, PH, ID, TW, BR)." },
    { "name": "Facebook Marketplace", "description": "Real-time Facebook Marketplace local & shipping search and full listing condition/seller/delivery detail." },
    { "name": "System & Playground", "description": "Zero-cost health checks, live latency telemetry, and public sandbox playground." }
  ],
  "paths": {
    "/v1/amazon/search": {
      "get": {
        "tags": ["Amazon"],
        "operationId": "amazonSearch",
        "summary": "Search Amazon Products & BuyBox Prices",
        "description": "Search real-time Amazon products by keyword across 18 marketplaces. Cost: 2 Credits / product returned (0 Credits if empty).",
        "parameters": [
          { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "example": "ceramic mug" }, "description": "Search keyword (aliases: q, keyword, search_term)." },
          { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "default": "US", "example": "US" }, "description": "Amazon marketplace ISO-2 code (US, UK, DE, JP, CA, FR, IT, ES, AU, MX, IN)." },
          { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1, "maximum": 50 } }
        ],
        "responses": {
          "200": { "description": "Normalized Amazon product list with ASIN, BuyBox price, Prime status, rating, reviews, and 30d sales.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" } } } }
        }
      }
    },
    "/v1/amazon/product": {
      "get": {
        "tags": ["Amazon"],
        "operationId": "amazonProduct",
        "summary": "Get Amazon Product Details & SKU Matrix by ASIN",
        "description": "Retrieve full Amazon product details, BuyBox seller, gallery images, feature bullets, and SKU variation matrix by ASIN or URL. Cost: 10 Credits / product.",
        "parameters": [
          { "name": "asin", "in": "query", "required": true, "schema": { "type": "string", "example": "B0CRMP3RQT" }, "description": "10-character Amazon ASIN or full Amazon URL." },
          { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "default": "US" } }
        ],
        "responses": {
          "200": { "description": "Normalized Amazon product detail object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDetailResponse" } } } }
        }
      }
    },
    "/v1/amazon/reviews": {
      "get": {
        "tags": ["Amazon"],
        "operationId": "amazonReviews",
        "summary": "Get Verified Amazon Customer Reviews by ASIN",
        "description": "Extract verified-purchase customer reviews, star ratings, variant attributes, and review images for an Amazon ASIN. Cost: 2 Credits / review returned.",
        "parameters": [
          { "name": "asin", "in": "query", "required": true, "schema": { "type": "string", "example": "B0CRMP3RQT" } },
          { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "default": "US" } },
          { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }
        ],
        "responses": {
          "200": { "description": "Normalized customer review list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewListResponse" } } } }
        }
      }
    },
    "/v1/walmart/search": {
      "get": {
        "tags": ["Walmart"],
        "operationId": "walmartSearch",
        "summary": "Search Walmart Products & Rollback Prices",
        "description": "Search Walmart.com products by keyword with real-time prices, list prices, fulfillment badges, and ratings. Cost: 2 Credits / product returned.",
        "parameters": [
          { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "example": "ceramic mug" } },
          { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } },
          { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "default": "best_match", "enum": ["best_match", "price_low", "price_high", "best_seller"] } }
        ],
        "responses": {
          "200": { "description": "Normalized Walmart product list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" } } } }
        }
      }
    },
    "/v1/walmart/product": {
      "get": {
        "tags": ["Walmart"],
        "operationId": "walmartProduct",
        "summary": "Get Full Walmart Product & SKU Details",
        "description": "Retrieve full Walmart product pricing, stock status, seller info, and SKU matrix by item ID or walmart.com URL. Cost: 10 Credits / product.",
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "example": "2659627283" }, "description": "Walmart numeric item ID or full walmart.com/ip/... URL." }
        ],
        "responses": {
          "200": { "description": "Normalized Walmart product detail object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDetailResponse" } } } }
        }
      }
    },
    "/v1/etsy/search": {
      "get": {
        "tags": ["Etsy"],
        "operationId": "etsySearch",
        "summary": "Search Etsy Handmade & Vintage Listings",
        "description": "Search Etsy listings with handmade shop details, Star Seller status, prices, and review counts. Cost: 2 Credits / listing returned.",
        "parameters": [
          { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "example": "ceramic mug" } },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 50 } }
        ],
        "responses": {
          "200": { "description": "Normalized Etsy listing results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" } } } }
        }
      }
    },
    "/v1/etsy/reviews": {
      "get": {
        "tags": ["Etsy"],
        "operationId": "etsyReviews",
        "summary": "Get Etsy Listing Buyer Reviews",
        "description": "Extract verified buyer reviews for an Etsy listing_id. Cost: 2 Credits / review returned.",
        "parameters": [
          { "name": "listing_id", "in": "query", "required": true, "schema": { "type": "string", "example": "1510223855" } }
        ],
        "responses": {
          "200": { "description": "Normalized Etsy review list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewListResponse" } } } }
        }
      }
    },
    "/v1/1688/search": {
      "get": {
        "tags": ["1688 Wholesale"],
        "operationId": "alibaba1688Search",
        "summary": "Search 1688 Factory Wholesale Listings & MOQ Price Ladders",
        "description": "Search China 1688.com factory wholesale offers with MOQ tiered prices (CNY & USD), Verified Super Factory badges, repurchase rates, and 30d sales. Cost: 2 Credits / item returned.",
        "parameters": [
          { "name": "keyword", "in": "query", "required": true, "schema": { "type": "string", "example": "陶瓷马克杯" } },
          { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }
        ],
        "responses": {
          "200": { "description": "Normalized 1688 wholesale offer list with MOQ tiers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" } } } }
        }
      }
    },
    "/v1/1688/item": {
      "get": {
        "tags": ["1688 Wholesale"],
        "operationId": "alibaba1688Item",
        "summary": "Get 1688 Factory Item MOQ Ladder & SKU Inventory Matrix",
        "description": "Retrieve complete 1688 wholesale item details including MOQ tiered pricing (CNY & USD), SKU inventory matrix, and factory verification. Cost: 10 Credits / item.",
        "parameters": [
          { "name": "item_id", "in": "query", "required": true, "schema": { "type": "string", "example": "1088453066793" } }
        ],
        "responses": {
          "200": { "description": "Normalized 1688 wholesale item detail object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDetailResponse" } } } }
        }
      }
    },
    "/v1/taobao/search": {
      "get": {
        "tags": ["Taobao & Tmall"],
        "operationId": "taobaoSearch",
        "summary": "Search Taobao & Tmall Retail Products",
        "description": "Search Taobao and Tmall listings with CNY/USD retail prices, Tmall flagship badges, and monthly sales. Cost: 2 Credits / item returned.",
        "parameters": [
          { "name": "keyword", "in": "query", "required": true, "schema": { "type": "string", "example": "手机壳" } },
          { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 } }
        ],
        "responses": {
          "200": { "description": "Normalized Taobao/Tmall search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" } } } }
        }
      }
    },
    "/v1/taobao/item": {
      "get": {
        "tags": ["Taobao & Tmall"],
        "operationId": "taobaoItem",
        "summary": "Get Taobao / Tmall Item Details & SKU Matrix",
        "description": "Fetch full Taobao or Tmall item details and SKU combinations by item_id. Cost: 10 Credits / item.",
        "parameters": [
          { "name": "item_id", "in": "query", "required": true, "schema": { "type": "string", "example": "862339102275" } }
        ],
        "responses": {
          "200": { "description": "Normalized Taobao/Tmall item detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDetailResponse" } } } }
        }
      }
    },
    "/v1/shopee/search": {
      "get": {
        "tags": ["Global Social & SEA"],
        "operationId": "shopeeSearch",
        "summary": "Search Shopee Southeast Asia Marketplace Products",
        "description": "Search Shopee products across SG, MY, TH, VN, PH, ID, TW, and BR. Cost: 2 Credits / item returned.",
        "parameters": [
          { "name": "keyword", "in": "query", "required": true, "schema": { "type": "string", "example": "mug" } },
          { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "default": "SG" } }
        ],
        "responses": {
          "200": { "description": "Normalized Shopee product list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" } } } }
        }
      }
    },
    "/v1/tiktok-shop/search": {
      "get": {
        "tags": ["Global Social & SEA"],
        "operationId": "tiktokShopSearch",
        "summary": "Search TikTok Shop Viral Products & GMV Sales",
        "description": "Search trending TikTok Shop products with live pricing, 30-day sales volume, and shop ratings. Supports GET query params and POST JSON body. Cost: 2 Credits / item returned.",
        "x-credits-per-request": "2 Credits / item",
        "x-price-per-request": "$0.08–$0.20 / 1K items",
        "parameters": [
          { "name": "keyword", "in": "query", "required": true, "schema": { "type": "string", "example": "mug" } },
          { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "default": "US" } }
        ],
        "responses": {
          "200": { "description": "Normalized TikTok Shop product list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductListResponse" } } } }
        }
      }
    },
    "/v1/tiktok-shop/product": {
      "get": {
        "tags": ["Global Social & SEA"],
        "operationId": "tiktokShopProduct",
        "summary": "Get TikTok Shop Product, SKU Variants & Top Reviews",
        "description": "Retrieve complete TikTok Shop product intelligence by product_id, id, or full TikTok Shop URL (supports GET query params and POST JSON body; aliases: /v1/tiktok-shop/item, /v1/tiktok/product). Returns all 10 core commerce fields: price, list_price, stock, sold_count, shop ({id, name, rating, url}), variants (SKU list), images, rating, rating_count, and top_reviews. Cost: 3 Credits / call ($0.30/1K PAYG, $0.12/1K Business; 0 Credits on 404/empty).",
        "x-credits-per-request": "3 Credits / call",
        "x-price-per-request": "$0.12–$0.30 / 1K calls",
        "parameters": [
          { "name": "product_id", "in": "query", "required": true, "schema": { "type": "string", "example": "1730073687428142070" }, "description": "TikTok Shop numeric product_id, id, or full TikTok Shop product URL." },
          { "name": "region", "in": "query", "required": false, "schema": { "type": "string", "default": "US", "example": "US" }, "description": "TikTok Shop storefront region (US, GB, ID, MY, TH, VN, PH, SG)." }
        ],
        "responses": {
          "200": { "description": "Complete TikTok Shop product object with shop metrics, SKU variants, and top buyer reviews.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TikTokShopProductResponse" } } } }
        }
      }
    },
    "/v1/facebook-marketplace/search": {
      "get": {
        "tags": ["Facebook Marketplace"],
        "operationId": "facebookMarketplaceSearch",
        "summary": "Search Facebook Marketplace Local & Shipping Listings",
        "description": "Search real-time Facebook Marketplace listings by keyword and city/location (supports GET query params and POST JSON body; aliases: /v1/facebook/marketplace/search, /v1/fb-marketplace/search). Returns price, list_price, image, images, date_listed, status, location, delivery, condition, and seller. Cost: 5 Credits / call ($0.50/1K PAYG, $0.20/1K Business; 0 Credits if empty).",
        "x-credits-per-request": "5 Credits / call",
        "x-price-per-request": "$0.20–$0.50 / 1K calls",
        "parameters": [
          { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "example": "couch" }, "description": "Search keyword (aliases: q, keyword)." },
          { "name": "location", "in": "query", "required": false, "schema": { "type": "string", "default": "austin", "example": "austin" }, "description": "City or region name (alias: city)." },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 50 } }
        ],
        "responses": {
          "200": { "description": "Normalized Facebook Marketplace search listings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookMarketplaceSearchResponse" } } } }
        }
      }
    },
    "/v1/facebook-marketplace/item": {
      "get": {
        "tags": ["Facebook Marketplace"],
        "operationId": "facebookMarketplaceItem",
        "summary": "Get Facebook Marketplace Listing Condition, Description & Seller",
        "description": "Fetch full Facebook Marketplace listing details by ID or URL (supports GET query params and POST JSON body; aliases: /v1/facebook-marketplace/listing, /v1/facebook/marketplace/item, /v1/facebook/marketplace/listing). Returns price, list_price, description, condition, location, delivery, seller, images, date_listed, and status. Cost: 5 Credits / call ($0.50/1K PAYG, $0.20/1K Business; 0 Credits on 404).",
        "x-credits-per-request": "5 Credits / call",
        "x-price-per-request": "$0.20–$0.50 / 1K calls",
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "example": "1500578701963217" }, "description": "Facebook Marketplace numeric listing ID or full facebook.com/marketplace/item/... URL (alias: listing_id)." }
        ],
        "responses": {
          "200": { "description": "Normalized Facebook Marketplace listing detail object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FacebookMarketplaceItemResponse" } } } }
        }
      }
    },
    "/v1/health": {
      "get": {
        "tags": ["System & Playground"],
        "operationId": "healthCheck",
        "summary": "Gateway Health Check (0 Credits)",
        "security": [],
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/v1/status": {
      "get": {
        "tags": ["System & Playground"],
        "operationId": "publicStatus",
        "summary": "Live Latency & Uptime Telemetry across all 16 Endpoints (0 Credits)",
        "security": [],
        "responses": { "200": { "description": "Live p50/p95 latency and catalog stats." } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your ShopData API key (`sd_live_...`). Claim 12,000 free credits at https://shopdataapi.com/signup."
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Pass `Authorization: Bearer sd_live_...` or an OAuth 2.1 MCP token (`mcp_at_...`)."
      }
    },
    "schemas": {
      "WholesaleTier": {
        "type": "object",
        "properties": {
          "min_qty": { "type": "integer", "example": 50 },
          "max_qty": { "type": ["integer", "null"], "example": 499 },
          "label": { "type": "string", "example": "50–499 pcs" },
          "unit_price": { "type": "number", "example": 8.5 },
          "currency": { "type": "string", "example": "CNY" },
          "unit_price_usd": { "type": "number", "example": 1.18 }
        }
      },
      "SkuOption": {
        "type": "object",
        "properties": {
          "sku_id": { "type": "string", "example": "B0CRMP3RQT-BLK" },
          "attributes": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "Color": "Obsidian Matte", "Size": "16 oz" } },
          "price": { "type": ["number", "null"], "example": 24.99 },
          "currency": { "type": "string", "example": "USD" },
          "in_stock": { "type": "boolean", "example": true },
          "stock_qty": { "type": ["integer", "null"], "example": 420 },
          "image_url": { "type": ["string", "null"] }
        }
      },
      "ShopProduct": {
        "type": "object",
        "properties": {
          "marketplace": { "type": "string", "enum": ["amazon", "walmart", "etsy", "1688", "taobao", "shopee", "tiktok_shop", "facebook_marketplace"] },
          "item_id": { "type": "string", "example": "B0CRMP3RQT" },
          "asin": { "type": ["string", "null"], "example": "B0CRMP3RQT" },
          "country": { "type": "string", "example": "US" },
          "title": { "type": "string", "example": "OWALA SmoothSip Insulated Stainless Steel Coffee Tumbler, 20 oz" },
          "url": { "type": "string", "example": "https://www.amazon.com/dp/B0CRMP3RQT" },
          "brand": { "type": ["string", "null"], "example": "Owala" },
          "category": { "type": ["string", "null"], "example": "Kitchen & Dining > Travel Mugs" },
          "price": { "type": ["number", "null"], "example": 24.99 },
          "list_price": { "type": ["number", "null"], "example": 29.99 },
          "currency": { "type": "string", "example": "USD" },
          "price_usd": { "type": ["number", "null"], "example": 24.99 },
          "wholesale_tiers": { "type": "array", "items": { "$ref": "#/components/schemas/WholesaleTier" } },
          "moq": { "type": ["integer", "null"], "example": 2 },
          "rating": { "type": ["number", "null"], "example": 4.8 },
          "reviews_count": { "type": "integer", "example": 8420 },
          "sales_volume": { "type": ["string", "null"], "example": "10K+ bought in past month" },
          "monthly_sales_est": { "type": ["integer", "null"], "example": 10000 },
          "is_prime": { "type": "boolean", "example": true },
          "is_best_seller": { "type": "boolean", "example": true },
          "in_stock": { "type": "boolean", "example": true },
          "seller_name": { "type": ["string", "null"], "example": "Amazon.com" },
          "verified_supplier": { "type": "boolean", "example": false },
          "repurchase_rate": { "type": ["string", "null"], "example": "38%" },
          "main_image": { "type": ["string", "null"] },
          "images": { "type": "array", "items": { "type": "string" } },
          "sku_matrix": { "type": "array", "items": { "$ref": "#/components/schemas/SkuOption" } },
          "badges": { "type": "array", "items": { "type": "string" } }
        }
      },
      "ProductListResponse": {
        "type": "object",
        "properties": {
          "code": { "type": "integer", "example": 0 },
          "status": { "type": "string", "example": "ok" },
          "msg": { "type": "string", "example": "success" },
          "meta": { "type": "object", "properties": { "marketplace": { "type": "string" }, "count": { "type": "integer" }, "credits_per_item": { "type": "integer", "example": 2 } } },
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShopProduct" } }
        }
      },
      "ProductDetailResponse": {
        "type": "object",
        "properties": {
          "code": { "type": "integer", "example": 0 },
          "status": { "type": "string", "example": "ok" },
          "msg": { "type": "string", "example": "success" },
          "meta": { "type": "object", "properties": { "marketplace": { "type": "string" }, "credits_cost": { "type": "integer", "example": 10 } } },
          "data": { "$ref": "#/components/schemas/ShopProduct" }
        }
      },
      "ReviewListResponse": {
        "type": "object",
        "properties": {
          "code": { "type": "integer", "example": 0 },
          "status": { "type": "string", "example": "ok" },
          "msg": { "type": "string", "example": "success" },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "review_id": { "type": "string" },
                "rating": { "type": "number", "example": 5 },
                "title": { "type": ["string", "null"] },
                "body": { "type": "string" },
                "author": { "type": "string" },
                "verified_purchase": { "type": "boolean" },
                "reviewed_at": { "type": ["string", "null"] },
                "variant": { "type": ["string", "null"] }
              }
            }
          }
        }
      },
      "TikTokShopProductResponse": {
        "type": "object",
        "properties": {
          "code": { "type": "integer", "example": 0 },
          "status": { "type": "string", "example": "ok" },
          "msg": { "type": "string", "example": "success" },
          "meta": {
            "type": "object",
            "properties": {
              "endpoint": { "type": "string", "example": "/v1/tiktok-shop/product" },
              "credits_cost": { "type": "integer", "example": 3 },
              "credits_charged": { "type": "integer", "example": 3 },
              "cached": { "type": "boolean", "example": true }
            }
          },
          "data": {
            "type": "object",
            "properties": {
              "product_id": { "type": "string", "example": "1730073687428142070" },
              "title": { "type": "string", "example": "Nova Ceramics Travel Mugs - 12oz & 16oz" },
              "price": { "type": "number", "example": 36.39 },
              "list_price": { "type": "number", "example": 36.39 },
              "stock": { "type": "integer", "example": 264198 },
              "sold_count": { "type": "integer", "example": 17084 },
              "rating": { "type": ["number", "null"], "example": 4.7 },
              "rating_count": { "type": "integer", "example": 1656 },
              "shop": {
                "type": "object",
                "properties": {
                  "id": { "type": "string", "example": "7496006028569447414" },
                  "name": { "type": "string", "example": "Nova Ceramics" },
                  "rating": { "type": ["number", "null"], "example": 4.7 },
                  "url": { "type": "string", "example": "https://shop.tiktok.com/us/store/nova-ceramics/7496006028569447414" }
                }
              },
              "variants": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "sku_id": { "type": "string", "example": "1730445685518668790" },
                    "name": { "type": "string", "example": "Lagoon / 12 ounce" },
                    "price": { "type": "number", "example": 36.39 },
                    "list_price": { "type": ["number", "null"], "example": 36.39 },
                    "stock": { "type": "integer", "example": 4035 },
                    "in_stock": { "type": "boolean", "example": true },
                    "image": { "type": ["string", "null"] }
                  }
                }
              },
              "images": { "type": "array", "items": { "type": "string" } },
              "top_reviews": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "review_id": { "type": "string" },
                    "rating": { "type": "number", "example": 5 },
                    "text": { "type": "string" },
                    "author": { "type": "string" },
                    "verified_purchase": { "type": "boolean" }
                  }
                }
              }
            }
          }
        }
      },
      "FacebookMarketplaceListing": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "1500578701963217" },
          "title": { "type": "string", "example": "Beige couch with sleeper topper" },
          "url": { "type": "string", "example": "https://www.facebook.com/marketplace/item/1500578701963217" },
          "price": { "type": ["number", "null"], "example": 350 },
          "list_price": { "type": ["number", "null"], "example": 350 },
          "image": { "type": ["string", "null"] },
          "images": { "type": "array", "items": { "type": "string" } },
          "date_listed": { "type": "string", "example": "2026-11-15T12:00:00.000Z" },
          "status": { "type": "string", "example": "live" },
          "location": { "type": "string", "example": "Austin, TX" },
          "delivery": { "type": "array", "items": { "type": "string" }, "example": ["IN_PERSON"] },
          "description": { "type": "string", "example": "Very comfy three-seat sofa with warm wood legs and sleeper topper." },
          "condition": { "type": "string", "example": "Used – good" },
          "seller": {
            "type": "object",
            "properties": {
              "id": { "type": ["string", "null"] },
              "name": { "type": "string", "example": "Hannah Frankl" },
              "verified": { "type": "boolean", "example": true }
            }
          }
        }
      },
      "FacebookMarketplaceSearchResponse": {
        "type": "object",
        "properties": {
          "code": { "type": "integer", "example": 0 },
          "status": { "type": "string", "example": "ok" },
          "msg": { "type": "string", "example": "success" },
          "meta": {
            "type": "object",
            "properties": {
              "endpoint": { "type": "string", "example": "/v1/facebook-marketplace/search" },
              "credits_cost": { "type": "integer", "example": 5 },
              "credits_charged": { "type": "integer", "example": 5 }
            }
          },
          "data": {
            "type": "object",
            "properties": {
              "query": { "type": "string", "example": "couch" },
              "location": { "type": "string", "example": "austin" },
              "count": { "type": "integer", "example": 20 },
              "items": { "type": "array", "items": { "$ref": "#/components/schemas/FacebookMarketplaceListing" } }
            }
          }
        }
      },
      "FacebookMarketplaceItemResponse": {
        "type": "object",
        "properties": {
          "code": { "type": "integer", "example": 0 },
          "status": { "type": "string", "example": "ok" },
          "msg": { "type": "string", "example": "success" },
          "meta": {
            "type": "object",
            "properties": {
              "endpoint": { "type": "string", "example": "/v1/facebook-marketplace/item" },
              "credits_cost": { "type": "integer", "example": 5 },
              "credits_charged": { "type": "integer", "example": 5 }
            }
          },
          "data": { "$ref": "#/components/schemas/FacebookMarketplaceListing" }
        }
      }
    }
  }
}