Spree Seller SDK

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

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

const profile = await client.profile.update({
  name: 'Acme Outfitters',
  contact_email: 'hello@acme.example',
  legal_name: 'Acme Outfitters Ltd',
})

curl --request PATCH \
  --url http://{defaultHost}/api/v3/seller/profile \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Spree-Seller-Id: <x-spree-seller-id>' \
  --data '
{
  "name": "Acme Supplies",
  "contact_email": "jsmith@example.com",
  "billing_email": "jsmith@example.com",
  "about": "<string>",
  "legal_name": "<string>",
  "registration_number": "<string>",
  "logo_signed_id": "<string>",
  "square_logo_signed_id": "<string>",
  "cover_photo_signed_id": "<string>",
  "billing_address": {
    "first_name": "<string>",
    "last_name": "<string>",
    "company": "<string>",
    "address1": "<string>",
    "address2": "<string>",
    "city": "<string>",
    "postal_code": "<string>",
    "phone": "<string>",
    "label": "<string>",
    "country_code": "US",
    "state_code": "NY",
    "state_name": "<string>"
  },
  "custom_fields": [
    {
      "id": "<string>",
      "custom_field_definition_id": "<string>",
      "value": "<unknown>"
    }
  ],
  "accept_terms": true
}
'

{
  "id": "sel_UkLWZg9DAJ",
  "name": "Acme Supplies",
  "slug": "seller-146",
  "about": "",
  "about_html": "",
  "logo_url": null,
  "square_logo_url": null,
  "cover_photo_url": null,
  "timezone": "UTC",
  "status": "approved",
  "legal_name": null,
  "registration_number": null,
  "contact_email": "hello@acme.test",
  "billing_email": null,
  "tax_remittance": "seller",
  "payouts_schedule_interval": null,
  "holiday_mode_until": null,
  "terms_accepted_at": "2026-01-15T12:00:00.000Z",
  "created_at": "2026-01-15T12:00:00.000Z",
  "minimum_payout_amount": null,
  "on_holiday": false,
  "sellable": true,
  "default_currency": "USD",
  "supported_currencies": [
    "USD",
    "EUR",
    "GBP"
  ],
  "products_count": 0
}

{
  "error": {
    "code": "validation_error",
    "message": "Name can't be blank",
    "details": {
      "name": [
        "can't be blank"
      ]
    }
  }
}

Update profile

Edits presentation, contact details and addresses.

Readable but not writable, by design: status — the lifecycle belongs to the marketplace operator’s workflows — the settlement terms, and slug, since a seller renaming their own storefront address would break every link pointing at it.

accept_terms: true stamps the moment the seller accepted the marketplace’s terms, which is what the matching onboarding requirement reads. One-way — sending false does not unmake the stamp.

custom_fields is narrowed server-side to the definitions this marketplace’s onboarding actually asks this seller for; a field nothing asked for is ignored rather than written.

PATCH

api

seller

profile

Spree Seller SDK

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

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

const profile = await client.profile.update({
  name: 'Acme Outfitters',
  contact_email: 'hello@acme.example',
  legal_name: 'Acme Outfitters Ltd',
})

curl --request PATCH \
  --url http://{defaultHost}/api/v3/seller/profile \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Spree-Seller-Id: <x-spree-seller-id>' \
  --data '
{
  "name": "Acme Supplies",
  "contact_email": "jsmith@example.com",
  "billing_email": "jsmith@example.com",
  "about": "<string>",
  "legal_name": "<string>",
  "registration_number": "<string>",
  "logo_signed_id": "<string>",
  "square_logo_signed_id": "<string>",
  "cover_photo_signed_id": "<string>",
  "billing_address": {
    "first_name": "<string>",
    "last_name": "<string>",
    "company": "<string>",
    "address1": "<string>",
    "address2": "<string>",
    "city": "<string>",
    "postal_code": "<string>",
    "phone": "<string>",
    "label": "<string>",
    "country_code": "US",
    "state_code": "NY",
    "state_name": "<string>"
  },
  "custom_fields": [
    {
      "id": "<string>",
      "custom_field_definition_id": "<string>",
      "value": "<unknown>"
    }
  ],
  "accept_terms": true
}
'

{
  "id": "sel_UkLWZg9DAJ",
  "name": "Acme Supplies",
  "slug": "seller-146",
  "about": "",
  "about_html": "",
  "logo_url": null,
  "square_logo_url": null,
  "cover_photo_url": null,
  "timezone": "UTC",
  "status": "approved",
  "legal_name": null,
  "registration_number": null,
  "contact_email": "hello@acme.test",
  "billing_email": null,
  "tax_remittance": "seller",
  "payouts_schedule_interval": null,
  "holiday_mode_until": null,
  "terms_accepted_at": "2026-01-15T12:00:00.000Z",
  "created_at": "2026-01-15T12:00:00.000Z",
  "minimum_payout_amount": null,
  "on_holiday": false,
  "sellable": true,
  "default_currency": "USD",
  "supported_currencies": [
    "USD",
    "EUR",
    "GBP"
  ],
  "products_count": 0
}

{
  "error": {
    "code": "validation_error",
    "message": "Name can't be blank",
    "details": {
      "name": [
        "can't be blank"
      ]
    }
  }
}

Authorizations

Authorization

string

header

required

JWT token for an authenticated seller session (seller_api audience)

Headers

X-Spree-Seller-Id

string

required

Body

application/json

name

string

Example:

"Acme Supplies"

contact_email

string<email> | null

billing_email

string<email> | null

about

string | null

Sanitized HTML: the seller's public description.

legal_name

string | null

The business a commission invoice is made out to.

registration_number

string | null

