Place a library file on a product

Spree Admin SDK

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

// Places a library file on the product. The file is shared, not copied.
const media = await client.products.media.create('prod_UkLWZg9DAJ', {
  source_media_id: 'media_UkLWZg9DAJ',
  alt: 'Front view',
})

{
  "id": "media_gbHJdmfrXB",
  "product_id": "prod_gbHJdmfrXB",
  "variant_ids": [],
  "position": 1,
  "alt": "Front view",
  "media_type": "image",
  "external_video_url": null,
  "focal_point_x": null,
  "focal_point_y": null,
  "video_provider": null,
  "video_embed_url": null,
  "video_url": null,
  "poster_url": null,
  "original_url": "http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--f34e09859ba330793d603f7c22466732a512f47b/thinking-cat.jpg",
  "mini_url": "http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--f34e09859ba330793d603f7c22466732a512f47b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--4360105231729cff27f4227ea4304fac7e08a65e/thinking-cat.jpg",
  "small_url": "http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--f34e09859ba330793d603f7c22466732a512f47b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--bba92085e6437e846cd0b9fca8d58f9c0b723eba/thinking-cat.jpg",
  "medium_url": "http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--f34e09859ba330793d603f7c22466732a512f47b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--242625616b48cff11334ec85f04b68042261f208/thinking-cat.jpg",
  "large_url": "http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--f34e09859ba330793d603f7c22466732a512f47b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--0fa218972b6a0c500c744b36fcd9fee8a0b3e995/thinking-cat.jpg",
  "xlarge_url": "http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--f34e09859ba330793d603f7c22466732a512f47b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--4d30e1109a0549e5024fddaecdff7a8eb271730d/thinking-cat.jpg",
  "og_image_url": "http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--f34e09859ba330793d603f7c22466732a512f47b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--24a2fdb966aceb15786df6c2f570db0d2624d262/thinking-cat.jpg",
  "external_references": {},
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "attached": true,
  "filename": "thinking-cat.jpg",
  "content_type": "image/jpeg",
  "byte_size": 18090,
  "embed_url": "http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--f34e09859ba330793d603f7c22466732a512f47b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--67e4c38f8d0453b5c5c0d3d44862a9d1bd79c07c/thinking-cat.jpg",
  "signed_id": "eyJfcmFpbHMiOnsiZGF0YSI6MSwiZXhwIjoiMjAyNi0wMS0xNlQxMjowMDowMC4wMDBaIiwicHVyIjoiYmxvYl9pZCJ9fQ==--a9cd29e72a70654182038480207bd929343f6a07",
  "viewable_id": "prod_gbHJdmfrXB",
  "download_url": "http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--f34e09859ba330793d603f7c22466732a512f47b/thinking-cat.jpg?disposition=attachment",
  "metadata": {},
  "viewable_type": "product"
}

POST

api

admin

products

{product_id}

media

Spree Admin SDK

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

// Places a library file on the product. The file is shared, not copied.
const media = await client.products.media.create('prod_UkLWZg9DAJ', {
  source_media_id: 'media_UkLWZg9DAJ',
  alt: 'Front view',
})

