commerce_image_upload

Upload one original X00004 product image for a later creation request. This upload does not create a product, attach the image or verify public rendering.

Connected source: This is later than the recorded 145-tool runtime; source registration is 153. Discover the connected endpoint before use. Read the shop connection and authorization rules.

Inputs and configuration

Supply the original PNG, JPEG or GIF bytes as canonical base64, without whitespace or a data-URL prefix. filename is a matching .png/.jpg/.jpeg/.gif basename, 1–240 characters, without a path, URL, colon or control character. The decoded file must contain 1–3,145,727 bytes: strictly less than 3 MiB. The wider generic domain file envelope does not relax the product limit. Container structure is checked; bytes are hashed and preserved without resizing, conversion, pixel decoding or browser rendering. No path, remote URL, object key or prior asset ID is accepted.

The host must explicitly configure PUBL_RESOURCE_GATEWAY_API_ORIGIN, PUBL_UPLOAD_BUCKET and PUBL_UPLOAD_REGION. The exact existing shop/store, selected channel, operator, installation, currency and current delegate policy must also pass the common connection checks. COMMERCE_V2 is a separate configured BCS origin; there is no service/store-creation fallback. The caller supplies no credentials, bucket, region or consumer identity.

Result and recovery

A dry run returns COMMERCE_IMAGE_PLAN with image metadata and writesPerformed:false. It validates bytes/context/storage without requesting a grant, uploading or creating a new journal. It does not produce a completed image reference for creation.

A real call saves prepared → issuing → uploading → done. The selected installation's temporary grant must satisfy the source 200/201 data contract and configured storage binding. One bounded original-byte PUT requires HTTP 200 and the matching SHA-256 checksum acknowledgement. No automatic retry, redirect, arbitrary endpoint or object deletion is used. Credentials and raw bytes are never saved in the task journal; metadata and the acknowledged canonical object receipt are retained.

COMMERCE_IMAGE_UPLOADED supplies taskId, image metadata, phase done and the acknowledged object. verification.byteChecksumAcknowledged is true while attachedToResource, publicReadVerified and renderVerified remain false. Pass only that completed taskId in commerce_creation_get draft.imageTaskIds. The same connection, operator, credential version, selected installation, purpose and storage must still match. Credential refresh can invalidate reuse; there is no silent rebind or refresh-tolerant image promise.

Use taskType commerce-image. Status/resume are observation-only and never request credentials or upload bytes. Only the identical original input can continue prepared work. Issuing/uploading uncertainty remains COMMERCE_IMAGE_PENDING; inspect lastCode and journalPersistence when present. Never reissue a grant/PUT or switch requestId to bypass uncertainty. Completed replays are historical and do not verify current public access.

A fresh acknowledged unattached upload can return the product-creation screen as an explicitly explained parent/handoff destination. It is not a created-product page. Historical, pending and unknown outcomes have no current success link. There is no automatic orphan cleanup or image deletion.

Input example

Replace it with the authorized original file and selected channel. A successful dry run alone cannot satisfy a later imageTaskIds reference.

{
  "channelCode": "selected-channel",
  "pAppCode": "X00004",
  "purpose": "product",
  "requestId": "shop-image-001",
  "file": {
    "filename": "example.png",
    "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aDWQAAAAASUVORK5CYII="
  },
  "dryRun": true
}