How to query products

What you’ll learn

• The simplified product data model
• The use-case for querying products
• Factors impacting product state
• The different queries you can use to work with products
• Alternatives to querying products

The Advert Data Model

For the purposes of this conversation, (querying products), the key relationships of an Advert are shown below:

The key takeaways from this model are:

• Adverts belong to a Seller
  • Sellers products are unique to them (the Marketplacer product ID will be unique)
• Adverts must have a least 1 variant, but can have more
• Variants have fields such as:
  • SKU
  • Barcode
  • Inventory position (called countOnHand in the Marketplacer APIs)
• It is ultimately the Variant that gets purchased by the customer (not the Advert)

You can explore the Marketplacer object model in more depth by taking a look at GraphQL Voyager

Why Query Products?

There are a number of reasons why you may want to query the 3rd party products hosted on Marketplacer via the Operator API, the most common use-case will usually be so that you can list those products for sale on your own eCommerce platform. This data-flow is part of a standard Connected Integration. A high level overview of the primary data flows for a connected integration are shown below:

While there are other use-cases, e.g. to consume products into an analytics platform to conduct further analysis, it is the Connected Integration use-case we’ll focus on in this article.

Advert State

Before discussing the advert queries, it’s important to cover the following fields on the Advert object as their values can impact both the “state” of the advert, and therefore the queries can be used to retrieve those adverts:

As you will appreciate, the values for these fields can have a number of different combinations, impacting the overall “state” of the Advert. A summary of this is provided below:

To summarize the above table, only when all 3 fields are true, can the Advert be said to be available for purchase. Adverts in this “state” are usually referred to as either online or published.

For the remainder of this article we’ll use the terms Published and Unpublished.

The Advert Queries

There are 3 Advert queries that can be employed via the Operator API, they each have different characteristics which we will discuss in each section.

advertsWhere

• Object Types Returned:
  • Advert
• Advert States Returned:
  [x] Published
  [x] Unpublished
  [x] Deleted (When executed as an Operator)

advertsWhere is a good candidate query when considering building a Connected Integration, as it returns: Published, Unpublished and Deleted Adverts, using a wide variety of filter criteria. Indeed if no filter criteria is supplied to advertsWhere it will return an empty set. An example query is provided below:

query {
  advertsWhere(retailerIds: ["U2VsbGVyLTE2NQ=="]) 
  {
	nodes {
      id
      legacyId
      title
      published
      online
      displayable
      variants {
        nodes {
          id
          label
          buyable
          published
          displayable
          countOnHand
        }
      }
    }
  }
}

The advertsWhere query returns all Adverts (irrespective of state) as Advert objects. While this allows you to distinguish Published Adverts (all 3 status fields are true), you cannot distinguish between Unpublished and Deleted Adverts using this query.

allAdverts

• Object Types Returned:
  • Advert
  • UnpublishedAdvert
  • DeletedAdvert
• Advert States Returned:
  [x] Published
  [x] Unpublished
  [x] Deleted

allAdverts is another potential choice when building a Connected Integration, however it has reduced set of filter criteria:

• updatedSince: Last time the Adverts were updated
• vetted: whether the Advert has been vetted
• requiresVetting: whether the Advert needs to go through the vetting process

In another difference with advertsWhere, instead of returning an Advert object representing Published, Unpublished and Deleted Adverts, allAdverts returns concrete types representing the different states that an Advert can have:

• Advert - representing Published Adverts
• UnpublishedAdverts - representing Unpublished Adverts
• DeletedAdvert - representing Deleted Adverts

An example query is provided below:

query {
	allAdverts(
		first: 1000, 
		updatedSince: "2023-05-29") {
		nodes {
			__typename
			... on Advert {
				legacyId
				updatedAt
				title
				seller {
					businessName
				}
			}
			... on UnpublishedAdvert {
				legacyId
				updatedAt
				details {
					title
					seller {
						businessName
					}
				}
			}
			... on DeletedAdvert {
				legacyId
				id
				updatedAt
			}
		}
	}
}

advertSearch

• Object Types Returned:

  • Advert

• Advert States Returned:
  [x] Published
  [ ] Unpublished
  [ ] Deleted

  advertSearch was not developed to support the Connected Integration use-case, and therefore we don’t recommend it when building such an integration.

  The primary use-case of advertSearch to be called directly by a frontend eCommerce web application, in providing Product Search functionality directly to end users. It was not designed for system to system integrations.

  advertSearch has the following characteristics:

  • Optimized for User Interactivity, e.g. someone performing a Product Search
  • Returns only Published products (you would not want to return products directly to the user that could not be purchased)
  • Has a large set of filter criteria, to support interactive product search

  An example query is provided below:

query {
	advertSearch(attributes: 
		{ 
			keywordQuery: "shoes"
			brandIds: ["QnJhbmQtNA=="]
		}) {
		adverts(first: 500) {
			totalCount
			nodes {
				id
				featureOptionValues {
					nodes {
						id
						displayName
						optionType {
							category
						}
					}
				}
				productDetails {
					key
					value
				}
				variants {
					nodes {
						administrativeBodyWarning
					}
				}
			}
		}
	}
}

Alternatives to Querying

In terms of moving Product data from Marketplacer into your domain (via a Connected Integration), you can use Webhooks instead. In contrast to an API based approach, where the Connected Integration “pulls” data at regular intervals, Webhooks push product (and other types of data) to the Connected Integration any time Create, Update or Delete events occur on Products. This allows for the near realtime movement of Product data to your integration.

• You can read more about Marketplacer webhooks here.
• You can read more about your integration options here.