{
  "id": "media_gbHJdmfrXB",
  "product_id": "prod_gbHJdmfrXB",
  "variant_ids": [],
  "position": 1,
  "alt": "Front view",
  "media_type": "image",
  "external_video_url": null,
  "focal_point_x": null,
  "focal_point_y": null,
  "video_provider": null,
  "video_embed_url": null,
  "video_url": null,
  "poster_url": null,
  "original_url": "http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--f34e09859ba330793d603f7c22466732a512f47b/thinking-cat.jpg",
  "mini_url": "http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--f34e09859ba330793d603f7c22466732a512f47b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--4360105231729cff27f4227ea4304fac7e08a65e/thinking-cat.jpg",
  "small_url": "http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--f34e09859ba330793d603f7c22466732a512f47b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--bba92085e6437e846cd0b9fca8d58f9c0b723eba/thinking-cat.jpg",
  "medium_url": "http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--f34e09859ba330793d603f7c22466732a512f47b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--242625616b48cff11334ec85f04b68042261f208/thinking-cat.jpg",
  "large_url": "http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--f34e09859ba330793d603f7c22466732a512f47b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--0fa218972b6a0c500c744b36fcd9fee8a0b3e995/thinking-cat.jpg",
  "xlarge_url": "http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--f34e09859ba330793d603f7c22466732a512f47b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--4d30e1109a0549e5024fddaecdff7a8eb271730d/thinking-cat.jpg",
  "og_image_url": "http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--f34e09859ba330793d603f7c22466732a512f47b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--24a2fdb966aceb15786df6c2f570db0d2624d262/thinking-cat.jpg",
  "external_references": {},
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "attached": true,
  "filename": "thinking-cat.jpg",
  "content_type": "image/jpeg",
  "byte_size": 18090,
  "embed_url": "http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--f34e09859ba330793d603f7c22466732a512f47b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--67e4c38f8d0453b5c5c0d3d44862a9d1bd79c07c/thinking-cat.jpg",
  "signed_id": "eyJfcmFpbHMiOnsiZGF0YSI6MSwiZXhwIjoiMjAyNi0wMS0xNlQxMjowMDowMC4wMDBaIiwicHVyIjoiYmxvYl9pZCJ9fQ==--a9cd29e72a70654182038480207bd929343f6a07",
  "viewable_id": "prod_gbHJdmfrXB",
  "download_url": "http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--f34e09859ba330793d603f7c22466732a512f47b/thinking-cat.jpg?disposition=attachment",
  "metadata": {},
  "viewable_type": "product"
}

Authorizations

x-spree-api-key

string

header

required

Secret API key for admin access

Authorization

string

header

required

JWT token for admin user authentication

Headers

x-spree-api-key

string

required

Authorization

string

required

Bearer token for admin authentication

Path Parameters

product_id

string

required

Product ID

Body

application/json

external_references

object

Identities the record has in external systems, keyed by system: the same { system: external_id } map the Admin API renders, so what you read can be sent straight back. Systems you do not name keep the reference they have. A list of { system, external_id } entries is accepted too.

alt

string | null

Example:

"Front view"

position

integer

Example:

1

media_type

enum<string>

Defaults to image. video needs a signed_id; external_video needs an external_video_url.

Available options:

image,

video,

external_video

Example:

"image"

external_video_url

string | null

YouTube or Vimeo link. Required when media_type is external_video.

poster_signed_id

string

A signed_id from files.upload() for a video's poster frame.

focal_point_x

number | null

Where the image is anchored when cropped, from 0 to 1.

focal_point_y

number | null

Where the image is anchored when cropped, from 0 to 1.

attachment

string

The file itself, sent as multipart form data. JSON clients upload first and send signed_id.

url

string

Fetch an image from this URL, in the background. Images only: an external video uses external_video_url.

signed_id

string

A signed_id from files.upload() for the media file itself.

source_media_id

string

Place a file that is already in the library. The new row shares the source file rather than copying it, and takes its own alt, position and variant links from here.

variant_ids

string[]

Variants to link this product-level media to. Variants of other products are dropped.

Response

201 - application/json

file placed

string

required

product_id

string | null

required

variant_ids

string[]

required

position

number

required

alt

string | null

required

media_type

enum<string>

required

Available options:

image,

video,

external_video

external_video_url

string | null

required

focal_point_x

number | null

required

focal_point_y

number | null

required

video_provider

string | null

required

video_embed_url

string | null

required

video_url

string | null

required

poster_url

string | null

required

original_url

string | null

required

mini_url

string | null

required

small_url

string | null

required

medium_url

string | null

required

large_url

string | null

required

xlarge_url

string | null

required

og_image_url

string | null

required

external_references

object

required

created_at

string

required

updated_at

string

required

attached

boolean

required

filename

string | null

required

content_type

string | null

required

byte_size

number | null

required

embed_url

string | null

required

signed_id

string | null

required

viewable_id

string | null

required

download_url

string | null

required

metadata

object

required

viewable_type

string | null

required

⌘I

API basics

Endpoints

Authorizations

Headers

Path Parameters

Body

Response