# What Is a Catalog API in Shopify and BigCommerce?

> What an online store's catalog API is, how it separates reading from writing in Shopify and BigCommerce, and the minimum permissions to give each app.

URL: https://clione.ai/glossary/catalog-api/
Lang: en

"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](/glossary/product-page/) 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.[^bc-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`.[^bc-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**.[^bc-update-products]

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](/glossary/shopify-metafields/). What it does not do is change variants, which have their own operation, `productVariantsBulkUpdate`.[^shopify-productupdate]

## 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.[^shopify-scopes] `productUpdate` requires `write_products`.[^shopify-productupdate] In BigCommerce, reading the catalog is `store_v2_products_read_only` and modifying it is `store_v2_products`.[^bc-update-products]

| What the app does                                                             | BigCommerce                   | Shopify          |
| ----------------------------------------------------------------------------- | ----------------------------- | ---------------- |
| Read titles, descriptions and SEO fields                                      | `store_v2_products_read_only` | `read_products`  |
| Change the description or the [meta description](/glossary/meta-description/) | `store_v2_products`           | `write_products` |

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:[^bc-update-products]

```http
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:[^shopify-productupdate]

```graphql
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.[^shopify-productupdate] 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.


**A successful API response says the data is stored, not that the [product page](/glossary/product-page/) shows it.** The API writes to the platform; what appears on the page is decided by the theme or the frontend that reads that data. And two permission mix-ups that keep recurring: giving write access to an app that only needs to read, when Shopify recommends requesting only what is needed,[^shopify-scopes] and expecting `productUpdate` to change variants too, when they have their own operation.[^shopify-productupdate]


## 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.[^shopify-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](/glossary/pim/) also edits, decide who rules each field**, or the last to write wins and the other loses their change: that is [field overwrite](/glossary/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.[^bc-update-products]

## Related concept: product feed

A [product feed](/glossary/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](/glossary/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.[^gmc-spec] **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](/glossary/webhook/): Shopify presents it as the alternative to polling the API over and over.[^shopify-webhooks]

To go further, the study [from stored data to published data](/studies/stored-vs-published-data/) measures the distance between what the API accepts and what shows on the product page, and the [publishing by platform reading path](/learn/publishing-by-platform/) orders the rest of the terms.