How to search for sellers

In this example we take you through how to search for sellers while using the Operator API

4 minute read

What you’ll learn

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

What is a “Seller”
The difference between “Prospective” and “Retailer” sellers
The difference between sellerSearch and allSellers and when to use
How to write examples of both sellerSearch and all Sellers

What are Sellers?

A Seller is a business entity that either:

Wants to sell on the marketplace (PROSPECTIVE)
Sells on the marketplace (RETAILER)

Typically, prospective sellers are being vetted or onboarded by the marketplace operator so cannot yet participate fully on the marketplace. Sellers tagged as retailers have been onboarded and can sell on the marketplace.

Seller Search Query

The first of the seller queries we’ll look at is: sellerSearch. This query gives you a wide range of search parameters on which to formulate your query. However, this query only returns sellers that are classified as RETAILER.

In addition, sellerSearch also does not return sellers that have:

Unpaid Billings
Been manually taken offline
Been deleted
In some other way been suspended

Summary of Functionality

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

Seller Type	Seller State	Returned from sellerSearch
Prospective	N/a	No
Retailer	Unpaid Billings = True	No
Retailer	Account Suspended = True	No
Retailer	Account Deleted = True	No
Retailer	Account offline = True	No
Retailer	Unpaid Billings = False and Account Suspended = False and Account Deleted = False and Account offline = False	Yes

Example

API Collections

You can find examples of sellerSearch in out API collections that can be found here.

query {
  sellerSearch(
    attributes: { businessName: "acme", updatedSince: "2022-01-01" }
  ) {
    sellers(first: 10, after: null) {
      totalCount
      pageInfo
      {
      	hasNextPage
        endCursor
      }
      nodes {
        id
        businessName
      }
    }
  }
}

This query searches for the first 10 sellers with:

acme in the name
that have been updated since 2025-01-01

An example response payload is shown below:

{
  "data": {
    "sellerSearch": {
      "sellers": {
        "totalCount": 1,
        "pageInfo": {
          "hasNextPage": false,
          "endCursor": "WzIuMTAyNTEyOCwiIl0"
        },
        "nodes": [
          {
            "id": "U2VsbGVyLTU=",
            "businessName": "ACMEE Corp."
          }
        ]
      }
    }
  }
}

When to use

sellerSearch is useful when you only want to work with Sellers that are transacting on your marketplace, perhaps where more granular search criteria is required.

All Sellers Query

The 2nd seller query we’ll look at is allSellers. This query provides only limited search filtering criteria, but in contrast to sellerSearch it returns all seller objects irrespective of state, including (soft) deleted sellers.

Example

An example of the allSellers query is given below:

query {
  allSellers(
    first: 100 
    after: null, 
    updatedSince: "2025-01-01",
    includeDeleted: true
  ) {
    totalCount
    pageInfo
    {
      hasNextPage
      endCursor
    }
    nodes {
      ... on Seller {
        __typename
        id
        businessName
        accountType
        hasUnpaidBillings
        online
      }
      ... on DeletedSeller {
        __typename
        id  
      }
    }
  }
}

This query will return the first 100 Sellers (including deleted):

Updated since 2025-01-01

One thing you’ll note about allSellers is that you need to use a fragment (...) to specify the return of either:

A Seller
A DeletedSeller

Other points to note about DeletedSellers:

They are not included by default, you need to specify: includeDeleted: true in the filter criteria
You can only return a limited number of fields for a DeletedSeller, e.g.:
- id
- legacyId
- updatedAt

An example response payload is shown below:

{
  "data": {
    "allSellers": {
      "totalCount": 10,
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "MjA"
      },
      "nodes": [
        {
          "__typename": "Seller",
          "id": "U2VsbGVyLTE4",
          "businessName": "Wholesale Babe",
          "accountType": "retailer",
          "hasUnpaidBillings": false,
          "online": true
        },
        {
          "__typename": "DeletedSeller",
          "id": "U2VsbGVyLTQ="
        },
        {
          "__typename": "Seller",
          "id": "U2VsbGVyLTE5",
          "businessName": "Patchworks 1",
          "accountType": "retailer",
          "hasUnpaidBillings": true,
          "online": false
        },
        {
          "__typename": "Seller",
          "id": "U2VsbGVyLTU=",
          "businessName": "ACMEE Corp.",
          "accountType": "retailer",
          "hasUnpaidBillings": false,
          "online": true
        },
        {
          "__typename": "Seller",
          "id": "U2VsbGVyLTI=",
          "businessName": "Babies 4U",
          "accountType": "retailer",
          "hasUnpaidBillings": false,
          "online": true
        },
        {
          "__typename": "Seller",
          "id": "U2VsbGVyLTIx",
          "businessName": "Cell Phones 8U",
          "accountType": "retailer",
          "hasUnpaidBillings": false,
          "online": true
        },
        {
          "__typename": "Seller",
          "id": "U2VsbGVyLTM=",
          "businessName": "Ball Bearings 4U",
          "accountType": "retailer",
          "hasUnpaidBillings": false,
          "online": true
        },
        {
          "__typename": "Seller",
          "id": "U2VsbGVyLTY=",
          "businessName": "Shopify Seller",
          "accountType": "retailer",
          "hasUnpaidBillings": false,
          "online": true
        },
        {
          "__typename": "Seller",
          "id": "U2VsbGVyLTIy",
          "businessName": "ACMEE Corp. 5",
          "accountType": "prospective",
          "hasUnpaidBillings": false,
          "online": false
        },
        {
          "__typename": "DeletedSeller",
          "id": "U2VsbGVyLTIw"
        }
      ]
    }
  }
}

When to use

allSellers is useful when you need to work with every seller entity in Marketplacer, e.g. perhaps when you’re synching seller data from Marketplacer to a 3rd party system.