logo_signed_id

string | null

A signed_id from POST /files; null removes the image.

square_logo_signed_id

string | null

A signed_id from POST /files; null removes the image.

cover_photo_signed_id

string | null

A signed_id from POST /files; null removes the image.

billing_address

object

Show child attributes

custom_fields

object[]

Answers to the custom fields this marketplace's onboarding asks for. A field nothing asked for is ignored rather than written.

Show child attributes

accept_terms

boolean

Stamps the moment the seller accepted the marketplace's terms. One-way: sending false does not unmake the stamp.

Response

profile updated

string

required

name

string

required

slug

string

required

about

string

required

about_html

string

required

logo_url

string | null

required

square_logo_url

string | null

required

cover_photo_url

string | null

required

timezone

string | null

required

status

required

The values listed are the built-in ones; extensions may add more.

Available options:

pending,

invited,

canceled,

onboarding,

ready_for_review,

approved,

rejected,

suspended

legal_name

string | null

required

registration_number

string | null

required

contact_email

string | null

required

billing_email

string | null

required

tax_remittance

enum<string>

required

Available options:

seller,

platform

payouts_schedule_interval

enum<string> | null

required

Available options:

daily,

weekly,

biweekly,

monthly,

manual

holiday_mode_until

string | null

required

terms_accepted_at

string | null

required

created_at

string

required

minimum_payout_amount

string | null

required

on_holiday

boolean

required

sellable

boolean

required

default_currency

enum<string>

required

Available options:

AED,

AFN,

ALL,

AMD,

ANG,

AOA,

ARS,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

BGN,

BHD,

BIF,

BMD,

BND,

BOB,

BRL,

BSD,

BTN,

BWP,

BYN,

BYR,

BZD,

CAD,

CDF,

CHF,

CLF,

CLP,

CNY,

COP,

CRC,

CUC,

CUP,

CVE,

CZK,

DJF,

DKK,

DOP,

DZD,

EEK,

EGP,

ERN,

ETB,

EUR,

FJD,

FKP,

GBP,

GEL,

GHS,

GIP,

GMD,

GNF,

GTQ,

GYD,

HKD,

HNL,

HRK,

HTG,

HUF,

IDR,

ILS,

INR,

IQD,

IRR,

ISK,

JMD,

JOD,

JPY,

KES,

KGS,

KHR,

KMF,

KPW,

KRW,

KWD,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

LTL,

LVL,

LYD,

MAD,

MDL,

MGA,

MKD,

MMK,

MNT,

MOP,

MRO,

MRU,

MTL,

MUR,

MVR,

MWK,

MXN,

MYR,

MZN,

NAD,

NGN,

NIO,

NOK,

NPR,

NZD,

OMR,

PAB,

PEN,

PGK,

PHP,

PKR,

PLN,

PYG,

QAR,

RON,

RSD,

RUB,

RWF,

SAR,

SBD,

SCR,

SDG,

SEK,

SGD,

SHP,

SKK,

SLE,

SLL,

SOS,

SRD,

SSP,

STD,

STN,

SVC,

SYP,

SZL,

THB,

TJS,

TMM,

TMT,

TND,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

USD,

UYI,

UYU,

UYW,

UZS,

VED,

VEF,

VES,

VND,

VUV,

WST,

XAF,

XCD,

XCG,

XOF,

XPF,

YER,

ZAR,

ZMK,

ZMW,

ZWD,

ZWG,

ZWL,

ZWN,

ZWR

supported_currencies

enum<string>[]

required

Available options:

AED,

AFN,

ALL,

AMD,

ANG,

AOA,

ARS,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

BGN,

BHD,

BIF,

BMD,

BND,

BOB,

BRL,

BSD,

BTN,

BWP,

BYN,

BYR,

BZD,

CAD,

CDF,

CHF,

CLF,

CLP,

CNY,

COP,

CRC,

CUC,

CUP,

CVE,

CZK,

DJF,

DKK,

DOP,

DZD,

EEK,

EGP,

ERN,

ETB,

EUR,

FJD,

FKP,

GBP,

GEL,

GHS,

GIP,

GMD,

GNF,

GTQ,

GYD,

HKD,

HNL,

HRK,

HTG,

HUF,

IDR,

ILS,

INR,

IQD,

IRR,

ISK,

JMD,

JOD,

JPY,

KES,

KGS,

KHR,

KMF,

KPW,

KRW,

KWD,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

LTL,

LVL,

LYD,

MAD,

MDL,

MGA,

MKD,

MMK,

MNT,

MOP,

MRO,

MRU,

MTL,

MUR,

MVR,

MWK,

MXN,

MYR,

MZN,

NAD,

NGN,

NIO,

NOK,

NPR,

NZD,

OMR,

PAB,

PEN,

PGK,

PHP,

PKR,

PLN,

PYG,

QAR,

RON,

RSD,

RUB,

RWF,

SAR,

SBD,

SCR,

SDG,

SEK,

SGD,

SHP,

SKK,

SLE,

SLL,

SOS,

SRD,

SSP,

STD,

STN,

SVC,

SYP,

SZL,

THB,

TJS,

TMM,

TMT,

TND,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

USD,

UYI,

UYU,

UYW,

UZS,

VED,

VEF,

VES,

VND,

VUV,

WST,

XAF,

XCD,

XCG,

XOF,

XPF,

YER,

ZAR,

ZMK,

ZMW,

ZWD,

ZWG,

ZWL,

ZWN,

ZWR

products_count

number

required

policies

object[]

Show child attributes

billing_address

object

Show child attributes

returns_address

object

Show child attributes

⌘I

API basics

Endpoints

Update profile

Authorizations

Headers

Body

Response