> ## Documentation Index
> Fetch the complete documentation index at: https://dev.puppetvendors.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create user (vendor-scoped)

> Create a new user account. **Merchant scope only**.



## OpenAPI

````yaml openapi-merchant.json POST /users
openapi: 3.0.0
info:
  title: PuppetVendors Merchant API V2
  version: 2.0.0
  description: >-
    The endpoints reachable with a merchant API key (`mk_live_…`), minted from
    Settings → API Access in the PuppetVendors admin. A merchant key administers
    users and vendors, and renews its own token. Everything else in the V2 API,
    including orders, products, payouts, fulfillments and documents, stays on
    the v1 API token and is refused here with a 403. Keys are revealed once at
    creation; rotating one leaves the previous key working for a 24 hour grace
    window.
  contact:
    name: PuppetVendors Support
    url: https://puppetvendors.com
  license:
    name: Proprietary
servers:
  - url: https://production-api.puppetvendors.com
    description: Production
  - url: http://localhost:8082
    description: Local development
security:
  - bearerAuth: []
tags:
  - name: Auth
    description: Authentication endpoints for obtaining and refreshing API tokens
  - name: Portal - Auth
    description: Vendor portal authentication endpoints (vendor user login, token refresh)
  - name: Products
    description: Product management and synchronization
  - name: Orders
    description: Order retrieval and management
  - name: Payouts
    description: Vendor payout information
  - name: Fulfillments
    description: Order fulfillment operations
  - name: Reports
    description: Vendor sales reports and analytics
  - name: Vendors
    description: Vendor management operations
  - name: Settings
    description: Settings endpoints for vendor configuration and management
  - name: Users
    description: User account management
  - name: Shop
    description: Shop configuration and settings
  - name: Commissions
    description: Commission rate management
  - name: Integrations
    description: Vendor integration configuration endpoints
  - name: Line Items
    description: Order line item operations
paths:
  /users:
    post:
      tags:
        - Users
      summary: Create user (vendor-scoped)
      description: Create a new user account. **Merchant scope only**.
      operationId: createUserVendorScope
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRequest'
            example:
              email: user@example.com
              name: John Doe
              password: securePassword123
              type: vendor
              vendorId: 507f1f77bcf86cd799439011
              approved: true
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/User'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Merchant scope required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict - Email already in use
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    UserRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          description: User email address
          example: user@example.com
        name:
          type: string
          description: User full name
          example: John Doe
        password:
          type: string
          format: password
          description: User password
          example: securePassword123
        type:
          type: string
          enum:
            - vendor
            - merchant
            - admin
          description: User type
          example: vendor
        vendorId:
          type: string
          description: Associated vendor ObjectId
          example: 507f1f77bcf86cd799439011
        approved:
          type: boolean
          description: Whether user is approved
          example: true
    User:
      type: object
      properties:
        _id:
          type: string
          description: User ObjectId
          example: 507f1f77bcf86cd799439012
        email:
          type: string
          format: email
          description: User email address
          example: user@example.com
        name:
          type: string
          description: User full name
          example: John Doe
        type:
          type: string
          enum:
            - vendor
            - merchant
            - admin
          description: User type
          example: vendor
        vendorId:
          type: string
          description: Associated vendor ObjectId (for vendor users)
          example: 507f1f77bcf86cd799439011
        approved:
          type: boolean
          description: Whether user is approved
          example: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          enum:
            - false
          description: Indicates the request failed
        error:
          type: object
          required:
            - message
          properties:
            message:
              type: string
              description: Human-readable error message
              example: Resource not found
            code:
              type: string
              description: >-
                Stable machine-readable error code. The frontend uses this as
                its localisation key (e.g. errors.api.<code>). Server errors
                always report INTERNAL_SERVER_ERROR.
              example: NOT_FOUND
            errorId:
              type: string
              description: >-
                Correlation id for support/log lookup. Present on opaque 5xx
                responses so a user can quote a reference for the underlying
                (server-side logged) error.
              example: err_1783365360839_j281w7b
            details:
              type: object
              description: >-
                Additional client-error context (e.g. field-level validation
                errors). Never populated for server errors.
  securitySchemes:
    bearerAuth:
      type: apiKey
      in: header
      name: x-access-token
      description: >-
        JWT minted from a merchant API key (`mk_live_…`) by POST /authenticate.
        Send the token value directly, with no "Bearer" prefix. Tokens last 14
        days and can be renewed at POST /refresh-token; revoking the key refuses
        the next request made with any token minted from it.

````