> ## 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 seller requirement

> Changes how a requirement is worded, what it asks for, where it sits in
the checklist, and whether it blocks approval.

`type` is not accepted: a saved row's kind never changes, because
anything a seller already submitted answered the old one.


**Required scope:** `write_sellers` (for API-key authentication).



## OpenAPI

````yaml /api-reference/admin.yaml patch /api/v3/admin/seller_requirements/{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/seller_requirements/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    patch:
      tags:
        - Seller Requirements
      summary: Update a seller requirement
      description: |-
        Changes how a requirement is worded, what it asks for, where it sits in
        the checklist, and whether it blocks approval.

        `type` is not accepted: a saved row's kind never changes, because
        anything a seller already submitted answered the old one.


        **Required scope:** `write_sellers` (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/SellerRequirementUpdateParams'
        required: true
      responses:
        '200':
          description: seller requirement updated
          content:
            application/json:
              example:
                id: selreq_UkLWZg9DAJ
                position: 1
                active: true
                required: true
                metadata: {}
                created_at: '2026-01-15T12:00:00.000Z'
                updated_at: '2026-01-15T12:00:00.000Z'
                kind: minimum_products
                name: Minimum products
                description: List at least this many products
                preferences:
                  minimum_count: 3
                custom_field_definition_ids: []
                allow_multiple: false
                accepts_submissions: false
                reviewed_by_operator: false
              schema:
                $ref: '#/components/schemas/SellerRequirement'
      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',
            })


            // Asks for three products instead of one. Sellers who already met
            the old

            // number see this return to their checklist.

            const sellerRequirement = await
            client.sellerRequirements.update('selreq_a1b2c3', {
              preferences: { minimum_count: 3 },
            })
        - lang: bash
          label: Spree CLI
          source: >-
            spree api patch /seller_requirements/{id} -d
            '{"preferences":{"minimum_count":3}}'
