> ## Documentation Index > Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt > Use this file to discover all available pages before exploring further. # Update a commission rate > Editing a rate changes what the next sale is charged, never what a past one was: commission lines keep their own snapshot of the rate that applied. **Required scope:** `write_commissions` (for API-key authentication). ## OpenAPI ````yaml /api-reference/admin.yaml patch /api/v3/admin/commission_rates/{id} openapi: 3.0.3 info: title: Admin API contact: name: Spree Commerce url: https://spreecommerce.org email: hello@spreecommerce.org description: > Spree Admin API v3 - Administrative API for managing products, orders, and store settings. ## Authentication The Admin API requires a secret API key passed in the `x-spree-api-key` header. Secret API keys can be generated in the Spree admin dashboard. ## Response Format All responses are JSON. List endpoints return paginated responses with `data` and `meta` keys. Single resource endpoints return a flat JSON object. ## Resource IDs Every resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`, `variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths, request bodies, and Ransack filters all accept them directly. ## Error Handling Errors return a consistent format: ```json { "error": { "code": "validation_error", "message": "Validation failed", "details": { "name": ["can't be blank"] } } } ``` version: v3 servers: - url: http://{defaultHost} variables: defaultHost: default: localhost:3000 security: [] tags: - name: Authentication description: Admin user login, logout, token refresh, and current user profile - name: Allowed Origins description: CORS allowlist for storefront and admin client origins - name: API Keys description: Secret and publishable API keys - name: Categories description: >- Hierarchical product categories — tree management, repositioning, and product assignments - name: Channels description: >- Sales channels, product publication across channels, and per-channel order routing rules - name: Custom Fields description: >- Custom field definitions for products, variants, customers, and other resources - name: Customer Groups description: >- Customer groups for segmenting customers (e.g. wholesale, VIP) used by pricing and promotions - name: Customers description: Customer profiles, addresses, credit cards, and store credits - name: Email Templates description: >- Customer email templates, the email layout and shared partials: drafts, previews, publishing and history - name: Exports description: Async CSV exports of admin resources - name: Files description: Uploading the files that product media, imports, logos and documents use - name: Fulfillments description: Order fulfillments — shipments, fulfill, cancel, resume, split - name: Gift Cards description: Gift cards and gift card batches - name: Imports description: >- Async CSV imports of admin resources, with per-row status and failed-row retry - name: Markets description: >- Markets — geographic groupings of countries used for pricing, tax, and fulfillment rules - name: Option Types description: >- Option types and option values used to build product variants (e.g. Size, Color) - name: Orders description: Orders, order items, applied gift cards, and applied store credits - name: Payment Methods description: Configured payment providers and their available types - name: Payments description: Order payments — list, capture, void - name: Pricing description: >- Prices and price lists for currency-, market-, and customer-group-specific pricing - name: Products description: >- Products, taxons/categories, product custom field values, and bulk product operations - name: Policies description: The store's legal documents — terms of service, privacy, returns, shipping - name: Reasons description: >- Merchant-owned vocabularies for why a return, claim, refund, cancellation or tax exemption happened - name: Promotions description: Promotions, promotion rules, promotion actions, and coupon codes - name: Refunds description: Order refunds - name: Settings description: Store-level settings — store profile, tags, and configuration - name: Staff description: Admin users, roles, and invitations to the store - name: Stock Locations description: Warehouses and physical fulfillment locations - name: Store Credits description: Prepaid customer balances across all customers, and each balance's ledger - name: Variants description: >- Product variants — the individual SKUs (size/color combinations) sold under a product - name: Webhooks description: Webhook endpoints and webhook delivery history paths: /api/v3/admin/commission_rates/{id}: parameters: - name: id in: path description: Commission rate ID required: true schema: type: string patch: tags: - Commission Rates summary: Update a commission rate description: |- Editing a rate changes what the next sale is charged, never what a past one was: commission lines keep their own snapshot of the rate that applied. **Required scope:** `write_commissions` (for API-key authentication). parameters: - name: x-spree-api-key in: header required: true schema: type: string - name: Authorization in: header required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CommissionRateUpdateParams' required: true responses: '200': description: commission rate updated content: application/json: example: id: crate_UkLWZg9DAJ name: Standard 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: '15' commission_tax_rate: null amounts: {} bounds: {} global: true rules: [] schema: $ref: '#/components/schemas/CommissionRate' security: - api_key: [] bearer_auth: [] x-codeSamples: - lang: javascript label: Spree Admin SDK source: >- import { createAdminClient } from '@spree/admin-sdk' const client = createAdminClient({ baseUrl: 'https://your-store.com', secretKey: 'sk_xxx', }) // `rules` is the rate's whole targeting — what you send replaces what it holds. // `position` moves the rate: 1 is tried first, and the first match wins. // // Every rule has to hold, so this charges 15% only on camera sales worth 50 or // more. Call ruleTypes() for the kinds this marketplace has. const commissionRate = await client.commissionRates.update('crate_a1b2c3', { value: '15', position: 1, rules: [ { type: 'category_rule', preferences: { category_ids: ['ctg_d4e5f6'] } }, { type: 'item_total_rule', preferences: { min_amount: '50' } }, ], }) - lang: bash label: Spree CLI source: >- spree api patch /commission_rates/{id} -d '{"value":"15","position":1,"rules":[{"type":"category_rule","preferences":{"category_ids":["ctg_d4e5f6"]}},{"type":"item_total_rule","preferences":{"min_amount":"50"}}]}' components: schemas: CommissionRateUpdateParams: type: object properties: name: type: string example: Audio sellers code: type: string description: Your own identifier for this rate; unique per store. example: audio nullable: true enabled: type: boolean position: type: integer description: >- 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 kind: type: string enum: - percentage - fixed description: >- `percentage` charges a share of the sale; `fixed` charges a flat fee. example: percentage value: type: string format: decimal pattern: ^-?\d+(\.\d+)?$ description: A percentage (10 = 10%) or a flat amount, per `kind`. example: '12.5' tax_inclusive: type: boolean description: >- 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: type: boolean description: >- Also charge commission on the seller's delivery revenue. Percentage rates only. commission_tax_rate: type: string format: decimal pattern: ^-?\d+(\.\d+)?$ description: >- 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. example: '0.21' nullable: true metadata: type: object additionalProperties: true amounts: type: object additionalProperties: true description: >- 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: type: object additionalProperties: true description: >- 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: type: array items: $ref: '#/components/schemas/CommissionRuleDraftParams' description: The full targeting; what you send replaces what the rate holds. CommissionRate: type: object properties: id: type: string name: type: string code: type: string nullable: true enabled: type: boolean position: type: number kind: type: string enum: - percentage - fixed tax_inclusive: type: boolean include_shipping: type: boolean metadata: type: object nullable: true deleted_at: type: string nullable: true created_at: type: string updated_at: type: string value: type: string commission_tax_rate: type: string nullable: true amounts: type: object bounds: type: object global: type: boolean rules: type: array items: $ref: '#/components/schemas/CommissionRule' required: - id - name - code - enabled - position - kind - tax_inclusive - include_shipping - metadata - deleted_at - created_at - updated_at - value - commission_tax_rate - amounts - bounds - global - rules x-typelizer: true CommissionRuleDraftParams: type: object properties: id: type: string description: Present for an existing rule; omit to create one. nullable: true type: type: string description: A kind from `GET /commission_rates/rule_types`. example: seller_rule preferences: type: object additionalProperties: true description: Configuration for the kind, per its type's `schema`. example: seller_ids: - sel_a1b2c3 product_ids: type: array items: type: string description: For kinds that name products, which are kept outside preferences. required: - type CommissionRule: type: object properties: id: type: string created_at: type: string updated_at: type: string type: type: string description: >- Rule type. Built-in: seller_rule, category_rule, product_rule, item_total_rule. Extensions may register more. commission_rate_id: type: string preferences: $ref: '#/components/schemas/CommissionRulePreferences' product_ids: type: array items: type: string nullable: true seller_ids: type: array items: type: string nullable: true category_ids: type: array items: type: string nullable: true sellers: type: array items: $ref: '#/components/schemas/Seller' categories: type: array items: $ref: '#/components/schemas/Category' required: - id - created_at - updated_at - type - commission_rate_id - preferences - product_ids - seller_ids - category_ids x-typelizer: true CommissionRulePreferences: description: >- Settings of a commission rule, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries. anyOf: - $ref: '#/components/schemas/CommissionRuleCategoryRulePreferences' - $ref: '#/components/schemas/CommissionRuleItemTotalRulePreferences' - $ref: '#/components/schemas/CommissionRuleProductRulePreferences' - $ref: '#/components/schemas/CommissionRuleSellerRulePreferences' - type: object additionalProperties: true x-spree-preferences-by-type: category_rule: '#/components/schemas/CommissionRuleCategoryRulePreferences' item_total_rule: '#/components/schemas/CommissionRuleItemTotalRulePreferences' product_rule: '#/components/schemas/CommissionRuleProductRulePreferences' seller_rule: '#/components/schemas/CommissionRuleSellerRulePreferences' Seller: type: object properties: id: type: string name: type: string slug: type: string about: type: string about_html: type: string logo_url: type: string nullable: true square_logo_url: type: string nullable: true cover_photo_url: type: string nullable: true status: anyOf: - type: string enum: - pending - invited - canceled - onboarding - ready_for_review - approved - rejected - suspended - type: string description: The values listed are the built-in ones; extensions may add more. contact_email: type: string nullable: true billing_email: type: string nullable: true tax_remittance: type: string enum: - seller - platform payouts_schedule_interval: type: string nullable: true enum: - daily - weekly - biweekly - monthly - manual metadata: type: object nullable: true holiday_mode_until: type: string nullable: true terms_accepted_at: type: string nullable: true created_at: type: string updated_at: type: string deleted_at: type: string nullable: true minimum_payout_amount: type: string nullable: true on_holiday: type: boolean sellable: type: boolean products_count: type: number users_count: type: number onboarding_progress: type: object onboarding_complete: type: boolean legal_name: type: string nullable: true registration_number: type: string nullable: true billing_address: $ref: '#/components/schemas/Address' returns_address: $ref: '#/components/schemas/Address' required: - id - name - slug - about - about_html - logo_url - square_logo_url - cover_photo_url - status - contact_email - billing_email - tax_remittance - payouts_schedule_interval - metadata - holiday_mode_until - terms_accepted_at - created_at - updated_at - deleted_at - minimum_payout_amount - on_holiday - sellable - products_count - users_count - onboarding_progress - onboarding_complete - legal_name - registration_number x-typelizer: true Category: type: object properties: id: type: string name: type: string permalink: type: string position: type: number depth: type: number meta_title: type: string nullable: true meta_description: type: string nullable: true meta_keywords: type: string nullable: true children_count: type: number parent_id: type: string nullable: true description: type: string description_html: type: string image_url: type: string nullable: true square_image_url: type: string nullable: true is_root: type: boolean is_child: type: boolean is_leaf: type: boolean parent: $ref: '#/components/schemas/Category' children: type: array items: $ref: '#/components/schemas/Category' ancestors: type: array items: $ref: '#/components/schemas/Category' custom_fields: type: array items: $ref: '#/components/schemas/CustomField' external_references: type: object translations: type: object metadata: type: object pretty_name: type: string lft: type: number rgt: type: number products_count: type: number created_at: type: string updated_at: type: string required: - id - name - permalink - position - depth - meta_title - meta_description - meta_keywords - children_count - parent_id - description - description_html - image_url - square_image_url - is_root - is_child - is_leaf - external_references - metadata - pretty_name - lft - rgt - products_count - created_at - updated_at x-typelizer: true CommissionRuleCategoryRulePreferences: type: object properties: category_ids: type: array items: type: string format: prefixed-id pattern: ^ctg_[A-Za-z0-9]+$ x-spree-prefix: ctg default: [] additionalProperties: false CommissionRuleItemTotalRulePreferences: type: object properties: min_amount: type: string format: money pattern: ^-?\d+(\.\d+)?$ nullable: true max_amount: type: string format: money pattern: ^-?\d+(\.\d+)?$ nullable: true additionalProperties: false CommissionRuleProductRulePreferences: type: object properties: {} additionalProperties: false CommissionRuleSellerRulePreferences: type: object properties: seller_ids: type: array items: type: string format: prefixed-id pattern: ^sel_[A-Za-z0-9]+$ x-spree-prefix: sel default: [] additionalProperties: false Address: type: object properties: id: type: string label: type: string nullable: true first_name: type: string nullable: true last_name: type: string nullable: true full_name: type: string address1: type: string nullable: true address2: type: string nullable: true postal_code: type: string nullable: true city: type: string nullable: true phone: type: string nullable: true company: type: string nullable: true country_name: type: string country_code: type: string enum: - AD - AE - AF - AG - AI - AL - AM - AO - AR - AS - AT - AU - AW - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GT - GU - GW - GY - HK - HN - HR - HT - HU - ID - IE - IL - IM - IN - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW state_text: type: string nullable: true state_code: type: string nullable: true quick_checkout: type: boolean is_default_billing: type: boolean is_default_shipping: type: boolean state_name: type: string nullable: true owner: allOf: - $ref: '#/components/schemas/AddressOwner' nullable: true metadata: type: object created_at: type: string updated_at: type: string latitude: type: number nullable: true longitude: type: number nullable: true customer_id: type: string nullable: true required: - id - label - first_name - last_name - full_name - address1 - address2 - postal_code - city - phone - company - country_name - country_code - state_text - state_code - quick_checkout - is_default_billing - is_default_shipping - state_name - owner - metadata - created_at - updated_at - latitude - longitude - customer_id x-typelizer: true CustomField: type: object properties: id: type: string label: type: string field_type: type: string enum: - short_text - long_text - rich_text - number - boolean - json key: type: string value: {} created_at: type: string updated_at: type: string storefront_visible: type: boolean custom_field_definition_id: type: string required: - id - label - field_type - key - value - created_at - updated_at - storefront_visible - custom_field_definition_id x-typelizer: true AddressOwner: type: object properties: id: type: string type: anyOf: - type: string enum: - customer - company - seller - type: string description: The values listed are the built-in ones; extensions may add more. name: type: string nullable: true required: - id - type - name x-typelizer: true securitySchemes: api_key: type: apiKey name: x-spree-api-key in: header description: Secret API key for admin access bearer_auth: type: http scheme: bearer bearerFormat: JWT description: JWT token for admin user authentication ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.