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

# Update customer

> Update a customer's status, balance group, or metadata. Used to activate a pending customer, deactivate an existing one, change their balance group, or manage custom metadata. Metadata is merged on update — only provided keys are added or overwritten. Set a key's value to `null` to remove it.

Required scope: `customers:write`



## OpenAPI

````yaml patch /v1/customers/{customer_id}
openapi: 3.0.0
info:
  title: Otark BRP API
  description: >-
    API for Balancing Responsible Parties (BRPs) to manage contracts,
    transactions, nominations, and customers on the Otark platform.
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.otark.energy
    description: Production
security: []
tags:
  - name: Contracts
    description: Manage energy contracts (PPA, day-ahead, etc.)
  - name: Transactions
    description: Contractual energy volumes between buyer and seller
  - name: Nominations
    description: Net saldo aggregated by balance group
  - name: Customers
    description: Manage customers assigned to the BRP
paths:
  /v1/customers/{customer_id}:
    patch:
      tags:
        - Customers
      summary: Update customer
      description: >-
        Update a customer's status, balance group, or metadata. Used to activate
        a pending customer, deactivate an existing one, change their balance
        group, or manage custom metadata. Metadata is merged on update — only
        provided keys are added or overwritten. Set a key's value to `null` to
        remove it.


        Required scope: `customers:write`
      operationId: updateCustomer
      parameters:
        - name: customer_id
          in: path
          required: true
          description: Customer identifier
          schema:
            type: string
            example: cust_r8s9t0u1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerUpdate'
      responses:
        '200':
          description: Updated customer
          headers:
            x-ratelimit-limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            x-ratelimit-remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            x-ratelimit-reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CustomerUpdate:
      type: object
      description: >-
        Partial update for a customer. Metadata is merged — only provided keys
        are added or overwritten. Set a key to `null` to remove it. Sending
        read-only fields (`id`, `name`, `assigned_at`, `activated_at`,
        `created_at`) returns a `read_only_field` error.
      properties:
        status:
          type: string
          description: New customer status
          enum:
            - pending
            - active
            - deactivated
        balance_group:
          $ref: '#/components/schemas/BalanceGroup'
        metadata:
          type: object
          description: Key-value pairs to merge into existing metadata
          additionalProperties:
            type: string
            nullable: true
          example:
            customer_number: KD-2026-0815
            cost_center: CC-4200
    Customer:
      type: object
      description: A customer assigned to the BRP
      properties:
        id:
          type: string
          description: Unique customer identifier
          example: cust_r8s9t0u1
        name:
          type: string
          description: Customer display name
          example: SolarDach GmbH
        status:
          type: string
          description: Customer status
          enum:
            - pending
            - active
            - deactivated
          example: active
        balance_group:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/BalanceGroup'
        metadata:
          type: object
          description: BRP-defined key-value pairs (free-form)
          additionalProperties:
            type: string
          example:
            customer_number: KD-2026-0815
            cost_center: CC-4200
            region: NRW
        assigned_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the customer was assigned
          example: '2026-01-10T09:00:00Z'
        activated_at:
          type: string
          format: date-time
          nullable: true
          description: ISO 8601 timestamp when the customer was activated
          example: '2026-01-10T11:30:00Z'
        created_at:
          type: string
          format: date-time
          description: ISO 8601 creation timestamp
          example: '2026-01-10T09:00:00Z'
      required:
        - id
        - name
        - status
        - balance_group
        - metadata
        - assigned_at
        - created_at
    BalanceGroup:
      type: object
      description: A balance group assignment
      properties:
        eic:
          type: string
          description: EIC code (balance group)
          example: 11YSOLARDACH--A
        tso:
          type: string
          description: TSO
          enum:
            - DE_AMPRION
            - DE_TENNET
            - DE_TRANSNET_BW
            - DE_50HERTZ
          example: DE_AMPRION
      required:
        - eic
        - tso
    Problem:
      type: object
      description: >-
        Error response following [RFC 9457 — Problem Details for HTTP
        APIs](https://www.rfc-editor.org/rfc/rfc9457).
      properties:
        type:
          type: string
          format: uri
          description: Absolute URI identifying the problem class
          example: https://brp.otark.team/errors/balance_group_tso_not_enabled
        title:
          type: string
          description: >-
            Short human-readable label (stable across occurrences of the same
            type)
          example: Balance Group TSO Not Enabled
        status:
          type: integer
          description: HTTP status code
          example: 400
        detail:
          type: string
          description: Human-readable explanation for this specific occurrence
          example: >-
            The requested TSO is not enabled for this balance group. Enable it
            via the balance group settings first.
        instance:
          type: string
          description: URI identifying the specific request
          example: /v1/customers/cust_r8s9t0u1
        errors:
          type: array
          description: Field-level validation errors (present on validation failures)
          items:
            $ref: '#/components/schemas/ProblemFieldError'
      required:
        - type
        - title
        - status
    ProblemFieldError:
      type: object
      description: A single field-level validation error
      properties:
        field:
          type: string
          description: JSON path of the field that caused the error
          example: balance_group.tso
        code:
          type: string
          description: >-
            Machine-readable error code: `unknown_field`, `read_only_field`,
            `required`, `invalid_type`, `invalid_enum_value`, `invalid_format`,
            `invalid_literal`, `value_too_small`, `value_too_large`, or
            `validation_failed`
          example: invalid_enum_value
        message:
          type: string
          description: Human-readable description of the issue
          example: >-
            Invalid enum value. Expected 'DE_AMPRION' | 'DE_TENNET' |
            'DE_TRANSNET_BW' | 'DE_50HERTZ', received 'INVALID'
      required:
        - code
        - message
  headers:
    X-RateLimit-Limit:
      description: Maximum number of requests allowed per window
      schema:
        type: integer
        example: 300
    X-RateLimit-Remaining:
      description: Remaining requests in the current window
      schema:
        type: integer
        example: 299
    X-RateLimit-Reset:
      description: Seconds until the rate limit window resets
      schema:
        type: integer
        example: 60
  responses:
    BadRequest:
      description: Invalid request — validation error or business rule violation
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://brp.otark.team/errors/validation
            title: Validation Failed
            status: 400
            instance: /v1/customers/cust_r8s9t0u1
            errors:
              - field: balance_group.tso
                code: invalid_enum_value
                message: >-
                  Invalid enum value. Expected 'DE_AMPRION' | 'DE_TENNET' |
                  'DE_TRANSNET_BW' | 'DE_50HERTZ', received 'INVALID'
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://brp.otark.team/errors/invalid_api_key
            title: Invalid API Key
            status: 401
    Forbidden:
      description: API key lacks required scopes
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://brp.otark.team/errors/insufficient_scopes
            title: Insufficient API Key Scopes
            status: 403
            detail: >-
              Missing scope: customers:write. Please create a new API key with
              the required scopes.
    NotFound:
      description: Resource does not exist or caller has no access
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://brp.otark.team/errors/customer_not_found
            title: Customer Not Found
            status: 404
            instance: /v1/customers/cust_r8s9t0u1
    Conflict:
      description: State conflict — the operation cannot be completed in the current state
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://brp.otark.team/errors/already_active
            title: Customer Already Active
            status: 409
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key

````