Skip to navigation
RESTAdminCatalogProductsImages

Create Product Image

Creates a Product Image.

Required Fields

  • image_file, or
  • image_url

Usage Notes

  • image_url - 255 character limit
  • Content-Type - For image_file, use the multipart/form-data media type. For image_url, use the application/json type. See Adding product images for more information.
  • When you upload an image_file, send description, sort_order, and is_thumbnail as separate form fields in the same multipart/form-data request.
  • You can create only one image at a time. A product can have up to 1000 images.
  • Supported image file types are BMP, GIF, JPEG, PNG, WBMP, XBM, and WEBP.
  • Each image file or image uploaded by URL can be up to 8 MB.

Authentication

X-Auth-Tokenstring

OAuth scopes

UI NamePermissionParameter
Productsmodifystore_v2_products
Productsread-onlystore_v2_products_read_only

Authentication header

HeaderArgumentDescription
X-Auth-Tokenaccess_tokenFor more about API accounts that generate access_tokens, see our Guide to API Accounts.

Further reading

For example requests and more information about authenticating BigCommerce APIs, see Authentication and Example Requests.

For more about BigCommerce OAuth scopes, see our Guide to API Accounts.

For a list of API status codes, see API Status Codes.

Path parameters

product_idintegerRequired

The ID of the Product to which the resource belongs.

store_hashstringRequired
Permanent ID of the BigCommerce store.

Headers

AcceptstringRequiredDefaults to application/json

The MIME type of the response body.

Request

This endpoint expects an object.
descriptionstringOptional
The description for the image.
image_urlstringOptional<=255 characters

The URL for an image displayed on the storefront when the conditions are applied. Limit of 8MB per file.

Cannot be used with image_file.

is_thumbnailbooleanOptional

Flag for identifying whether the image is used as the productʼs thumbnail.

product_idintegerOptional
The unique numeric identifier for the product with which the image is associated.
sort_orderintegerOptional-2147483648-2147483647

The order in which the image will be displayed on the product page. Higher integers give the image a lower priority. When updating, if the image is given a lower priority, all images with a sort_order the same as or greater than the imageʼs new sort_order value will have their sort_orders reordered.

Response

Success
dataobjectOptional
metaobjectOptional
Response metadata.

Errors

400
Bad Request Error
404
Not Found Error
422
Unprocessable Entity Error