Spree Admin SDK

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

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

// Returns where to send the bytes: send the file to `upload.url` with
// `upload.method` and `upload.headers`, then pass `signed_id` to the
// endpoint that uses it.
// `client.files.upload(file)` does both steps for you.
const { signed_id, upload } = await client.files.create({
  filename: 'products.csv',
  content_type: 'text/csv',
  byte_size: 48213,
  checksum: 'XrY7u+Ae7tCTyyK7j1rNww==',
  visibility: 'private',
})

{
  "signed_id": "eyJfcmFpbHMiOnsiZGF0YSI6MSwiZXhwIjoiMjAyNi0wMS0xNlQxMjowMDowMC4wMDBaIiwicHVyIjoiYmxvYl9pZCJ9fQ==--a9cd29e72a70654182038480207bd929343f6a07",
  "filename": "products.csv",
  "content_type": "text/csv",
  "byte_size": 48213,
  "visibility": "private",
  "expires_at": "2026-01-16T12:00:00.000Z",
  "upload": {
    "method": "PUT",
    "url": "http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJxcmZsMnNod3YwYmR4cWF3ZWFocDZvYjhlYzh5IiwiY29udGVudF90eXBlIjoidGV4dC9jc3YiLCJjb250ZW50X2xlbmd0aCI6NDgyMTMsImNoZWNrc3VtIjoiaGdKTXJSNkRFQjJYTloxelVRVVJWZz09Iiwic2VydmljZV9uYW1lIjoidGVzdCJ9LCJleHAiOiIyMDI2LTAxLTE1VDEyOjA1OjAwLjAwMFoiLCJwdXIiOiJibG9iX3Rva2VuIn19--d4e8daa252ef4ddb8e82ab74394aab7d435572ec",
    "headers": {
      "Content-Type": "text/csv"
    }
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "Content type is not included in the list",
    "details": {
      "content_type": [
        {
          "value": "application/x-sh",
          "code": "inclusion",
          "message": "is not included in the list",
          "specific": false
        }
      ]
    }
  }
}

Upload a file

Accepts a file and returns a signed_id to send to the endpoint that uses it — signed_id on product media, avatar_signed_id on a customer, attachment_signed_id on an import, and so on.

Two ways to send the bytes, one response:

Presigned (JSON): send the file’s metadata, then PUT the bytes to upload.url with exactly upload.headers. Use this for anything large — the bytes go straight to storage.
Multipart: send the bytes in a file part. The file is stored before the response, so upload is null. Limited to 10 MB by default.

signed_id is opaque: pass it back unchanged and never parse it. It stops being attachable at expires_at, one day after the upload.

visibility picks the storage: public (the default) for images and videos customers see, private for documents, imports and digital products. Public uploads accept web images, videos and CSV; private uploads accept any type. checksum is the file’s MD5 digest, base64-encoded — the storage service verifies the bytes against it.

Required scope: write_products (for API-key authentication).

POST

api

admin

files

Spree Admin SDK

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

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

// Returns where to send the bytes: send the file to `upload.url` with
// `upload.method` and `upload.headers`, then pass `signed_id` to the
// endpoint that uses it.
// `client.files.upload(file)` does both steps for you.
const { signed_id, upload } = await client.files.create({
  filename: 'products.csv',
  content_type: 'text/csv',
  byte_size: 48213,
  checksum: 'XrY7u+Ae7tCTyyK7j1rNww==',
  visibility: 'private',
})

{
  "signed_id": "eyJfcmFpbHMiOnsiZGF0YSI6MSwiZXhwIjoiMjAyNi0wMS0xNlQxMjowMDowMC4wMDBaIiwicHVyIjoiYmxvYl9pZCJ9fQ==--a9cd29e72a70654182038480207bd929343f6a07",
  "filename": "products.csv",
  "content_type": "text/csv",
  "byte_size": 48213,
  "visibility": "private",
  "expires_at": "2026-01-16T12:00:00.000Z",
  "upload": {
    "method": "PUT",
    "url": "http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJxcmZsMnNod3YwYmR4cWF3ZWFocDZvYjhlYzh5IiwiY29udGVudF90eXBlIjoidGV4dC9jc3YiLCJjb250ZW50X2xlbmd0aCI6NDgyMTMsImNoZWNrc3VtIjoiaGdKTXJSNkRFQjJYTloxelVRVVJWZz09Iiwic2VydmljZV9uYW1lIjoidGVzdCJ9LCJleHAiOiIyMDI2LTAxLTE1VDEyOjA1OjAwLjAwMFoiLCJwdXIiOiJibG9iX3Rva2VuIn19--d4e8daa252ef4ddb8e82ab74394aab7d435572ec",
    "headers": {
      "Content-Type": "text/csv"
    }
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "Content type is not included in the list",
    "details": {
      "content_type": [
        {
          "value": "application/x-sh",
          "code": "inclusion",
          "message": "is not included in the list",
          "specific": false
        }
      ]
    }
  }
}

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

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

presigned 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