CartVisual
Sign inCreate account

Assets & tasks / MERCHANT WORKFLOW

Should You Supply a BigCommerce Variant Image as a File or a Public URL?

BigCommerce's Create Product Variant Image endpoint accepts two distinct input routes: a form-submitted image_file, for which files larger than 1 MB are rejected, or a publicly accessible image_url, for which the documented image limit is 8 MB per file. The URL route supports BMP, GIF, JPEG, PNG, and WebP. Choose the route using the actual image bytes, supported format, hosting access, and authorized variant identity. A public URL is not an unlimited-size alternative to direct upload.

01 / SHOULD YOU SUPPLY A BIGCOMMERCE VARIANT IMAGE AS A FILE OR A PUBLIC URL?

Apply the correct size and input contract

The BigCommerce Create Product Variant Image API accepts either a form post containing image_file or an application/json request containing image_url. The two routes address the same variant-image resource, but their transport and size rules differ.

The direct-file route rejects files larger than 1 MB. The public-URL route requires an accessible image URL, supports BMP, GIF, JPEG, PNG, and WebP, and has an 8 MB per-file limit. These limits must be evaluated separately. A 2.4 MB image may be unsuitable for direct file submission while remaining within the documented URL-side size boundary, provided its format, accessibility, and actual request are valid.

RouteRequestDocumented limitRequired evidence
image_fileForm submission containing image bytesFiles larger than 1 MB rejectedActual file size and correct form encoding
image_urlJSON with public image URL8 MB per image; BMP, GIF, JPEG, PNG, WebPPublic retrieval, supported format, actual image bytes

Do not treat a filename extension as proof of the served media format. A CDN may transform the response, and the API documentation does not guarantee acceptance of every redirect, signed URL, or negotiated representation. Inspect the actual response before submission.

02 / SHOULD YOU SUPPLY A BIGCOMMERCE VARIANT IMAGE AS A FILE OR A PUBLIC URL?

Preserve product and variant identity

The request targets /stores/{store_hash}/v3/catalog/products/{product_id}/variants/{variant_id}/image on the BigCommerce API host. It requires an API credential with the appropriate Products modify permission and the X-Auth-Token header.

BigCommerce documents that only one image can be explicitly associated with a variant. Creating a new variant image overwrites an existing variant-image association. The selected variant can display its assigned image on the storefront. Therefore, route selection is not merely an upload-performance decision: the operator must confirm the exact product and variant before changing a live association.

Record the product ID, variant ID, SKU, approved source revision, current assigned image, and proposed replacement. If the goal is to add another gallery view rather than replace the selected variant image, do not assume this endpoint is the correct resource.

For image_file, submit the approved bytes using the documented form route. For image_url, use a genuine public URL in the JSON body. A local filesystem path is not a public URL, and a private creative-workspace download link is not automatically suitable for server-side retrieval.

The related WooCommerce image-fetch guide

03 / SHOULD YOU SUPPLY A BIGCOMMERCE VARIANT IMAGE AS A FILE OR A PUBLIC URL?

Hypothetical olive-case image decision

Hypothetical CartVisual editorial exercise. No BigCommerce request, file upload, URL fetch, or storefront inspection was performed. Fictional product ID 8500 has variant ID 85002, SKU CASE-OLIVE-M. The approved source photograph is olive-case-master.png, hypothetically 2.4 MB.

The merchant prepares two possible delivery assets. Candidate A is olive-case-api.jpg, hypothetically 820 KB, for the direct-file route. Candidate B is the unchanged 2.4 MB PNG hosted at a proposed public image address. The example address https://assets.example.invalid/olive-case-v2.png is deliberately nonworking and must be replaced with a real accessible URL before any submission.

A third candidate, olive-case-oversize.png, is hypothetically 9.1 MB. It exceeds both the direct-file and documented URL-side limits.

CandidateSizeFile routeURL route
Approved master PNG2.4 MBOver 1 MBWithin 8 MB, subject to real public hosting
JPEG derivative820 KBSize-eligible candidatePotentially eligible if properly hosted
Oversize PNG9.1 MBOver 1 MBOver 8 MB

These are proposed routing decisions, not API acceptance results. The 820 KB derivative still requires a product-detail comparison, especially at the printed label and edge. The 2.4 MB master requires actual public hosting before it can be evaluated through the URL route.

