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

# Images, Videos, and Custom Fields

Plan: Developer Foundations

Lesson 11 of 21 · 30 min

We have created an eCommerce universe where products exist with limitless options and established order through brands and categories. Now, let's bring the products to life through the magic of images, videos, and custom fields.

In this lesson, we'll learn how to add an image to a product, add a video to a product, and add a custom field to a product.

## Product Images

Product images are used to show shoppers what they're buying. When creating an image, image URLs, or an image file can be passed in. Using an image URL does not make the asset a reference to the original, but instead BigCommerce downloads a copy and pushes it out to the CDN.

When dealing with product thumbnails, remember that only one image can be the product thumbnail. The product thumbnail is the image that shows on the category page, in search results, and any other location that features the product. If only one image is on the product it becomes both the thumbnail and the main product image.

### Create a Product Image

```http showLineNumbers={false}
POST /catalog/products/{product_id}/images
```

Creates a product image.

**Required Fields**

* `image_file`
  or
* `image_url`

Only one image at a time can be created. When using file upload, other image file parameters can be updated as well as using `key:value` pairs.
A **GET** request to the same endpoint will return ALL product images for a product.

![Example Request: Create a Product Image](/_fern-files/bigcommerce.docs.buildwithfern.com/2c60ac47c079aa4008bf6e4024008833d4beecf83293a686f963a84ab4c6a085/assets/learn/catalog-rest-api/createImage.png)

![Example Response: Create a Product Image](/_fern-files/bigcommerce.docs.buildwithfern.com/ab1a96635ce89620871787ffb1b347c8407f0c5117e963549be9ea23f88994d4/assets/learn/catalog-rest-api/createImageResponse.png)

### Update a Product Image

```http showLineNumbers={false}
PUT /catalog/products/{product_id}/images/{image_id}
```

Updates a product image.

Use this endpoint to **GET** and/or **DELETE** a Product Image.

## Product Videos

Product Videos help shoppers connect with the product. Products with well-done videos really sell. Like product images, a product can have more than one video; however, remember that product videos must be hosted on YouTube. The video\_id corresponds to the "v" parameter in a YouTube video URL.

### Create a Product Video

```http showLineNumbers={false}
POST /catalog/products/{product_id}/videos
```

Creates a product video.

**Required Fields**

* `video_id` - Example: `https://www.youtube.com/watch?v=R12345677`

Publicly accessible URLs are valid parameters. Videos must be loaded through YouTube at this time.

Use this endpoint to **GET** a list of product videos.

![Example Request: Create a Product Video](/_fern-files/bigcommerce.docs.buildwithfern.com/92bbf557084d7d6e2ecd3cd9b5a160e43c5d239ae9380a1510fb8b120fa689c7/assets/learn/catalog-rest-api/createVideoRequest.png)

![Example Response: Create a Product Video](/_fern-files/bigcommerce.docs.buildwithfern.com/f65246fec96900bd283f0b62c54585572c693c9f6e30becc92dd882a7a153ba7/assets/learn/catalog-rest-api/createVideoResponse.png)

### Update a Product Video

```http showLineNumbers={false}
PUT /catalog/products/{product_id}/videos/{video_id}
```

Updates a product video.

Use this endpoint to **GET** and/or **DELETE** a product video

## Custom Fields

Custom fields are a feature intended for product specifications in a `key:value` arrangement. With them, you can display specifications on the product detail page and on the product listing pages such as category and brand pages. These allow you to specify additional information that will appear on the product's page, such as a book's ISBN or a shirt's fabric.

It is important to remember that in powering faceted search (searching/filtering by custom field values), there is a limit of 250 characters for custom field values.

### Create a Custom Field

```http showLineNumbers={false}
POST /catalog/products/{product_id}/custom-fields
```

Creates a custom field.

Required Fields:

* `name`
* `value`

![Example Request: Create a Custom Field](/_fern-files/bigcommerce.docs.buildwithfern.com/7b10d44deb901088353be49f9d1386303221a3d2d484194ac883b934f341a5b8/assets/learn/catalog-rest-api/createCustomField.png)

![Example Response: Create a Custom Field](/_fern-files/bigcommerce.docs.buildwithfern.com/04ab01b2548f7d3e0430505a0e59d409e41a2c9c6bd1f976e174b04b8b398357/assets/learn/catalog-rest-api/createCustomFieldResponse.png)

> **Info**
>
> It is possible to create multiple custom fields at once by passing in an array.

### Update a Custom Field

```http showLineNumbers={false}
PUT /catalog/products/{product_id}/custom-fields/{custom_field_id}
```

Updates a custom field.

Use this endpoint to **GET** and/or **DELETE** a Custom Field

## Resources

* [Product Images](/developer/api-reference/rest/admin/catalog/products/images/get-product-images)
* [Product Videos](/developer/api-reference/rest/admin/catalog/products/videos)
* [Custom Fields](/developer/api-reference/rest/admin/catalog/products/custom-fields)