> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Lab - Product FAQ Project Setup

Plan: Composable Developer

Lesson 11 of 19 · 30 min

In this multi-part lab exercise, you're going to practice customizing your Catalyst storefront with a simple feature on the product detail page.

As you build out your own customizations with Catalyst, you'll have a chance to explore its approach to GraphQL workflows and the built-in toolsets that empower you to build quickly and efficiently.

**Prerequisites**

For all labs ahead, you will need the following.

* A Catalyst storefront and local project, as provisioned in the previous setup lab
* [Postman](https://www.postman.com/) or a similar API client
* An IDE or code editor, like [VS Code](https://code.visualstudio.com/)
* Node.js 24 or later
* The [pnpm](https://pnpm.io/installation) package manager
* Basic understanding of [React](https://react.dev/) and [Next.js](https://nextjs.org/)

**In this lab, you will:**

* Set up the prerequisite metafield data required by the Product FAQs feature

## The Project - Product Frequently Asked Questions

In these exercises, you'll be progressively building a Frequently Asked Questions (FAQ). Such a feature would provide a systematic way to present customers with the answers to frequently asked questions on a product-by-product basis - functionality that's particularly useful for highly custom or highly technical products.

Using **metafields**, you'll attach FAQ records to a product, then utilize custom GraphQL and built-in components to present them on the product detail page in an unobtrusive way.

![Product FAQs in action](/_fern-files/bigcommerce.docs.buildwithfern.com/fc443531a246ac29263a70dac8c04d8dce256c49125431c2e58257eb675e5481/assets/learn/catalyst-core/product-faqs.png)

## Step 1: Set Up Environment and Collection

[Metafields](/developer/api-reference/rest/admin/catalog/products/metafields) are custom key/value pairs that can be assigned to various entities in BigCommerce, including products, allowing you a free-form method to express any arbitrary data that doesn't fit into the schema of BigCommerce's native fields. You'll be inserting metafields to represent "frequently asked question" (FAQ) records on a product.

Adding or updating metafields requires the use of the BigCommerce REST Management API, so you'll be utilizing Postman in this section to build the appropriate requests. In a real-world scenario in which non-technical users need the ability to edit these FAQs, you would likely develop a small companion app to manage them, or else install an app from the BigCommerce marketplace to enable a UI interface for metafields in general.

Each metafield has an assigned **namespace**, and when querying such fields using the GraphQL Storefront API, a namespace argument must be specified. You'll create separate metafields for each FAQ, but all with a common namespace for a given locale (for example, "FAQ|en"). The string value of each metafield will be a JSON representation of a question and its answer.

For this section of the project setup, you'll be using **Postman**.

1. In your BigCommerce store control panel, **create** a new "V2/V3 API token" account in Settings > "Store-level API accounts" with the following scopes.

| Scope    | Permission |
| -------- | ---------- |
| Products | modify     |

2. Securely **store** the access token for your API account.
3. **Create** a new Postman environment with the following variables.

| Variable Name | Value                                                  |
| ------------- | ------------------------------------------------------ |
| `v3_token`    | The access token of your store-level V2/V3 API account |
| `store_hash`  | Your store hash                                        |

4. **Create** a Postman collection and give it an appropriate name, such as "Catalyst Product FAQs".

## Step 2: Create Metafield Request

1. **Choose** a product that is available on your Catalyst storefront and **record** its numerical ID. This can be found in the URL of your control panel when editing the product, where the URL path is in the pattern `/products/edit/{id}`.
2. **Create** a new "Create FAQ Metafield" HTTP request and save it to your collection. The request requires the following details.

| Method        | POST                                                                                           |
| ------------- | ---------------------------------------------------------------------------------------------- |
| URL           | `https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products/:product_id/metafields` |
| Authorization | No Auth                                                                                        |

3. In the Headers tab, use the Presets drop-down to **Manage Presets**, then **Add** a header preset with the following values, saving it with a name like "BC REST".

| Header       | Value            |
| ------------ | ---------------- |
| Accept       | application/json |
| Content-Type | application/json |
| X-Auth-Token | `{{v3_token}}`   |

Note the `:product_id` identifier in the URL path, which refers to a Path Variable defined on this request, rather than an environment or collection variable.

4. **Select** your newly created header preset to populate headers.
5. In the Params tab, **create** the Path Variable `product_id` (note there is no ":" in this context) with your product ID as the value.
6. In the Body tab, **Select** "raw" as the body type and "JSON" from the list of formats. **Enter** the following body. Feel free to change the details of the `key` and the "question" and "answer" values, but take care to preserve the escaped JSON format. If the default locale in your storefront is not "en", update the "namespace" value accordingly.

```json showLineNumbers={false}
{
    "key": "ship-time",
    "value": "{ \"question\": \"How quickly does this product ship?\", \"answer\": \"The product ships within 2 days.\" }",
    "namespace": "FAQ|en",
    "permission_set": "read_and_sf_access"
}
```

7. In the Tests tab, **add** the following code.

```js showLineNumbers={false}
pm.test("Response is not an error", () => {
    pm.response.to.not.be.error;
    pm.response.to.not.have.jsonBody("errors");
});
pm.test("Response is JSON with data", () => {
    pm.response.to.have.jsonBody("data");
});
pm.test("Response includes a metafield ID", () => {
    pm.expect(pm.response.json().data?.id).to.be.a("number");
});
```

8. **Send** the request and **verify** that all tests pass.
9. **Change** the Body of the request to the following, or any key/question/answer you choose, for a second FAQ:

```json showLineNumbers={false}
{
    "key": "colors-sizes",
    "value": "{ \"question\": \"Is this available in other colors or sizes?\", \"answer\": \"This product is available only as depicted.\" }",
    "namespace": "FAQ|en",
    "permission_set": "read_and_sf_access"
}
```

10. **Send** the request and **verify** that all tests pass.
11. **Change** the Body of the request to the following, or any key/question/answer you choose, for a third FAQ:

```json showLineNumbers={false}
{
    "key": "return-opened",
    "value": "{ \"question\": \"Can this product be returned if opened?\", \"answer\": \"Unfortunately, all sales are final if this product is opened.\" }",
    "namespace": "FAQ|en",
    "permission_set": "read_and_sf_access"
}
```

12. **Send** the request and **verify** that all tests pass.

You may, of course, choose to create more FAQ metafields on your chosen product, and/or to create them on other products. The following exercises will require only that you have at least three FAQs on at least one product.

13. **Repeat** the above steps for any other locales you wish to support in your storefront. (For example, if the "fr" locale is supported in your storefront, repeat each metafield request with the "namespace" value "FAQ|fr".)

## Step 3: Get FAQ Metafields

Your product should now have the required data for the following exercises. If you'd like to verify the FAQ fields that now exist on the product, follow these steps to set up a "Get FAQ Metafields" request.

1. **Create** a new "Get FAQ Metafields" HTTP request and **save** it to your existing collection. The request requires the following details.

| Method        | GET                                                                                            |
| ------------- | ---------------------------------------------------------------------------------------------- |
| URL           | `https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/products/:product_id/metafields` |
| Authorization | No Auth                                                                                        |
| Headers       | Utilize your "BC REST" headers preset from the Presets drop-down                               |

2. In the Params tab, **create** the Query Param `namespace` with the value you want to filter on, such as "FAQ|en".
3. Also in the Params tab, **create** the Path Variable `product_id` with your product ID as the value.
4. **Send** the request and **observe** the response.

With the appropriate metafields now created on at least one product, you're now set to begin customizing your Catalyst storefront to include FAQs.

## Resources

* [Metafields](/developer/api-reference/rest/admin/catalog/products/metafields)