04 / SHOULD YOU SUPPLY A BIGCOMMERCE VARIANT IMAGE AS A FILE OR A PUBLIC URL?

Inspect response status and returned image_url

For the URL route, the conceptual JSON request is {"image_url":"https://YOUR-ACTUAL-PUBLIC-HOST/olive-case-v2.png"}. The host text is a placeholder, not a tested endpoint. The documented successful response contains data.image_url. BigCommerce says that image_url is returned for both file and URL submissions.

Record the actual HTTP response status, error body if present, and returned data.image_url. Do not fill a returned URL with the submitted source URL by assumption; BigCommerce may return its own hosted image address.

If the multipart request fails, check its encoding, image bytes, and 1 MB limit. If the URL request fails, check the 8 MB limit, supported format, anonymous accessibility, and actual response behavior. If authentication fails, correct the API credential and permission scope rather than recompressing the image.

If the request succeeds but the wrong color appears when the variant is selected, inspect the variant ID and the assigned image. The transfer can succeed while the SKU-to-image mapping is wrong. Read back the resource where supported and inspect the actual storefront selection independently.

If the returned image is correct but the general product thumbnail remains unchanged, investigate that separate image resource instead of repeatedly replacing the variant association.

CartVisual, the publisher, can help prepare product-image candidates but does not submit BigCommerce API requests or host guaranteed public variant-image URLs. See the public-media delivery guide before using an externally generated asset as a server-fetchable source.

05 / SHOULD YOU SUPPLY A BIGCOMMERCE VARIANT IMAGE AS A FILE OR A PUBLIC URL?

Use the example with your own product records

The filled records are hypothetical editorial examples. The entry-template row is for your own files, settings and observations; it does not connect to another application.

SKUProduct IDVariant IDCandidateRouteFile formatImage sizeRoute limitAnonymous URL accessActual HTTP statusReturned data.image_urlVariant displayNext action
CASE-OLIVE-M850085002olive-case-master.pngimage_filePNG2.4 MB hypothetical1 MB; exceededNot applicableNot submittedNot returnedNot checkedDo not submit as direct file
CASE-OLIVE-M850085002olive-case-api.jpgimage_fileJPEG820 KB hypothetical1 MB; within size boundaryNot applicableNot submittedNot returnedNot checkedInspect quality and prepare authenticated form request
CASE-OLIVE-M850085002olive-case-master.png at example.invalidimage_urlPNG2.4 MB hypothetical8 MB; within size boundaryNo; fictional placeholderNot submittedNot returnedNot checkedReplace with real public URL and verify served bytes
CASE-OLIVE-M850085002olive-case-oversize.pngimage_urlPNG9.1 MB hypothetical8 MB; exceededNot checkedNot submittedNot returnedNot checkedPrepare a source-faithful derivative within the limit

Download the editable CSV worksheet

06 / SHOULD YOU SUPPLY A BIGCOMMERCE VARIANT IMAGE AS A FILE OR A PUBLIC URL?

What the sources establish

  • BigCommerce Developers — Create Product Variant Image: Primary API documentation for image_file form submission, the 1 MB file-route limit, image_url JSON submission, the 8 MB URL-side image limit, BMP/GIF/JPEG/PNG/WebP support, Products modify authorization, overwrite semantics, and returned data.image_url.
Published by CartVisualPublished Updated Evidence and editorial policy
SOURCES & SCOPE

Sources and further reading

Recorded source-review dates are listed individually below. An undated source does not inherit the article’s publication date. Software and platform rules can change; check the current original before acting.

QUESTIONS, ANSWERED

Frequently asked questions

Can I submit a 2.4 MB image through image_url instead of image_file?

The documented 8 MB URL-side limit permits that size in principle, but the URL must be publicly accessible, serve a supported image format, and pass the actual BigCommerce request. The direct image_file route rejects files larger than 1 MB.

Does a successful response mean the correct product variant is showing the image?

Not by itself. Record the returned data.image_url, verify the intended product and variant IDs, and inspect the selected variant on the storefront. The endpoint can overwrite an existing variant-image association.

YOUR NEXT CAMPAIGN

Create assets from a clear source

Bring your reviewed source photo or brand brief to CartVisual. Check the current tools, account access and credits before generating, then compare every result with your source.

Create a CartVisual account Open the workspace Check access and credits