Spree Admin SDK

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

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

// Charges this seller 12.5% of every sale, with VAT on the commission itself
// left to your tax settings. The rate lands at the top of the list, so it
// resolves ahead of anything more general already there.
const commissionRate = await client.commissionRates.create({
  name: 'Audio sellers',
  kind: 'percentage',
  value: '12.5',
  rules: [{ type: 'seller_rule', preferences: { seller_ids: ['sel_a1b2c3'] } }],
})

{
  "id": "crate_gbHJdmfrXB",
  "name": "Audio sellers",
  "code": null,
  "enabled": true,
  "position": 1,
  "kind": "percentage",
  "tax_inclusive": false,
  "include_shipping": false,
  "metadata": {},
  "deleted_at": null,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "value": "12.5",
  "commission_tax_rate": null,
  "amounts": {},
  "bounds": {},
  "global": true,
  "rules": []
}

{
  "error": {
    "code": "validation_error",
    "message": "needs a flat fee amount in at least one currency",
    "details": {
      "base": [
        {
          "code": "commission_rate_needs_an_amount",
          "message": "needs a flat fee amount in at least one currency",
          "specific": false
        }
      ]
    }
  }
}

Create a commission rate

Sets what the marketplace charges, and which sales it applies to.

rules is the rate’s whole targeting, sent inline. Every rule has to hold, and a rule naming several records means any of them — so “(Cameras OR Audio) AND that seller” is a category rule holding two ids beside a seller rule holding one. Send no rules to charge every sale.

Rule kinds come from GET /commission_rates/rule_types, which also describes the configuration each one takes. A marketplace that adds its own kind sees it there without this endpoint changing.

commission_tax_rate is VAT on the commission itself — the marketplace’s own service to the seller, a separate supply from the sale. Leave it null to let the store’s tax engine answer for wherever the seller’s business sits.

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

POST

api

admin

commission_rates

Spree Admin SDK

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

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

// Charges this seller 12.5% of every sale, with VAT on the commission itself
// left to your tax settings. The rate lands at the top of the list, so it
// resolves ahead of anything more general already there.
const commissionRate = await client.commissionRates.create({
  name: 'Audio sellers',
  kind: 'percentage',
  value: '12.5',
  rules: [{ type: 'seller_rule', preferences: { seller_ids: ['sel_a1b2c3'] } }],
})

{
  "id": "crate_gbHJdmfrXB",
  "name": "Audio sellers",
  "code": null,
  "enabled": true,
  "position": 1,
  "kind": "percentage",
  "tax_inclusive": false,
  "include_shipping": false,
  "metadata": {},
  "deleted_at": null,
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z",
  "value": "12.5",
  "commission_tax_rate": null,
  "amounts": {},
  "bounds": {},
  "global": true,
  "rules": []
}

{
  "error": {
    "code": "validation_error",
    "message": "needs a flat fee amount in at least one currency",
    "details": {
      "base": [
        {
          "code": "commission_rate_needs_an_amount",
          "message": "needs a flat fee amount in at least one currency",
          "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

Body

application/json

name

string

required

Example:

"Audio sellers"

kind

enum<string>

required

percentage charges a share of the sale; fixed charges a flat fee.

Available options:

percentage,

fixed

Example:

"percentage"

value

string<decimal>

required

A percentage (10 = 10%) or a flat amount, per kind.

Pattern: ^-?\d+(\.\d+)?$

Example:

"12.5"

code

string | null

Your own identifier for this rate; unique per store.

Example:

"audio"

enabled

boolean

position

integer

Place in the list. Rates resolve top-down and the first whose rules match wins, so 1 is tried first. New rates are created at the top; send this to move one. A rate with no rules matches every sale, so the marketplace default belongs at the bottom.

Example:

1

tax_inclusive

boolean

Charge on the price including the customer's VAT. Left off, commission is charged on the seller's net revenue, which is the usual basis where the fee is taxed as its own supply.

include_shipping

boolean

Also charge commission on the seller's delivery revenue. Percentage rates only.

commission_tax_rate

string<decimal> | null

VAT on the commission itself, as a fraction rather than a percentage. Null lets the store's tax engine answer for the seller's jurisdiction.

Pattern: ^-?\d+(\.\d+)?$

Example:

"0.21"

metadata

object

amounts

object

What a flat fee charges, keyed by currency, as decimal strings. A sale in a currency with no amount falls to the next matching rate. Replaces the whole set.

Example:

{ "USD": "2.50", "EUR": "2.00" }

bounds

object

The floor and cap a percentage charges within, keyed by currency: { min_amount, max_amount } decimal strings. A sale in a currency with no bounds is charged unbounded. Replaces the whole set.

Example:

{
  "USD": {
    "min_amount": "1.00",
    "max_amount": "50.00"
  }
}

rules

object[]

The full targeting; what you send replaces what the rate holds.

Show child attributes

Response

commission rate created

string

required

name

string

required

code

string | null

required

enabled

boolean

required

position

number

required

kind

enum<string>

required

Available options:

percentage,

fixed

tax_inclusive

boolean

required

include_shipping

boolean

required

metadata

object | null

required

deleted_at

string | null

required

created_at

string

required

updated_at

string

required

value

string

required

commission_tax_rate

string | null

required

amounts

object

required

bounds

object

required

global

boolean

required

rules

object[]

required

Show child attributes

⌘I

API basics

Endpoints

Create a commission rate

Authorizations

Headers

Body

Response