Spree Seller SDK

import { createSellerClient } from '@spree/seller-sdk'

const client = createSellerClient({
  baseUrl: 'https://your-store.com',
  jwtToken: 'eyJhbGciOi...',
  sellerId: 'sel_UkLWZg9DAJ',
})

const file = await client.files.create({
  filename: 'registration.pdf',
  content_type: 'application/pdf',
  byte_size: 51234,
  visibility: 'private',
})

curl --request POST \
  --url http://{defaultHost}/api/v3/seller/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Spree-Seller-Id: <x-spree-seller-id>' \
  --data '
{
  "filename": "registration.pdf",
  "content_type": "application/pdf",
  "byte_size": 51234,
  "checksum": "rL0Y20zC+Fzt72VPzMSk2A==",
  "file": "<string>"
}
'

{
  "signed_id": "eyJfcmFpbHMiOnsiZGF0YSI6MSwiZXhwIjoiMjAyNi0wMS0xNlQxMjowMDowMC4wMDBaIiwicHVyIjoiYmxvYl9pZCJ9fQ==--a9cd29e72a70654182038480207bd929343f6a07",
  "filename": "registration.pdf",
  "content_type": "application/pdf",
  "byte_size": 51234,
  "visibility": "private",
  "expires_at": "2026-01-16T12:00:00.000Z",
  "upload": {
    "method": "PUT",
    "url": "http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiI4NDFrenlvbTQ5cnRhcDk0cmZxbGV6dnM1cGJsIiwiY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vcGRmIiwiY29udGVudF9sZW5ndGgiOjUxMjM0LCJjaGVja3N1bSI6IlZqaHowNGxRdUVHdXY0bkR2aHNhTlE9PSIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl90b2tlbiJ9fQ==--abe303073ba7e7a0de1e5dc55e6c2a9a162c265e",
    "headers": {
      "Content-Type": "application/pdf"
    }
  }
}

Upload a file

Accepts a file and returns a signed_id to send wherever the file belongs — as a requirement submission’s file_signed_id, or as logo_signed_id, square_logo_signed_id or cover_photo_signed_id on the profile. The file is attached to nothing at this point; the endpoint that takes the signed_id is the one that checks ownership.

Send the file’s metadata as JSON, then PUT the bytes to upload.url with exactly upload.headers; or send small files (10 MB by default) as a multipart file part, in which case upload is null.

signed_id is opaque and expires at expires_at, one day after the upload. visibility is public (the default, web images, videos and CSV only) or private (any type). checksum is the file’s MD5 digest, base64-encoded.

POST

api

seller

files

Spree Seller SDK

import { createSellerClient } from '@spree/seller-sdk'

const client = createSellerClient({
  baseUrl: 'https://your-store.com',
  jwtToken: 'eyJhbGciOi...',
  sellerId: 'sel_UkLWZg9DAJ',
})

const file = await client.files.create({
  filename: 'registration.pdf',
  content_type: 'application/pdf',
  byte_size: 51234,
  visibility: 'private',
})

curl --request POST \
  --url http://{defaultHost}/api/v3/seller/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Spree-Seller-Id: <x-spree-seller-id>' \
  --data '
{
  "filename": "registration.pdf",
  "content_type": "application/pdf",
  "byte_size": 51234,
  "checksum": "rL0Y20zC+Fzt72VPzMSk2A==",
  "file": "<string>"
}
'

{
  "signed_id": "eyJfcmFpbHMiOnsiZGF0YSI6MSwiZXhwIjoiMjAyNi0wMS0xNlQxMjowMDowMC4wMDBaIiwicHVyIjoiYmxvYl9pZCJ9fQ==--a9cd29e72a70654182038480207bd929343f6a07",
  "filename": "registration.pdf",
  "content_type": "application/pdf",
  "byte_size": 51234,
  "visibility": "private",
  "expires_at": "2026-01-16T12:00:00.000Z",
  "upload": {
    "method": "PUT",
    "url": "http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiI4NDFrenlvbTQ5cnRhcDk0cmZxbGV6dnM1cGJsIiwiY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vcGRmIiwiY29udGVudF9sZW5ndGgiOjUxMjM0LCJjaGVja3N1bSI6IlZqaHowNGxRdUVHdXY0bkR2aHNhTlE9PSIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl90b2tlbiJ9fQ==--abe303073ba7e7a0de1e5dc55e6c2a9a162c265e",
    "headers": {
      "Content-Type": "application/pdf"
    }
  }
}

Authorizations

Authorization

string

header

required

JWT token for an authenticated seller session (seller_api audience)

Headers

X-Spree-Seller-Id

string

required

Body

filename

string

required

Example:

"registration.pdf"

content_type

string

required

Example:

"application/pdf"

byte_size

integer

Example:

51234

checksum

string

Base64-encoded MD5 digest of the file; the storage service checks the bytes against it.

Example:

"rL0Y20zC+Fzt72VPzMSk2A=="

visibility

enum<string>

public (the default) for images, videos and CSV files anyone may fetch, private for any type.

Available options:

public,

private

file

The bytes, for a multipart upload.

Response

201 - application/json

upload target created

signed_id

string

required

filename

string

required

content_type

string

required

byte_size

number

required

visibility

enum<string>

required

Available options:

public,

private

expires_at

string

required

upload

object | null

required

Show child attributes

⌘I

API basics

Endpoints

Upload a file

Authorizations

Headers

Body

Response