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.
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.
| Route | Request | Documented limit | Required evidence |
|---|---|---|---|
| image_file | Form submission containing image bytes | Files larger than 1 MB rejected | Actual file size and correct form encoding |
| image_url | JSON with public image URL | 8 MB per image; BMP, GIF, JPEG, PNG, WebP | Public 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.
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
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.
| Candidate | Size | File route | URL route |
|---|---|---|---|
| Approved master PNG | 2.4 MB | Over 1 MB | Within 8 MB, subject to real public hosting |
| JPEG derivative | 820 KB | Size-eligible candidate | Potentially eligible if properly hosted |
| Oversize PNG | 9.1 MB | Over 1 MB | Over 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.
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.
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.
| SKU | Product ID | Variant ID | Candidate | Route | File format | Image size | Route limit | Anonymous URL access | Actual HTTP status | Returned data.image_url | Variant display | Next action |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| CASE-OLIVE-M | 8500 | 85002 | olive-case-master.png | image_file | PNG | 2.4 MB hypothetical | 1 MB; exceeded | Not applicable | Not submitted | Not returned | Not checked | Do not submit as direct file |
| CASE-OLIVE-M | 8500 | 85002 | olive-case-api.jpg | image_file | JPEG | 820 KB hypothetical | 1 MB; within size boundary | Not applicable | Not submitted | Not returned | Not checked | Inspect quality and prepare authenticated form request |
| CASE-OLIVE-M | 8500 | 85002 | olive-case-master.png at example.invalid | image_url | PNG | 2.4 MB hypothetical | 8 MB; within size boundary | No; fictional placeholder | Not submitted | Not returned | Not checked | Replace with real public URL and verify served bytes |
| CASE-OLIVE-M | 8500 | 85002 | olive-case-oversize.png | image_url | PNG | 9.1 MB hypothetical | 8 MB; exceeded | Not checked | Not submitted | Not returned | Not checked | Prepare a source-faithful derivative within the limit |
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.
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.
- BigCommerce Developers — Create Product Variant Image · Review date not separately recorded
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