### add_media

Adds an image to the store's own media library and returns the url it now lives at on the merchant's media host. Supply the image EITHER as url, to download one already published on the web, OR as data, the image's own bytes base64 encoded. Use data for an image you were given directly, such as a design or logo the merchant attached, since that file has no url to fetch. Put the returned url in an `<img src>`. The file's magic bytes decide its type: PNG, JPEG, GIF, WebP and AVIF are accepted; SVG is not. A fetched image may be up to 15 MiB and an inline one up to 2 MiB. Note that this writes to the merchant's storage and counts against their plan's storage allowance.

**Scope:** `write_storefront`


  <ParamField body="data" type="string">
    The image's own bytes, base64 encoded, for an image that is not on the web. Give this or url, never both. Up to 2 MiB once decoded. A "data:image/png;base64,..." prefix is accepted and stripped.
  </ParamField>
  <ParamField body="filename" type="string">
    Optional. A short name for the file, for the merchant's benefit when they browse the library later. The extension is set from the file's real type and anything you write here is ignored. Defaults to the last path segment of the url.
  </ParamField>
  <ParamField body="url" type="string">
    Absolute https url of the image to fetch. Give this or data, never both.
  </ParamField>

### create_media_upload

Starts an upload for a file too large to send inline, by returning a URL and form fields to POST the file straight to storage. Use add_media instead for an image under 2 MB, which needs only one call. AFTER the upload succeeds you MUST call register_media with the object_key returned here, or the file will sit in storage counting against the store's plan while appearing in no library and no page.

**Scope:** `write_storefront`


  <ParamField body="content_type" type="string" required>
    One of: image/avif, image/gif, image/jpeg, image/png, image/webp, video/mp4, video/quicktime, video/webm. SVG is not accepted.
  </ParamField>
  <ParamField body="filename" type="string" required>
    The file's name, with no slashes and no '..'. Used for the stored key.
  </ParamField>
  <ParamField body="size_bytes" type="integer" required>
    The file's exact size in bytes. Required, and enforced: the upload is refused by storage if the file is larger, and the store's remaining plan space is checked against this number before the upload is allowed at all.
  </ParamField>

### register_media

Finishes an upload started with create_media_upload by adding the file to the store's media library and returning its URL. Call it immediately after the upload succeeds. It checks the file really arrived, so calling it after a failed upload is refused rather than recording a broken image. It does NOT take pixel dimensions: on this path the bytes never reach the backend and you have not decoded them either, so any number would be a guess.

**Scope:** `write_storefront`


  <ParamField body="content_type" type="string" required>
  </ParamField>
  <ParamField body="filename" type="string" required>
  </ParamField>
  <ParamField body="object_key" type="string" required>
    Exactly the object_key create_media_upload returned.
  </ParamField>
  <ParamField body="size_bytes" type="integer" required>
    The uploaded file's size in bytes.
  </ParamField>