Store Media

A Store Media is a store-level media asset (currently images) that can be uploaded once and then reused across the store — for example as the source of a Product Image.

API version: available from the unstable version. All URLs start with https://api.tiendanube.com/unstable/{store_id} or https://api.nuvemshop.com.br/unstable/{store_id}. SSL only.

Store Media has the following restrictions:

• Must weigh less than 20MB.
• Must be an image in one of the following types: image/jpeg, image/png, image/gif, image/webp, image/avif.

Upload flow

Uploading is a three-step flow — the file bytes are uploaded directly to storage, never through the API:

1. Presign — POST /store-media/presign returns a short-lived pre-signed upload_url and the media id (a UUID).
2. Upload — PUT the raw file bytes to upload_url (direct to storage, no Authorization header). Send the same Content-Type you declared in the presign.
3. Confirm — POST /store-media/{id}/confirm validates and persists the media. After this the media can be used (e.g. as a product image source via store_media_uuid).

Properties

Property	Explanation
id	The unique identifier for the Store Media (UUID)
store_id	ID of the store the media belongs to
slug	Storage slug used to build the media URLs
original_filename	The original file name provided on upload
alt_text	Alternative text for the media (max 255 chars). May be null
mime_type	The media MIME type (image/jpeg, image/png, image/gif, image/webp, image/avif)
media_type	High-level media type (currently image)
file_size_bytes	File size in bytes
width	Image width in pixels. May be null
height	Image height in pixels. May be null
src_sets_json	JSON describing the responsive source sets for the media. May be null
thumbnail_url	URL to a thumbnail of the media
created_at	Date when the Store Media was created in ISO 8601 format

Scopes

Operation	Scope
Read (GET)	read_content
Write (POST / PATCH / DELETE)	write_content

Endpoints

POST /store-media/presign

Request a pre-signed URL to upload a file. Rate limited.

Parameter	Explanation
original_filename	The original file name (required)
mime_type	The file MIME type; must be one of the allowed image types (required)
file_size_bytes	The exact file size in bytes; must be greater than 0 and at most 20MB (required)

POST /store-media/presign

{
  "original_filename": "charizard.jpg",
  "mime_type": "image/jpeg",
  "file_size_bytes": 20345
}

HTTP/1.1 200 OK

{
  "id": "41b5a07f-3a51-485c-bc76-7322e2831fd2",
  "slug": "41b5a07f-3a51-485c-bc76-7322e2831fd2-charizard",
  "upload_url": "https://s3.amazonaws.com/…?X-Amz-Signature=…",
  "expires_at": "2025-06-12T09:20:00-03:00"
}

HTTP/1.1 422 Unprocessable Entity

{
  "code": 422,
  "message": "Unprocessable Entity",
  "description": "Missing or invalid file_size_bytes."
}

PUT {upload_url}

Upload the raw file bytes directly to storage, using the upload_url returned by the presign. This request goes to storage, not to the API: do not send the Authorization header. Use the same Content-Type declared on the presign, and upload exactly the file whose size you sent as file_size_bytes.

HTTP/1.1 200 OK

POST /store-media/{id}/confirm

Validate the uploaded file and persist the Store Media. Send the same metadata used on the presign.

Parameter	Explanation
original_filename	The original file name (required)
mime_type	The file MIME type (required)
file_size_bytes	The exact file size in bytes (required)

POST /store-media/41b5a07f-3a51-485c-bc76-7322e2831fd2/confirm

{
  "original_filename": "charizard.jpg",
  "mime_type": "image/jpeg",
  "file_size_bytes": 20345
}

HTTP/1.1 201 Created

{
  "id": "41b5a07f-3a51-485c-bc76-7322e2831fd2",
  "store_id": 1234,
  "slug": "41b5a07f-3a51-485c-bc76-7322e2831fd2-charizard",
  "original_filename": "charizard.jpg",
  "alt_text": null,
  "mime_type": "image/jpeg",
  "media_type": "image",
  "file_size_bytes": 20345,
  "width": 1024,
  "height": 1024,
  "src_sets_json": null,
  "thumbnail_url": "https://d26lpennugtm8s.cloudfront.net/stores/001/234/media/41b5a07f-…-charizard-320.jpg",
  "created_at": "2025-06-12T09:15:11-03:00"
}

If the same file was already confirmed, the existing media is returned with status 409 Conflict.

GET /store-media

Receive a paginated list of the store's media.

Parameter	Explanation
page	Page to show (default 1)
limit	Amount of results per page (default 20, max 100)
media_type	Filter by media type (image)
filename	Filter by original filename

GET /store-media?page=1&limit=20

HTTP/1.1 200 OK

{
  "data": [
    {
      "id": "41b5a07f-3a51-485c-bc76-7322e2831fd2",
      "original_filename": "charizard.jpg",
      "alt_text": null,
      "mime_type": "image/jpeg",
      "media_type": "image",
      "width": 1024,
      "height": 1024,
      "thumbnail_url": "https://d26lpennugtm8s.cloudfront.net/stores/001/234/media/41b5a07f-…-charizard-320.jpg",
      "created_at": "2025-06-12T09:15:11-03:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

GET /store-media/{id}

Receive a single Store Media.

GET /store-media/41b5a07f-3a51-485c-bc76-7322e2831fd2

HTTP/1.1 200 OK

{
  "id": "41b5a07f-3a51-485c-bc76-7322e2831fd2",
  "store_id": 1234,
  "slug": "41b5a07f-3a51-485c-bc76-7322e2831fd2-charizard",
  "original_filename": "charizard.jpg",
  "alt_text": null,
  "mime_type": "image/jpeg",
  "media_type": "image",
  "file_size_bytes": 20345,
  "width": 1024,
  "height": 1024,
  "src_sets_json": null,
  "thumbnail_url": "https://d26lpennugtm8s.cloudfront.net/stores/001/234/media/41b5a07f-…-charizard-320.jpg",
  "created_at": "2025-06-12T09:15:11-03:00"
}

PATCH /store-media/{id}

Update a Store Media. Only alt_text can be updated.

Parameter	Explanation
alt_text	Alternative text for the media (max 255 chars, or null to clear it)

PATCH /store-media/41b5a07f-3a51-485c-bc76-7322e2831fd2

{
  "alt_text": "A drawing of Charizard"
}

HTTP/1.1 200 OK

{
  "id": "41b5a07f-3a51-485c-bc76-7322e2831fd2",
  "original_filename": "charizard.jpg",
  "alt_text": "A drawing of Charizard",
  "mime_type": "image/jpeg",
  "media_type": "image",
  "width": 1024,
  "height": 1024,
  "thumbnail_url": "https://d26lpennugtm8s.cloudfront.net/stores/001/234/media/41b5a07f-…-charizard-320.jpg",
  "created_at": "2025-06-12T09:15:11-03:00"
}

DELETE /store-media/{id}

Remove a Store Media.

DELETE /store-media/41b5a07f-3a51-485c-bc76-7322e2831fd2

HTTP/1.1 200 OK

{}

Using a Store Media as a Product Image

Once a media is confirmed, use its id as the store_media_uuid when creating or updating a Product Image:

• Create: POST /products/{product_id}/images with { "store_media_uuid": "<id>" }.
• Repoint: PUT /products/{product_id}/images/{image_id} with { "store_media_uuid": "<id>" }.