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

# Look up merchants

> Searches the merchants a program can allow: Visa merchants for a `hoppier_card` program, gift-card brands for a `gift_card` program. Send the ids you choose as `merchantIds` when you [create a program](/api-reference/programs/create).

The key's owner must be an admin of the company.


* **The catalogue** is the dashboard's merchant picker: Hoppier's merchants plus your company's own custom ones. Another company's custom merchants never appear, and a program can't use them.
* **Wildcards.** A merchant with `wildcard: true` stands for a whole category, such as local restaurants. With no `query`, Visa results start with them.
* **Paging.** Results are ranked by how well they match `query`, so pages go by position: ask again with `offset` raised by `limit` while `hasMore` is `true`. `offset` goes up to 1000; search for something narrower to reach further.
* **Gift-card values.** `giftCard.minAmount` and `maxAmount` are in hundredths of the brand's own currency (cents for USD). `currencies` lists the currencies the brand comes in.
* **Merchant ids are numbers**, unlike the other ids in the API.
* **Not verified for Visa cards?** Your account's programs are `gift_card` programs, so look up `gift_card` merchants.


## OpenAPI

````yaml /openapi.yaml get /merchants
openapi: 3.1.0
info:
  title: Hoppier API
  version: 1.0.0-beta
  summary: Create and read your Hoppier programs, and add and list the people in them.
  description: >
    The Hoppier API is in **closed beta**. Everything in this reference runs in
    production today.


    - A full-access admin creates company API keys in the dashboard, under
    **Developers › API keys**. For a personal key, email
    [support@hoppier.com](mailto:support@hoppier.com).

    - There is no sandbox. Every key works against your live account.

    - We add fields and error codes without notice, so ignore anything you don't
    recognise. We don't rename or remove a documented field without announcing
    it on the [changelog](https://docs.hoppier.com/changelog) first.
  termsOfService: https://www.hoppier.com/terms
  contact:
    name: Hoppier support
    email: support@hoppier.com
servers:
  - url: https://app.hoppier.com/api/v1
    description: Production
security:
  - apiKey: []
tags:
  - name: Account
    description: Check an API key and see which account it belongs to.
  - name: Addresses
    description: Save and list your company's addresses, for new programs.
  - name: Merchants
    description: Look up the merchants and gift-card brands a program can allow.
  - name: Programs
    description: Read and create the reward programs in your account.
  - name: Participants
    description: Add people to a program and list them.
paths:
  /merchants:
    get:
      tags:
        - Merchants
      summary: Look up merchants
      description: >
        Searches the merchants a program can allow: Visa merchants for a
        `hoppier_card` program, gift-card brands for a `gift_card` program. Send
        the ids you choose as `merchantIds` when you [create a
        program](/api-reference/programs/create).


        The key's owner must be an admin of the company.
      operationId: listMerchants
      parameters:
        - name: programType
          in: query
          required: true
          description: The type of program the merchants are for.
          schema:
            type: string
            enum:
              - hoppier_card
              - gift_card
          example: gift_card
        - name: query
          in: query
          required: false
          description: A merchant's name or a word to search for, such as `coffee`.
          schema:
            type: string
            maxLength: 200
          example: coffee
        - name: country
          in: query
          required: false
          description: >-
            Only merchants available in this country, as a two-letter code such
            as `US`.
          schema:
            type: string
            pattern: ^[A-Za-z]{2}$
          example: US
        - name: limit
          in: query
          required: false
          description: How many merchants to return, from 1 to 50.
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
        - name: offset
          in: query
          required: false
          description: How many results to skip, from 0 to 1000.
          schema:
            type: integer
            minimum: 0
            maximum: 1000
            default: 0
      responses:
        '200':
          description: A page of merchants.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantList'
              example:
                merchants:
                  - id: 3755
                    object: merchant
                    name: Starbucks
                    wildcard: false
                    categories:
                      - Food & Drink
                    countries:
                      - US
                    logoUrl: https://cdn.example.com/merchants/starbucks.png
                    giftCard:
                      minAmount: 500
                      maxAmount: 50000
                      currencies:
                        - USD
                hasMore: true
                totalCount: 13
        '400':
          description: >
            `invalid_request`: `programType` is missing or not one of the two,
            or `limit`, `offset` or `country` isn't allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missingType:
                  summary: No programType
                  value:
                    error: invalid_request
                    message: '"programType" is required'
                limitTooHigh:
                  summary: limit over 50
                  value:
                    error: invalid_request
                    message: '"limit" must be less than or equal to 50'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/NotAdmin'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    MerchantList:
      type: object
      required:
        - merchants
        - hasMore
        - totalCount
      properties:
        merchants:
          type: array
          items:
            $ref: '#/components/schemas/Merchant'
        hasMore:
          type: boolean
          description: >-
            `true` when there are more results: ask again with `offset` raised
            by `limit`.
        totalCount:
          type: integer
          description: How many merchants match, across every page.
          examples:
            - 13
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: >
            A machine-readable code, such as `unauthorized` or
            `program_not_found`. Act on it and the HTTP status. New codes can
            appear, so handle one you don't recognise by its status. [Every
            code](/guides/errors-and-rate-limits#error-codes).
          examples:
            - program_not_found
        message:
          type: string
          description: What went wrong, in plain words. Don't parse it; it can change.
          examples:
            - Program not found.
        parameter:
          type: string
          description: On some `invalid_request` errors, the field that was refused.
          examples:
            - email
    Merchant:
      type: object
      description: A merchant or gift-card brand a program can allow.
      required:
        - id
        - object
        - name
        - wildcard
        - categories
        - countries
      properties:
        id:
          type: integer
          description: The merchant's id, for `merchantIds` when you create a program.
          examples:
            - 3755
        object:
          type: string
          const: merchant
        name:
          type: string
          examples:
            - Starbucks
        wildcard:
          type: boolean
          description: >
            `true` for an entry that stands for a whole category, such as local
            restaurants, rather than one merchant.
        categories:
          type: array
          items:
            type: string
          examples:
            - - Food & Drink
        countries:
          type: array
          items:
            type: string
          description: Two-letter codes of the countries the merchant is available in.
          examples:
            - - US
        logoUrl:
          type: string
          format: uri
          description: The merchant's logo. Left out when there isn't one.
        giftCard:
          type: object
          description: Gift-card brands only.
          required:
            - minAmount
            - maxAmount
            - currencies
          properties:
            minAmount:
              type: integer
              description: >-
                The smallest card value, in hundredths of the brand's currency
                (cents for USD).
              examples:
                - 500
            maxAmount:
              type: integer
              description: >-
                The largest card value, in hundredths of the brand's currency
                (cents for USD).
              examples:
                - 50000
            currencies:
              type: array
              items:
                type: string
              description: The currencies the brand comes in.
              examples:
                - - USD
  responses:
    Unauthorized:
      description: >
        `unauthorized`: the API key is missing or malformed, or it's wrong,
        unknown or switched off.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingKey:
              summary: No API key
              value:
                error: unauthorized
                message: 'API key is missing. Send it as "Authorization: Bearer <key>".'
            invalidKey:
              summary: Malformed, wrong or unknown key
              value:
                error: unauthorized
                message: API key is not valid.
            inactiveKey:
              summary: Key switched off
              value:
                error: unauthorized
                message: API key is inactive.
    NotAdmin:
      description: >
        `insufficient_permission`: the key's owner isn't an admin of the
        company.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: insufficient_permission
            message: This API key's user is not an admin of this account.
    RateLimited:
      description: >
        `rate_limited`: too many requests. Wait the number of seconds in
        `Retry-After`, then retry. See [Errors and rate
        limits](/guides/errors-and-rate-limits#rate-limits).
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            perAccount:
              summary: Per-account limit
              value:
                error: rate_limited
                message: >-
                  Too many requests for this account. Retry after the number of
                  seconds in Retry-After.
            perAddress:
              summary: Per-address limit
              value:
                error: rate_limited
                message: Too Many Requests
    ServerError:
      description: >
        `internal_error`: something went wrong on Hoppier's side. The message
        never contains internal details. Retry with backoff; if it keeps
        happening, email support@hoppier.com.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: internal_error
            message: An unexpected error occurred.
  headers:
    RetryAfter:
      description: Whole seconds to wait before retrying.
      schema:
        type: string
      example: '30'
    RateLimitRemaining:
      description: >-
        Per-address limit only. Requests left in the current 10-second window,
        so `0` on a 429.
      schema:
        type: string
      example: '0'
    RateLimitReset:
      description: >-
        Per-address limit only. When the window refills, as a Unix timestamp in
        seconds.
      schema:
        type: string
      example: '1793491210'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: hk_live.<prefix>.<secret>
      description: >
        Send your key in the `Authorization` header: `Authorization: Bearer
        hk_live.…`. The word `Bearer` is case-sensitive.


        Keys are shown once. Treat them like passwords and never put one in code
        that runs in a browser or an app.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.