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
The roles the Operator and the Seller play in the flow
The APIs and Webhooks that can be used to automate the Catalog Rules

Connected Operators and their sellers can use this functionality. This functionality is not available for Fullstack or in the original Seller Portal.

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 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.

Valid Rules

The rule key and operators are enumerated types, see

CatalogRulesOperatorEnum: https://api.marketplacer.com/graph-doc/catalogruleskeyenum.doc.html
Catalogrulesoperatorenum: https://api.marketplacer.com/graph-doc/catalogrulesoperatorenum.doc.html

Any combination of Operator and Key is valid, though not all combinations make logical sense.

If the operator is PRESENT, don’t provide a value.

For all other operators, the value provided must be an integer encoded as a string.

APIs & Webhooks

Graphql changes include the following:

Create catalog rule (operator only)
Update catalog rule (operator only)
Delete catalog rule (operator only)
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)

Create a Catalog Rule

mutation
catalogRuleCreate($attributes: CatalogRuleInput!)
 {
  catalogRuleCreate(input: { attributes: $attributes })
 {
    catalogRule {
      id
      key
      operator
      value
      errorMessage
    }
    errors {
      field
      messages
    }
  }
}

$attributes = {
  key: 'PRODUCT_DESCRIPTION',
  operator: 'GREATER_THAN',
  value: '50',
  errorMessage: 'Description must be more than 50 characters',

}

Update a Catalog Rule

mutation
catalogRuleCreate($catalogRuleId: ID!, $attributes: CatalogRuleUpdateInput!)
{
  catalogRuleUpdate(input: { catalogRuleId: $catalogRuleId, attributes: $attributes }) {

    catalogRule {
      id
      key
      operator
      value
      errorMessage
    }

    errors {
      field
      messages
    }
  }
}

$catalogRuleId = ID!
$attributes = {
  operator: 'GREATER_THAN',
  value: '50',
  errorMessage: 'Description must be more than 50 characters',
}

Delete a Catalog Rule

mutation
catalogRuleDelete($id: ID!)
{
  catalogRuleDelete(input: { id: $id })
{
    errors {
      field
      messages
    }
  }
}

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 }
    }
  }
}