How to search for sellers

What you’ll learn

In this article we explain how you can use the sellerSearch GraphQL query to search for Sellers on the marketplace, specifically you’ll learn:

• What is a “Seller”
• The conditions under which sellerSearch will return Sellers
• Query examples to get the most out of searching for Sellers

Overview

The sellerSearch query can be used to (not surprisingly!) return Seller objects from the Marketplacer GraphQL API. There are however some nuances to consider when working with this query which we will expand upon in this article. At a summary level however, sellerSearch will only return:

• On-boarded, “active” Sellers (i.e. those that can transact on the marketplace)
• Sellers that are not: deleted, off-line/disabled, have unpaid billings etc.

We explain this in further detail below.

What are Sellers?

In the context of this article, a Seller is a business entity that is allowed to transact (i.e. sell stuff) on the marketplace. They will most usually have gone through some form of on-boarding exercise with the Marketplacer operator to ensure they have been set up correctly.

The reason we qualify that here is that there are other types of Seller Account that can exist on Marketplacer:

• Prospective Sellers
• Private Sellers

Prospective Sellers

Prospective Sellers are business entities that have been identified as candidate sellers on the marketplace (either self-nominated via an expression of interest, or identified by the operator).

Prospective Sellers:

• Cannot transact on the marketplace
• Are not returned by the sellerSearch query

Private Sellers

Private Sellers are individual Marketplacer user-accounts. These typically only exist when:

• You are using the Marketplacer Front end (aka the “Full Stack” solution), and
• Users have signed up for a user account

Private Seller accounts will not usually exist when operating a Connected or Headless integration, they are also not returned by sellerSearch.

You can see the distinction between these types of Seller by:

• Logging into the Operator / Admin Portal
• Selecting Members -> Manage Sellers
• Selecting the “Account Type” in the Search Form:

Again for the purposes of this article, (and the sellerSearch query in particular), we are only talking about “Account Types” with the classification of Seller.

Other Considerations

In addition to only returning “Sellers”, there are other things to consider when working with sellerSearch, for example Sellers that have any of the following conditions or settings will not be returned by sellerSearch:

• Sellers that have “unpaid billings”
• Sellers that have been manually taken off-line
• Sellers that have been deleted
• Sellers that have in some other way been suspended

In short, if a Seller is (for whatever reason) not allowed to transact on the Marketplacer, they will not be returned by sellerSearch. Or to put it another way, only currently active Sellers on the marketplace will be returned.

Summary of sellerSearch Functionality

The following table summarizes the conditions under which Seller objects will be returned from sellerSearch:

Seller Search Examples

Full discussion on querying with GraphQL is outside the scope of this article, there are some good learning resources on the official GraphQL site if you’ve not worked with GraphQL before.

This section just provides some example sellerSearch queries that you may find useful.

Example 1: Simple Query

This query returns the id and businessName of the first 24 Sellers on the marketplace. 24 is the default page size for sellerSearch and will be used if no page size is specified.

query{
  sellerSearch{
    sellers{
      edges{
        node{
          id
          businessName
        }
      }
    }
  }
}    

Example 2: Specify a page size of 100

This query deals with concepts around pagination, for a full explanation of how this works, please refer to this how to article. In this example we specify a page size of 100, with a view to paging forward through our result set.

query{
  sellerSearch{
    sellers(first: 100){
      edges{
        node{
          id
          businessName
        }
      }
      totalCount
      pageInfo{
        endCursor
        hasNextPage
      }
    }
  }
}

Example 3: Search for Sellers based on Business Name

Search for all Sellers with a businessName that contains the value acme.

query{
  sellerSearch(attributes: {businessName: "acme"}){
   sellers{
     edges{
       node{
         id
         businessName
        }
      }
    }
  }
}  

Example 4: Search for Sellers based on multiple criteria

When using multiple criteria, the logical AND operator is used.

query{
  sellerSearch(attributes: {
    businessName: "acme"
    onlineOnly: false
    updatedSince: "2022-01-01"
  }){
    sellers{
      edges{
        node{
          id
          businessName
        }
      }
    }
  }
}