_done shopify rank API

openapi: 3.2.0
info:
  title: Shopify AI Rank Checker shopify rank API
  description: Checks how well a Shopify store's products show up when AI shopping assistants such as ChatGPT, Gemini, Perplexity, Grok, and Copilot search for products, and reports the store's rank and its closest competitors. Searches Shopify's real Global Catalog — the same product index AI assistants read from.
  version: 1.0.0
  contact:
    name: _done
    url: https://forms.gle/5KzuSFH7p8hHtDmz7
    email: info@underscoredone.com
  x-openapi-url: https://shopify-ai-rank-checker.underscoredone.com/openapi.json
  x-logo:
    url: https://underscoredone.com/logo.png
    altText: _done
  x-guidance: Call this when a user wants to know how visible their Shopify store is to AI shopping assistants for specific search terms. Provide the store's myshopify.com domain and a list of search keywords. Use 'simple' report_detail for a quick rank check, or 'full' for complete competitor data and a data quality score. Keep keyword lists to 10 or fewer per call for faster responses; split larger lists into multiple calls.
  x-ai-instructions: Call this when a user wants to know how visible their Shopify store is to AI shopping assistants for specific search terms. Provide the store's myshopify.com domain and a list of search keywords. Use 'simple' report_detail for a quick rank check, or 'full' for complete competitor data and a data quality score. Keep keyword lists to 10 or fewer per call for faster responses; split larger lists into multiple calls.
  x-provider: _done — single-purpose utility APIs for developers and AI agents. Pay per call with USDC on Base Mainnet or Solana Mainnet.
  x-pricing:
    model: pay-per-call
    currency: USDC
    network: Base Mainnet or Solana Mainnet
    price: $0.05
  x-keywords:
  - network
  - shopify rank checker
  - ai shopping visibility
  - chatgpt product rank
  - gemini shopping search
  - shopify seo
  - global catalog
  - ucp mcp
  - product rank tracker
  - utility
  - api
  - ai-agent
  - pay-per-call
  - usdc
  - x402
  x-category: shopify rank
  x-provider-url: https://underscoredone.com
  x-agentcash-auth:
    mode: paid
  x-402:
    price: $0.05
    network: eip155:8453
    asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
    pay_to: '0xE9740820225B3918b4ddd1292C7cA4Ca0e2C2F08'
    facilitator: https://api.cdp.coinbase.com/platform/v2/x402
    scheme: exact
    description: Checks how well a Shopify store's products show up when AI shopping assistants such as ChatGPT, Gemini, Perplexity, Grok, and Copilot search for products, and reports the store's rank and its closest competitors. Searches Shopify's real Global Catalog — the same product index AI assistants read from.
    mime_type: application/json
    networks:
    - network: eip155:8453
      asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
      pay_to: '0xE9740820225B3918b4ddd1292C7cA4Ca0e2C2F08'
    - network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
      asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
      pay_to: 8ugAWAXDB8V18kiUrGZTq1oMvU3C6Fxs8hfC6rvzQT3b
servers:
- url: https://shopify-ai-rank-checker.underscoredone.com
  description: Production
tags:
- name: shopify rank
paths:
  /rank:
    post:
      tags:
      - shopify rank
      summary: Finds your Shopify product's rank in the AI shopping catalog for any search keywords.
      description: Look up where a Shopify store's products show up when AI shopping assistants search for the given phrases, and show which competitors rank ahead of it.
      operationId: handler_rank_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
              examples:
                success:
                  summary: Successful response
                  value:
                    api_version: 1.0.0
                    results:
                    - keyword: 7 foot pool table
                      rank: 2
                      urlFound: https://www.legacybilliards.com/products/baylor-ii-7-ft-pool-table-modern
                      top10Results:
                      - https://www.playgosports.com/products/gosports-mid-size
                      - https://www.legacybilliards.com/products/baylor-ii-7-ft-pool-table-modern
        '422':
          description: Unprocessable — a required field is missing or the wrong type. Check the detail field for specifics.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: array
        '402':
          description: Payment required. Send a signed USDC payment on Base Mainnet or Solana Mainnet using the x402 protocol.
          headers:
            X-Payment-Response:
              description: x402 payment challenge — base64-encoded JSON with payment details.
              schema:
                type: string
        '400':
          description: Bad request — your input failed validation or could not be processed. Check the detail field for specifics.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
      x-ai-instructions: Call this when a user wants to know how visible their Shopify store is to AI shopping assistants for specific search terms. Provide the store's myshopify.com domain and a list of search keywords. Use 'simple' report_detail for a quick rank check, or 'full' for complete competitor data and a data quality score. Keep keyword lists to 10 or fewer per call for faster responses; split larger lists into multiple calls.
      x-guidance: Call this when a user wants to know how visible their Shopify store is to AI shopping assistants for specific search terms. Provide the store's myshopify.com domain and a list of search keywords. Use 'simple' report_detail for a quick rank check, or 'full' for complete competitor data and a data quality score. Keep keyword lists to 10 or fewer per call for faster responses; split larger lists into multiple calls.
      x-payment-info:
        price:
          fixed:
            mode: fixed
            currency: USD
            amount: '0.05'
        protocols:
        - x402: {}
