How to work with Catalog Rules

In this article we take you through how Catalog Rules work and work with the API calls that can be used to automate the workflow.

3 minute read

What you’ll learn

The high-level Catalog Rules flow
- Including where Catalog Rules sit in the overall product creation flow

What are Adverts?

In short, “Adverts” in Marketplacer are Products - it’s that simple!

So whenever we refer to Adverts we are simply referring to Products. In this article (and elsewhere on the docs site) we may use the terms Product and Advert interchangeably.

Advert will typically be used in relation to technical and API discussions (as that is the term used in these domains), whereas business and process focused conversations will most usually use the term Product.

The Product Creation Flow

Before looking at Catalog Rules in detail, it’s worth understanding where Catalog Rules sit in the overall context of product creation:

End to end product flow

These steps can be summarized as follows:

Step	Optional	Purpose
Create product via API	No	Mandatory step in creating products. Can be used in isolation of all other concepts.
Catalog Rules	Yes	Used to specify one or more rules that can be checked automatically by Marketplacer to determine if a product is valid, (e.g. Length of product description, number of images etc.)
Product Vetting	Yes	The “final” stage in approving a product for sale. Vetting will involve looking at elements of a product that are not covered by Catalog Rules.

We will focus on Catalog Rules in the remainder of this article, for a more general end to end overview of product creation, please refer to the Product Creation Primer.

The Catalog Rules Flow

The Concept

An operator can create catalog rules to automate validation checks for seller’s product data prior to operator review (vetting).

These catalog rules are checked when a product is saved.

Products and variants can still be saved, but they cannot progress to operator vetting until the product and at least one published variant passes these checks.

This ensures

Sellers get feedback quickly for any product that does not meet the validation checks.
Operators are only vetting products that are known to meet the validation checks, which reduces the vetting workload for operators.

APIs

Graphql changes include the following:

Query all catalog rules (operator or seller)
Query catalog rule errors on the advert type (operator or seller)
Query catalog rule errors on the variant type (operator or seller)

Worked Examples

The full advert creation process is described here, please refer to this for more detail.

Query Catalog Rules

query ( 
  $first: Int,
  $after: String,){

  catalogRules (
    first: $first,
    after: $after,){
    nodes {
      id
      key
      operator
      errorMessage
    }
    totalCount
    pageInfo {
      hasPreviousPage
      hasNextPage
      endCursor
      startCursor
    }
  }
}

query($id: ID!) {
  node(id: $id) {
    ... on Advert {
      catalogRulesErrors { fieldName errorMessage objectId }
    }
  }
}

Query Catalog Rules for a Variant Type

query($id: ID!) {
  node(id: $id) {
    ... on Variant {
      catalogRulesErrors { fieldName errorMessage objectId }
    }
  }
}