components:
  schemas:
    SellerRequirementUpdateParams:
      type: object
      properties:
        name:
          type: string
          description: >-
            What the seller sees. Required for kinds that can be added more than
            once, since the wording is the only thing telling them apart. Left
            blank on the others, the kind names itself.
          example: Business registration
        description:
          type: string
          description: Instructions shown to the seller.
          example: A copy of your certificate of incorporation.
        position:
          type: integer
          description: Place in the checklist.
          example: 1
        active:
          type: boolean
          example: true
        required:
          type: boolean
          description: Whether this blocks approval. Off means recommended.
          example: true
        preferences:
          type: object
          additionalProperties: true
          description: Configuration for this kind, per its type's `schema`.
          example:
            accepted_content_types:
              - application/pdf
        metadata:
          type: object
          additionalProperties: true
        custom_field_definition_ids:
          type: array
          items:
            type: string
          description: >-
            Custom field definitions this requirement asks the seller to fill in
            (`required_custom_fields` kind).
    SellerRequirement:
      type: object
      properties:
        id:
          type: string
        position:
          type: number
        active:
          type: boolean
        required:
          type: boolean
        metadata:
          type: object
          nullable: true
        created_at:
          type: string
        updated_at:
          type: string
        kind:
          type: string
          description: >-
            Requirement kind. Built-in: accept_terms, complete_profile,
            billing_address, returns_address, delivery_method, package_type,
            minimum_products, payout_account, required_custom_fields, policy,
            attestation, operator_review, document. Extensions may register
            more.
        name:
          type: string
        description:
          type: string
          nullable: true
        preferences:
          $ref: '#/components/schemas/SellerRequirementPreferences'
        custom_field_definition_ids:
          type: array
          items:
            type: string
        allow_multiple:
          type: boolean
        accepts_submissions:
          type: boolean
        reviewed_by_operator:
          type: boolean
      required:
        - id
        - position
        - active
        - required
        - metadata
        - created_at
        - updated_at
        - kind
        - name
        - description
        - preferences
        - custom_field_definition_ids
        - allow_multiple
        - accepts_submissions
        - reviewed_by_operator
      x-typelizer: true
    SellerRequirementPreferences:
      description: >-
        Settings of a seller requirement, 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/SellerRequirementAcceptTermsPreferences'
        - $ref: '#/components/schemas/SellerRequirementAttestationPreferences'
        - $ref: '#/components/schemas/SellerRequirementBillingAddressPreferences'
        - $ref: '#/components/schemas/SellerRequirementCompleteProfilePreferences'
        - $ref: '#/components/schemas/SellerRequirementDeliveryMethodPreferences'
        - $ref: '#/components/schemas/SellerRequirementDocumentPreferences'
        - $ref: '#/components/schemas/SellerRequirementMinimumProductsPreferences'
        - $ref: '#/components/schemas/SellerRequirementOperatorReviewPreferences'
        - $ref: '#/components/schemas/SellerRequirementPackageTypePreferences'
        - $ref: '#/components/schemas/SellerRequirementPayoutAccountPreferences'
        - $ref: '#/components/schemas/SellerRequirementPolicyPreferences'
        - $ref: >-
            #/components/schemas/SellerRequirementRequiredCustomFieldsPreferences
        - $ref: '#/components/schemas/SellerRequirementReturnsAddressPreferences'
        - type: object
          additionalProperties: true
      x-spree-preferences-by-type:
        accept_terms: '#/components/schemas/SellerRequirementAcceptTermsPreferences'
        attestation: '#/components/schemas/SellerRequirementAttestationPreferences'
        billing_address: '#/components/schemas/SellerRequirementBillingAddressPreferences'
        complete_profile: '#/components/schemas/SellerRequirementCompleteProfilePreferences'
        delivery_method: '#/components/schemas/SellerRequirementDeliveryMethodPreferences'
        document: '#/components/schemas/SellerRequirementDocumentPreferences'
        minimum_products: '#/components/schemas/SellerRequirementMinimumProductsPreferences'
        operator_review: '#/components/schemas/SellerRequirementOperatorReviewPreferences'
        package_type: '#/components/schemas/SellerRequirementPackageTypePreferences'
        payout_account: '#/components/schemas/SellerRequirementPayoutAccountPreferences'
        policy: '#/components/schemas/SellerRequirementPolicyPreferences'
        required_custom_fields: '#/components/schemas/SellerRequirementRequiredCustomFieldsPreferences'
        returns_address: '#/components/schemas/SellerRequirementReturnsAddressPreferences'
    SellerRequirementAcceptTermsPreferences:
      type: object
      properties:
        terms_body:
          type: string
          x-spree-widget: textarea
          nullable: true
        terms_effective_from:
          type: string
          format: date
          nullable: true
        terms_url:
          type: string
          nullable: true
      additionalProperties: false
    SellerRequirementAttestationPreferences:
      type: object
      properties: {}
      additionalProperties: false
    SellerRequirementBillingAddressPreferences:
      type: object
      properties: {}
      additionalProperties: false
    SellerRequirementCompleteProfilePreferences:
      type: object
      properties:
        require_about:
          type: boolean
          default: true
        require_logo:
          type: boolean
          default: true
        require_cover_photo:
          type: boolean
          default: false
        require_contact_email:
          type: boolean
          default: true
      additionalProperties: false
    SellerRequirementDeliveryMethodPreferences:
      type: object
      properties: {}
      additionalProperties: false
    SellerRequirementDocumentPreferences:
      type: object
      properties: {}
      additionalProperties: false
    SellerRequirementMinimumProductsPreferences:
      type: object
      properties:
        minimum_count:
          type: integer
          default: 1
      additionalProperties: false
    SellerRequirementOperatorReviewPreferences:
      type: object
      properties: {}
      additionalProperties: false
    SellerRequirementPackageTypePreferences:
      type: object
      properties: {}
      additionalProperties: false
    SellerRequirementPayoutAccountPreferences:
      type: object
      properties: {}
      additionalProperties: false
    SellerRequirementPolicyPreferences:
      type: object
      properties: {}
      additionalProperties: false
    SellerRequirementRequiredCustomFieldsPreferences:
      type: object
      properties: {}
      additionalProperties: false
    SellerRequirementReturnsAddressPreferences:
      type: object
      properties: {}
      additionalProperties: false
  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.