What is a catalog API in an online store?

"Catalog API" sounds like something only the technical team deals with, but you see it every time you install an app: it is what sits behind the screen where the app asks permission to view or modify your products. It is not a product file the store exports, or the API your site uses to show the catalog to the shopper. It is the administration door to the catalog, and what an app can do with your product pages is exactly what you let it do through it.

How it works

An ecommerce platform has two kinds of API over the same catalog. The admin ones read and write: they create products, change prices, fill in fields. The storefront ones are made for the shopper. BigCommerce describes them as built for the actions of someone buying in the store: browsing the catalog, logging in, filling the cart and paying. They are limited to the context of a specific shopper, while the admin ones work without that limit.⁠^{[1]BigCommerce Developer Learning. Storefront APIs} When an app of yours needs to change something, it asks for the first kind.

In BigCommerce, the admin one is literally called the Catalog API: it manages products, categories, brands, bulk pricing rules and more, and products live at the path /v3/catalog/products. Among its fields are the ones that matter for SEO: page_title, meta_description, search_keywords and custom_url.⁠^{[2]BigCommerce API Reference. Catalog - Products} To change several products at once, you send a PUT request to that same path with a list of products, each with its id, and each batch accepts at most 10 products.⁠^{[3]BigCommerce API Reference. Update Products (batch)}

Shopify has no "catalog API" by that name: products are read and written with the GraphQL Admin API. The productUpdate operation changes a product's title, description, vendor or media, and it also accepts the SEO fields (seo, with title and description) and metafields. What it does not do is change variants, which have their own operation, productVariantsBulkUpdate.⁠^{[4]Shopify Dev Docs. productUpdate (GraphQL Admin API)}

The permissions

Each app gets in with specific permissions, which on both platforms are called scopes. In Shopify, read_products and write_products give access to products, their variants and collections, among other resources. Two rules from its documentation: a write permission includes reading the same resource, so write is only requested if the app truly needs both, and an app should request only the data it needs to function.⁠^{[5]Shopify Dev Docs. Access scopes} productUpdate requires write_products.⁠^{[4]Shopify Dev Docs. productUpdate (GraphQL Admin API)} In BigCommerce, reading the catalog is store_v2_products_read_only and modifying it is store_v2_products.⁠^{[3]BigCommerce API Reference. Update Products (batch)}

This is the table worth having in front of you when an app shows you its permissions screen. A tool that only reports on your catalog does not need the second row.

In a store

A fictitious example: a tripod store wants to change the meta description of its product 112. In BigCommerce, the request would go to the products path, with a batch of one:⁠^{[3]BigCommerce API Reference. Update Products (batch)}

PUT https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products
Content-Type: application/json

[
  { "id": 112, "meta_description": "Carbon fiber travel tripod for mirrorless cameras." }
]

In Shopify, the same task is a GraphQL mutation on the product, with the seo field:⁠^{[4]Shopify Dev Docs. productUpdate (GraphQL Admin API)}

mutation {
  productUpdate(
    product: {
      id: "gid://shopify/Product/112"
      seo: { description: "Carbon fiber travel tripod for mirrorless cameras." }
    }
  ) {
    product {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Shopify's mutation asks for a userErrors list back, and you have to read it: a response with no network error can carry a rejected change inside it.⁠^{[4]Shopify Dev Docs. productUpdate (GraphQL Admin API)} Clione writes to stores by this same route: it publishes its signals with the platform's own APIs, and only when the merchant clicks Push.

How to check it

1. List the apps with access to your products and, for each one, note whether it has read or write. In Shopify, the permissions each app requests are declared by the app itself.⁠^{[5]Shopify Dev Docs. Access scopes}
2. Compare each permission with what the app does, using the table above. If it only reports, it does not need to write.
3. If an app writes to fields your team or your PIM also edits, decide who rules each field, or the last to write wins and the other loses their change: that is field overwrite.
4. After a change through the API, read the product back with the API itself and open the product page's source code: the first step confirms the data is stored; the second, that it is published.
5. In BigCommerce, split bulk changes into batches of 10 products at most.⁠^{[3]BigCommerce API Reference. Update Products (batch)}

Related concept: product feed

A product feed is the opposite of an administration door: a file with the catalog's data, prepared in the format another channel asks for so that channel can read it. Google Merchant Center, for example, accepts product data in text or XML feeds, or through its own API, and has its specification of how it must arrive.⁠^{[6]Google Merchant Center Help. Product data specification} The catalog API is the source; the feed is a copy that goes out from it to somewhere else. And if what you need is not to ask about changes but for the platform to tell you when they happen, that is a webhook: Shopify presents it as the alternative to polling the API over and over.⁠^{[7]Shopify Dev Docs. About webhooks}

To go further, the study from stored data to published data measures the distance between what the API accepts and what shows on the product page, and the publishing by platform reading path orders the rest of the terms.