Media

List the account's READY files with the library's filters: search (filename, tags, alt text), tags (any of), usage "unused", the structured filter, store presence, sort (master fields or created_at/updated_at), and paging. Each row carries the file's facts as attributes (Filename, Content Type, Width, Height, Byte Size, Media Type, Media Status), where it is used (usage_count), and a thumbnail; with channel_id also its version on that store (Alt Text, Shopify Media GID). A file still uploading (Media Status pending) is not listed — read it with get_media_v1.

Get one file's shared record: its facts as attributes (Filename, Content Type, Width, Height, Byte Size, Media Type, Media Status — "pending" while uploading, "ready" once confirmed — Tags, Preview Only for files that live in Shopify), its publish state, and a full-resolution thumbnail URL. Per-store alt text and Shopify media ids live on its store versions (get_master_with_projections_v1). Edit Filename or Tags with update_master_attributes_v1 and Alt Text with update_projection_attributes_v1; storage keys are write-protected.

List the entities a file is attached to: across every store (distinct products, collections, and articles — a variant's attachment counts for its product), or on one store with channel_id (each attachment's link id, whether it still awaits publish, and variants as their own rows).

Retrieve a ready JPEG, PNG, or WebP image's original bytes (returned as image content) so it can be inspected or edited externally, then replaced through the replacement tools. Files still uploading, GIFs, videos, and files that live in Shopify are refused. Images over the attachment budget (8 MiB) cannot be returned.

• Extended timeout. 120 s per call — the operation runs server-side orchestration or a live Shopify read.

Before renaming a file, check the sanitized filename the publish would send, which stores already hold a different file under that name (Shopify requires unique filenames per store — read live), and the nearest free variant when there is a conflict.

• Live Shopify read. Slower than PIM reads and can fail when Shopify is unavailable.

Step 1 of uploading a new file: declare its filename, content type (JPEG, PNG, GIF, WebP, MP4, QuickTime) and size (at most 20 MiB) and get back the new file id plus a short-lived upload URL. The bytes must then be PUT to that URL with the same Content-Type and Content-Length, and the upload finished with confirm_media_upload_v1. Until confirmed the file is not ready and not listed.

• Drafts only. Changes land in Peak PIM; nothing reaches Shopify until a publish.

Step 2 of uploading: after the bytes were PUT to the upload URL, verify them server-side (type, size, dimensions are read from the object itself) and mark the file ready. width/height are advisory, used only when the server cannot measure (videos). The file is then browsable and attachable; it reaches Shopify when an entity it is attached to publishes.

• Drafts only. Changes land in Peak PIM; nothing reaches Shopify until a publish.

Create an authored relationship link between two per-store versions on the same store: attach an existing file to a product, variant, collection, or article version (target = the file's version on that store), or attach a product to a catalog. position -1 appends after the last link; a non-negative position is stored as given. Collection → product pairs are refused (membership comes from the collection's sources). The link awaits the source entity's next publish.

• Drafts only. Changes land in Peak PIM; nothing reaches Shopify until a publish.

Rewrite one authored link: its position (to reorder a gallery — every link's position is stored as given, sibling positions are not shifted) and/or its endpoints (to move a file onto another entity version, or swap which file a slot holds). All three fields are written as a whole; read the link first and resend the endpoints you keep. The entity's publish then reconciles the change.

• Drafts only. Changes land in Peak PIM; nothing reaches Shopify until a publish.

Step 1 of replacing a ready image's bytes (JPEG, PNG, GIF, WebP only; files that live in Shopify cannot be replaced): declare the new filename, content type and size, and the file's current draft_revision as base_revision (a stale revision answers 409 — reload the file). Returns a replacement session (1 hour) and an upload URL the new bytes must be PUT to; then commit_media_replacement_v1 or cancel_media_replacement_v1. Pass the same idempotency_key to the commit so a retried commit replays instead of erroring.

• Reaches your stores. Annotated open-world and destructive; the in-app assistant always asks for confirmation before running it.

Step 2 of replacing a file: after the new bytes were PUT to the session's upload URL, verify them, make them the file's canonical bytes in the PIM, and ENQUEUE the background publish that sends the replacement to every store the file is on (its owners are re-published). The result carries the updated file and the accepted operation — poll get_publish_operation_v1 and read per-store outcomes with get_publish_failures_v1. The commit is never rolled back on a store failure: failed stores stay pending and retry on their next publish.

• Extended timeout. 120 s per call — the operation runs server-side orchestration or a live Shopify read.
• Reaches your stores. Annotated open-world and destructive; the in-app assistant always asks for confirmation before running it.

Discard a staged replacement session so its uploaded bytes are never committed. Always succeeds, including for a session that already expired.

• Reaches your stores. Annotated open-world and destructive; the in-app assistant always asks for confirmation before running it.