> ## Documentation Index
> Fetch the complete documentation index at: https://docs-api.incarts.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Find supported retailers

> Search retailer choices and routing values for shoppable link generation

Use this endpoint before creating Instacart shopping list, recipe, or product detail links when you
need the store-specific routing value.

<Tip>
  Instacart shopping list and recipe links use `retailerId`. Instacart product detail links use the
  retailer slug in `retailer`.
</Tip>


## OpenAPI

````yaml openapi/incarts-public-api.v1.yaml GET /v1/retailers
openapi: 3.1.0
info:
  title: Incarts API
  version: 1.0.0
  summary: Create shoppable links and QR codes with the Incarts API.
  description: >
    Create shoppable Incarts links and QR codes for retailer, campaign, and
    commerce workflows.
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://incarts-api-qob6vapoca-uc.a.run.app
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Health
    description: Service health checks.
  - name: Links
    description: Link generation and retrieval.
  - name: Retailers
    description: Retailer discovery for link generation.
  - name: QR Codes
    description: QR codes associated with shoppable links.
paths:
  /v1/retailers:
    get:
      tags:
        - Retailers
      summary: Find supported retailers
      description: >
        Finds supported retailer choices for shoppable link generation.


        For Instacart links, use `usage.shoppingList.retailerId` or
        `usage.recipe.retailerId`

        with `options.instacart.retailerId`. Use `usage.productDetail.retailer`
        with

        `options.instacart.retailer` for product detail links.
      operationId: listRetailers
      parameters:
        - name: provider
          in: query
          required: true
          description: >-
            Retailer provider to search. Only Instacart discovery is available
            in v1.
          schema:
            $ref: '#/components/schemas/RetailerProvider'
          example: instacart
        - name: query
          in: query
          required: false
          description: Case-insensitive search over retailer name, slug, or retailer id.
          schema:
            type: string
            minLength: 1
            maxLength: 120
          example: target
        - name: limit
          in: query
          required: false
          description: Maximum number of retailers to return.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
          example: 25
        - $ref: '#/components/parameters/CorrelationId'
      responses:
        '200':
          description: Retailers found.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/CorrelationId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetailerListResponse'
              examples:
                instacart:
                  value:
                    data:
                      - provider: instacart
                        name: Target
                        retailerId: '648'
                        slug: target
                        services:
                          - delivery
                          - pickup
                        categories:
                          - grocery
                        locationCount: 184
                        samplePostalCodes:
                          - '10001'
                          - '60601'
                        usage:
                          shoppingList:
                            routingMode: specific
                            retailerId: '648'
                          recipe:
                            routingMode: specific
                            retailerId: '648'
                          productDetail:
                            routingMode: specific
                            retailer: target
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    RetailerProvider:
      type: string
      enum:
        - instacart
    RetailerListResponse:
      type: object
      additionalProperties: false
      required:
        - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/RetailerDirectoryEntry'
    RetailerDirectoryEntry:
      type: object
      additionalProperties: false
      required:
        - provider
        - name
        - locationCount
        - usage
      properties:
        provider:
          $ref: '#/components/schemas/RetailerProvider'
        name:
          type: string
          description: Display name for the retailer.
          example: Target
        retailerId:
          type: string
          description: >-
            Instacart numeric retailer id. Use this with
            `options.instacart.retailerId` for shopping list and recipe links.
          example: '648'
        slug:
          type: string
          description: >-
            Instacart retailer slug. Use this with `options.instacart.retailer`
            for product detail links.
          example: target
        services:
          type: array
          description: Fulfillment services observed across matching locations.
          items:
            type: string
          example:
            - delivery
            - pickup
        categories:
          type: array
          description: Retailer categories observed across matching locations.
          items:
            type: string
          example:
            - grocery
        locationCount:
          type: integer
          minimum: 1
          description: Number of Firestore retailer rows grouped into this retailer choice.
          example: 184
        samplePostalCodes:
          type: array
          description: Small sample of postal codes represented by the grouped locations.
          items:
            type: string
          example:
            - '10001'
            - '60601'
        usage:
          $ref: '#/components/schemas/RetailerDirectoryUsage'
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
    RetailerDirectoryUsage:
      type: object
      additionalProperties: false
      properties:
        shoppingList:
          $ref: '#/components/schemas/InstacartRetailerIdRoutingUsage'
        recipe:
          $ref: '#/components/schemas/InstacartRetailerIdRoutingUsage'
        productDetail:
          $ref: '#/components/schemas/InstacartRetailerSlugRoutingUsage'
    ErrorObject:
      type: object
      additionalProperties: false
      required:
        - code
        - message
        - correlationId
      properties:
        code:
          type: string
          description: Stable machine-readable error code.
          example: validation_failed
        message:
          type: string
          description: Human-readable error summary.
          example: products is required for walmart add_to_cart links.
        correlationId:
          type: string
          example: req_01JZ4TCZ7AG9P9W38V4VNQ7W4B
        details:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
    InstacartRetailerIdRoutingUsage:
      type: object
      additionalProperties: false
      required:
        - routingMode
        - retailerId
      properties:
        routingMode:
          type: string
          enum:
            - specific
        retailerId:
          type: string
          minLength: 1
          example: '648'
    InstacartRetailerSlugRoutingUsage:
      type: object
      additionalProperties: false
      required:
        - routingMode
        - retailer
      properties:
        routingMode:
          type: string
          enum:
            - specific
        retailer:
          type: string
          minLength: 1
          example: target
    ErrorDetail:
      type: object
      additionalProperties: false
      required:
        - field
        - message
      properties:
        field:
          type: string
          example: products
        message:
          type: string
          example: At least one product is required.
  parameters:
    CorrelationId:
      name: X-Correlation-ID
      in: header
      required: false
      description: >-
        Client-supplied request correlation ID. The API echoes this value when
        provided.
      schema:
        type: string
        minLength: 8
        maxLength: 128
      example: req_01JZ4TCZ7AG9P9W38V4VNQ7W4B
  headers:
    CorrelationId:
      description: >-
        Request correlation ID generated by the API or echoed from
        `X-Correlation-ID`.
      schema:
        type: string
      example: req_01JZ4TCZ7AG9P9W38V4VNQ7W4B
  responses:
    BadRequest:
      description: Request body, path, or header is malformed.
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/CorrelationId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: API key is missing or invalid.
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/CorrelationId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: >-
        API key is valid but does not have access to the requested project or
        scope.
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/CorrelationId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: Rate limit exceeded.
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/CorrelationId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Unexpected server error.
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/CorrelationId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Incarts-API-Key

````