components:
  schemas:
    CompetitorEntry:
      properties:
        position:
          type: integer
          title: Position
          description: Where this product sits in the search results, starting at 1.
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
          description: The product's name as shown in the catalog.
        price:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Price
          description: The product's price, if listed.
        productUrl:
          anyOf:
          - type: string
          - type: 'null'
          title: Producturl
          description: The product's web address.
        shopName:
          anyOf:
          - type: string
          - type: 'null'
          title: Shopname
          description: The name of the store selling this product.
        shopDomain:
          anyOf:
          - type: string
          - type: 'null'
          title: Shopdomain
          description: The store's web address.
        rating:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Rating
          description: The product's customer rating, if it has one.
      type: object
      required:
      - position
      title: CompetitorEntry
    Request:
      properties:
        shop_domain:
          type: string
          title: Shop Domain
          description: Your store's web address, for example legacybilliards.com or example-store.myshopify.com. You can paste it with or without https://.
        keywords:
          items:
            type: string
          type: array
          maxItems: 10
          minItems: 1
          title: Keywords
          description: A list of 1 to 10 search phrases you want to check your store's rank for. Split larger lists across multiple calls.
        report_detail:
          type: string
          enum:
          - simple
          - full
          title: Report Detail
          description: Choose 'simple' for a quick rank summary or 'full' for complete competitor and data quality details.
          default: simple
        ships_to_country:
          type: string
          title: Ships To Country
          description: A two-letter country code, such as US or DE, so results reflect what a shopper in that country would see.
          default: US
      type: object
      required:
      - shop_domain
      - keywords
      title: Request
      example:
        keywords:
        - 7 foot pool table
        - shuffleboard table
        report_detail: simple
        ships_to_country: US
        shop_domain: legacybilliards.com
    RankResult:
      properties:
        keyword:
          type: string
          title: Keyword
          description: The search phrase this result is about.
        rank:
          anyOf:
          - type: integer
          - type: 'null'
          title: Rank
          description: Where your product landed in the search results. A blank value means it was not found within the scanned results.
        urlFound:
          anyOf:
          - type: string
          - type: 'null'
          title: Urlfound
          description: The exact web address of your product that showed up in the results, if it was found.
        top10Results:
          items:
            anyOf:
            - type: string
            - type: 'null'
          type: array
          title: Top10Results
          description: The web addresses of the top results shown for this search phrase, including yours if it made the list.
        totalScanned:
          anyOf:
          - type: integer
          - type: 'null'
          title: Totalscanned
          description: How many catalog results were checked for this phrase. Only filled in for the full report.
        matchedTitle:
          anyOf:
          - type: string
          - type: 'null'
          title: Matchedtitle
          description: The name of your product that was found. Only filled in for the full report.
        competitorsBeating:
          anyOf:
          - type: integer
          - type: 'null'
          title: Competitorsbeating
          description: How many other products ranked ahead of yours for this phrase. Only filled in for the full report.
        dataQualityScore:
          anyOf:
          - type: integer
          - type: 'null'
          title: Dataqualityscore
          description: A score from 0 to 100 showing how complete your product listing looks (description, images, options, ratings, categories). Only filled in for the full report when your product is found.
        enrichmentChecks:
          anyOf:
          - additionalProperties:
              type: boolean
            type: object
          - type: 'null'
          title: Enrichmentchecks
          description: A breakdown of which listing details your product has or is missing. Only filled in for the full report when your product is found.
        topCompetitors:
          anyOf:
          - items:
              $ref: '#/components/schemas/CompetitorEntry'
            type: array
          - type: 'null'
          title: Topcompetitors
          description: Details on the top-ranked products for this phrase. Only filled in for the full report.
        notFoundReason:
          anyOf:
          - type: string
          - type: 'null'
          title: Notfoundreason
          description: A plain-English explanation when your product was not found or the check failed.
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Filled in only if the catalog could not be searched for this phrase.
      type: object
      required:
      - keyword
      title: RankResult
    Response:
      properties:
        api_version:
          type: string
          title: Api Version
          description: The version number of this tool.
          default: 1.0.0
        shop_domain:
          type: string
          title: Shop Domain
          description: The store address the results are for, after cleanup.
        ships_to_country:
          type: string
          title: Ships To Country
          description: The shopper country the results reflect.
        results:
          items:
            $ref: '#/components/schemas/RankResult'
          type: array
          title: Results
          description: One result per search phrase you asked about, listed in the same order you provided them.
      type: object
      required:
      - shop_domain
      - ships_to_country
      - results
      title: Response
  securitySchemes:
    siwx:
      type: apiKey
      in: header
      name: SIGN-IN-WITH-X
      description: CAIP-122 wallet signature for repeat access after payment
x-payment-accepts:
- scheme: exact
  network: eip155:8453
  payTo: '0xE9740820225B3918b4ddd1292C7cA4Ca0e2C2F08'
  asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
- scheme: exact
  network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
  payTo: 8ugAWAXDB8V18kiUrGZTq1oMvU3C6Fxs8hfC6rvzQT3b
  asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v