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

# Terminate a subscription

> Terminate a subscription. Three reasons are supported:

- `ORDINARY`: regular termination. `intended_end_at` is optional; when omitted, the plan's cancellation period applies.
- `MOVE_OUT`: special termination right tied to a move-out date. `intended_end_at` is mandatory and still has to leave the grid operator a few working days of notice.
- `WITHDRAWAL`: 14-day cooling-off period (Widerruf) after contract confirmation. The end date is calculated to comply with grid-operator notice periods.

All end dates in the request and response are **exclusive** midnight Europe/Berlin: from that moment the customer is no longer supplied. The customer's last day of supply is the day before the named date.

Every termination reason has to clear the grid operator's working-day notice; ORDINARY additionally has to respect the plan's cancellation period.

Conflict responses (`409`) carry a dedicated `errors[].code`:
- `invalid_termination_date` — the requested date is in the past or violates the plan's / grid operator's notice period.
- `withdrawal_not_allowed` — the 14-day withdrawal window has elapsed (or the subscription has no confirmed_at to count from).



## OpenAPI

````yaml /openapi/openapi.curie.json post /subscriptions/{id}/terminate
openapi: 3.0.0
info:
  title: Nomos API
  version: 2026-05-27.curie
servers:
  - url: https://api.nomos.energy
    description: production
security: []
tags:
  - name: Plans
  - name: Leads
  - name: Subscriptions
  - name: Customers
  - name: Usage
  - name: Prices
  - name: Invoices
  - name: Smart Meter Orders
  - name: Grid Fee Reductions
  - name: Market Partners
  - name: Events
  - name: Authentication
paths:
  /subscriptions/{id}/terminate:
    post:
      tags:
        - Subscriptions
      summary: Terminate a subscription
      description: >-
        Terminate a subscription. Three reasons are supported:


        - `ORDINARY`: regular termination. `intended_end_at` is optional; when
        omitted, the plan's cancellation period applies.

        - `MOVE_OUT`: special termination right tied to a move-out date.
        `intended_end_at` is mandatory and still has to leave the grid operator
        a few working days of notice.

        - `WITHDRAWAL`: 14-day cooling-off period (Widerruf) after contract
        confirmation. The end date is calculated to comply with grid-operator
        notice periods.


        All end dates in the request and response are **exclusive** midnight
        Europe/Berlin: from that moment the customer is no longer supplied. The
        customer's last day of supply is the day before the named date.


        Every termination reason has to clear the grid operator's working-day
        notice; ORDINARY additionally has to respect the plan's cancellation
        period.


        Conflict responses (`409`) carry a dedicated `errors[].code`:

        - `invalid_termination_date` — the requested date is in the past or
        violates the plan's / grid operator's notice period.

        - `withdrawal_not_allowed` — the 14-day withdrawal window has elapsed
        (or the subscription has no confirmed_at to count from).
      parameters:
        - schema:
            type: string
            example: sub_mi4f0oda6x9m7gcsvjk0ole1
          required: true
          name: id
          in: path
      requestBody:
        description: The termination request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TerminateSubscription'
      responses:
        '200':
          description: The subscription's termination details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TerminateSubscriptionResponse'
        '400':
          description: >-
            The server cannot or will not process the request due to something
            that is perceived to be a client error (e.g., malformed request
            syntax, invalid request message framing, or deceptive request
            routing).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrBadRequest'
        '401':
          description: The client must authenticate itself to get the requested response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrUnauthorized'
        '402':
          description: A higher pricing plan is required to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrPaymentRequired'
        '403':
          description: >-
            The client does not have the necessary permissions to access the
            resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrForbidden'
        '404':
          description: The server can't find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrNotFound'
        '405':
          description: The request method is not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrMethodNotAllowed'
        '409':
          description: >-
            The request could not be completed due to a conflict mainly due to
            unique constraints.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrConflict'
        '422':
          description: >-
            The request was well-formed but was unable to be followed due to
            semantic errors.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrUnprocessableEntity'
        '429':
          description: The client has sent too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrTooManyRequests'
        '500':
          description: >-
            The server has encountered a situation it doesn't know how to
            handle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrInternalServerError'
      security:
        - Bearer: []
components:
  schemas:
    TerminateSubscription:
      oneOf:
        - type: object
          properties:
            reason:
              type: string
              enum:
                - ORDINARY
            intended_end_at:
              type: string
              format: date-time
              description: >-
                Optional exclusive end timestamp. Must be exactly midnight
                Europe/Berlin (any zone offset accepted as long as the instant
                is 00:00 Berlin). From that moment the customer is no longer
                supplied; the last day of supply is the day before. When
                omitted, the plan's cancellation period applies.
              example: '2026-12-31T00:00:00+01:00'
          required:
            - reason
        - type: object
          properties:
            reason:
              type: string
              enum:
                - MOVE_OUT
            intended_end_at:
              type: string
              format: date-time
              description: >-
                Exclusive end timestamp for the move-out. Must be exactly
                midnight Europe/Berlin (any zone offset accepted as long as the
                instant is 00:00 Berlin). Mandatory for `MOVE_OUT`. Must respect
                the grid operator's working-day notice.
              example: '2026-12-31T00:00:00+01:00'
          required:
            - reason
            - intended_end_at
        - type: object
          properties:
            reason:
              type: string
              enum:
                - WITHDRAWAL
          required:
            - reason
    TerminateSubscriptionResponse:
      type: object
      properties:
        reason:
          type: string
          enum:
            - ORDINARY
            - MOVE_OUT
            - WITHDRAWAL
        intended_end_at:
          type: string
          format: date-time
          description: >-
            Customer-provided or system-calculated exclusive end timestamp at
            midnight Europe/Berlin. From this instant the customer is no longer
            supplied.
          example: '2026-12-31T00:00:00+01:00'
      required:
        - reason
        - intended_end_at
    ErrBadRequest:
      type: object
      properties:
        code:
          type: string
          enum:
            - BAD_REQUEST
          description: The error code related to the status code.
          example: BAD_REQUEST
        message:
          type: string
          description: A human readable message describing the issue.
          example: 'invalid_type in ''end'': Required'
        requestId:
          type: string
          description: The request id to be used for debugging and error reporting.
          example: 37a04f8f-e791-491c-81e1-86cd304649bb
        docs:
          type: string
          description: The docs related to the error code.
          example: https://docs.nomos.energy/api-references/errors/BAD_REQUEST
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - invalid_type
                  - too_big
                  - too_small
                  - invalid_format
                  - not_multiple_of
                  - unrecognized_keys
                  - invalid_union
                  - invalid_key
                  - invalid_element
                  - invalid_value
                  - custom
                  - unserviceable_zip
                  - ended_subscription
                  - duplicate_grid_reduction
                  - missing_smart_meter
                  - missing_module_1
                  - unsupported_product
                  - unsupported_meter_order
                  - duplicate_meter_order
                  - unsupported_meter
                  - out_of_period_meter_reading
                  - unsupported_meter_reading
                  - duplicate_customer_email
                  - invalid_iban
                  - upgrade_api_version
                  - withdrawal_not_allowed
                  - invalid_termination_date
                example: invalid_type
              field:
                type: string
                example: favoriteNumbers.1
              message:
                type: string
                example: 'Invalid input: expected string, received number'
            required:
              - code
              - field
              - message
          description: >-
            Per-field breakdown of a validation or business-rule failure.
            Omitted for API versions before the structured-errors cutoff.
      required:
        - code
        - message
        - requestId
        - docs
    ErrUnauthorized:
      type: object
      properties:
        code:
          type: string
          enum:
            - UNAUTHORIZED
          description: The error code related to the status code.
          example: UNAUTHORIZED
        message:
          type: string
          description: A human readable message describing the issue.
          example: Invalid or malformed token
        requestId:
          type: string
          description: The request id to be used for debugging and error reporting.
          example: 37a04f8f-e791-491c-81e1-86cd304649bb
        docs:
          type: string
          description: The docs related to the error code.
          example: https://docs.nomos.energy/api-references/errors/UNAUTHORIZED
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - invalid_type
                  - too_big
                  - too_small
                  - invalid_format
                  - not_multiple_of
                  - unrecognized_keys
                  - invalid_union
                  - invalid_key
                  - invalid_element
                  - invalid_value
                  - custom
                  - unserviceable_zip
                  - ended_subscription
                  - duplicate_grid_reduction
                  - missing_smart_meter
                  - missing_module_1
                  - unsupported_product
                  - unsupported_meter_order
                  - duplicate_meter_order
                  - unsupported_meter
                  - out_of_period_meter_reading
                  - unsupported_meter_reading
                  - duplicate_customer_email
                  - invalid_iban
                  - upgrade_api_version
                  - withdrawal_not_allowed
                  - invalid_termination_date
                example: invalid_type
              field:
                type: string
                example: favoriteNumbers.1
              message:
                type: string
                example: 'Invalid input: expected string, received number'
            required:
              - code
              - field
              - message
          description: >-
            Per-field breakdown of a validation or business-rule failure.
            Omitted for API versions before the structured-errors cutoff.
      required:
        - code
        - message
        - requestId
        - docs
    ErrPaymentRequired:
      type: object
      properties:
        code:
          type: string
          enum:
            - PAYMENT_REQUIRED
          description: The error code related to the status code.
          example: PAYMENT_REQUIRED
        message:
          type: string
          description: A human readable message describing the issue.
          example: Payment required
        requestId:
          type: string
          description: The request id to be used for debugging and error reporting.
          example: 37a04f8f-e791-491c-81e1-86cd304649bb
        docs:
          type: string
          description: The docs related to the error code.
          example: https://docs.nomos.energy/api-references/errors/PAYMENT_REQUIRED
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - invalid_type
                  - too_big
                  - too_small
                  - invalid_format
                  - not_multiple_of
                  - unrecognized_keys
                  - invalid_union
                  - invalid_key
                  - invalid_element
                  - invalid_value
                  - custom
                  - unserviceable_zip
                  - ended_subscription
                  - duplicate_grid_reduction
                  - missing_smart_meter
                  - missing_module_1
                  - unsupported_product
                  - unsupported_meter_order
                  - duplicate_meter_order
                  - unsupported_meter
                  - out_of_period_meter_reading
                  - unsupported_meter_reading
                  - duplicate_customer_email
                  - invalid_iban
                  - upgrade_api_version
                  - withdrawal_not_allowed
                  - invalid_termination_date
                example: invalid_type
              field:
                type: string
                example: favoriteNumbers.1
              message:
                type: string
                example: 'Invalid input: expected string, received number'
            required:
              - code
              - field
              - message
          description: >-
            Per-field breakdown of a validation or business-rule failure.
            Omitted for API versions before the structured-errors cutoff.
      required:
        - code
        - message
        - requestId
        - docs
    ErrForbidden:
      type: object
      properties:
        code:
          type: string
          enum:
            - FORBIDDEN
          description: The error code related to the status code.
          example: FORBIDDEN
        message:
          type: string
          description: A human readable message describing the issue.
          example: You are not allowed to access this resource
        requestId:
          type: string
          description: The request id to be used for debugging and error reporting.
          example: 37a04f8f-e791-491c-81e1-86cd304649bb
        docs:
          type: string
          description: The docs related to the error code.
          example: https://docs.nomos.energy/api-references/errors/FORBIDDEN
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - invalid_type
                  - too_big
                  - too_small
                  - invalid_format
                  - not_multiple_of
                  - unrecognized_keys
                  - invalid_union
                  - invalid_key
                  - invalid_element
                  - invalid_value
                  - custom
                  - unserviceable_zip
                  - ended_subscription
                  - duplicate_grid_reduction
                  - missing_smart_meter
                  - missing_module_1
                  - unsupported_product
                  - unsupported_meter_order
                  - duplicate_meter_order
                  - unsupported_meter
                  - out_of_period_meter_reading
                  - unsupported_meter_reading
                  - duplicate_customer_email
                  - invalid_iban
                  - upgrade_api_version
                  - withdrawal_not_allowed
                  - invalid_termination_date
                example: invalid_type
              field:
                type: string
                example: favoriteNumbers.1
              message:
                type: string
                example: 'Invalid input: expected string, received number'
            required:
              - code
              - field
              - message
          description: >-
            Per-field breakdown of a validation or business-rule failure.
            Omitted for API versions before the structured-errors cutoff.
      required:
        - code
        - message
        - requestId
        - docs
    ErrNotFound:
      type: object
      properties:
        code:
          type: string
          enum:
            - NOT_FOUND
          description: The error code related to the status code.
          example: NOT_FOUND
        message:
          type: string
          description: A human readable message describing the issue.
          example: Resource not found
        requestId:
          type: string
          description: The request id to be used for debugging and error reporting.
          example: 37a04f8f-e791-491c-81e1-86cd304649bb
        docs:
          type: string
          description: The docs related to the error code.
          example: https://docs.nomos.energy/api-references/errors/NOT_FOUND
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - invalid_type
                  - too_big
                  - too_small
                  - invalid_format
                  - not_multiple_of
                  - unrecognized_keys
                  - invalid_union
                  - invalid_key
                  - invalid_element
                  - invalid_value
                  - custom
                  - unserviceable_zip
                  - ended_subscription
                  - duplicate_grid_reduction
                  - missing_smart_meter
                  - missing_module_1
                  - unsupported_product
                  - unsupported_meter_order
                  - duplicate_meter_order
                  - unsupported_meter
                  - out_of_period_meter_reading
                  - unsupported_meter_reading
                  - duplicate_customer_email
                  - invalid_iban
                  - upgrade_api_version
                  - withdrawal_not_allowed
                  - invalid_termination_date
                example: invalid_type
              field:
                type: string
                example: favoriteNumbers.1
              message:
                type: string
                example: 'Invalid input: expected string, received number'
            required:
              - code
              - field
              - message
          description: >-
            Per-field breakdown of a validation or business-rule failure.
            Omitted for API versions before the structured-errors cutoff.
      required:
        - code
        - message
        - requestId
        - docs
    ErrMethodNotAllowed:
      type: object
      properties:
        code:
          type: string
          enum:
            - METHOD_NOT_ALLOWED
          description: The error code related to the status code.
          example: METHOD_NOT_ALLOWED
        message:
          type: string
          description: A human readable message describing the issue.
          example: Method not allowed
        requestId:
          type: string
          description: The request id to be used for debugging and error reporting.
          example: 37a04f8f-e791-491c-81e1-86cd304649bb
        docs:
          type: string
          description: The docs related to the error code.
          example: https://docs.nomos.energy/api-references/errors/METHOD_NOT_ALLOWED
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - invalid_type
                  - too_big
                  - too_small
                  - invalid_format
                  - not_multiple_of
                  - unrecognized_keys
                  - invalid_union
                  - invalid_key
                  - invalid_element
                  - invalid_value
                  - custom
                  - unserviceable_zip
                  - ended_subscription
                  - duplicate_grid_reduction
                  - missing_smart_meter
                  - missing_module_1
                  - unsupported_product
                  - unsupported_meter_order
                  - duplicate_meter_order
                  - unsupported_meter
                  - out_of_period_meter_reading
                  - unsupported_meter_reading
                  - duplicate_customer_email
                  - invalid_iban
                  - upgrade_api_version
                  - withdrawal_not_allowed
                  - invalid_termination_date
                example: invalid_type
              field:
                type: string
                example: favoriteNumbers.1
              message:
                type: string
                example: 'Invalid input: expected string, received number'
            required:
              - code
              - field
              - message
          description: >-
            Per-field breakdown of a validation or business-rule failure.
            Omitted for API versions before the structured-errors cutoff.
      required:
        - code
        - message
        - requestId
        - docs
    ErrConflict:
      type: object
      properties:
        code:
          type: string
          enum:
            - CONFLICT
          description: The error code related to the status code.
          example: CONFLICT
        message:
          type: string
          description: A human readable message describing the issue.
          example: Resource already exists
        requestId:
          type: string
          description: The request id to be used for debugging and error reporting.
          example: 37a04f8f-e791-491c-81e1-86cd304649bb
        docs:
          type: string
          description: The docs related to the error code.
          example: https://docs.nomos.energy/api-references/errors/CONFLICT
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - invalid_type
                  - too_big
                  - too_small
                  - invalid_format
                  - not_multiple_of
                  - unrecognized_keys
                  - invalid_union
                  - invalid_key
                  - invalid_element
                  - invalid_value
                  - custom
                  - unserviceable_zip
                  - ended_subscription
                  - duplicate_grid_reduction
                  - missing_smart_meter
                  - missing_module_1
                  - unsupported_product
                  - unsupported_meter_order
                  - duplicate_meter_order
                  - unsupported_meter
                  - out_of_period_meter_reading
                  - unsupported_meter_reading
                  - duplicate_customer_email
                  - invalid_iban
                  - upgrade_api_version
                  - withdrawal_not_allowed
                  - invalid_termination_date
                example: invalid_type
              field:
                type: string
                example: favoriteNumbers.1
              message:
                type: string
                example: 'Invalid input: expected string, received number'
            required:
              - code
              - field
              - message
          description: >-
            Per-field breakdown of a validation or business-rule failure.
            Omitted for API versions before the structured-errors cutoff.
      required:
        - code
        - message
        - requestId
        - docs
    ErrUnprocessableEntity:
      type: object
      properties:
        code:
          type: string
          enum:
            - UNPROCESSABLE_ENTITY
          description: The error code related to the status code.
          example: UNPROCESSABLE_ENTITY
        message:
          type: string
          description: A human readable message describing the issue.
          example: >-
            invalid_enum_value in 'status': Invalid enum value. Expected
            'pending' | 'active' | 'ended'
        requestId:
          type: string
          description: The request id to be used for debugging and error reporting.
          example: 37a04f8f-e791-491c-81e1-86cd304649bb
        docs:
          type: string
          description: The docs related to the error code.
          example: https://docs.nomos.energy/api-references/errors/UNPROCESSABLE_ENTITY
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - invalid_type
                  - too_big
                  - too_small
                  - invalid_format
                  - not_multiple_of
                  - unrecognized_keys
                  - invalid_union
                  - invalid_key
                  - invalid_element
                  - invalid_value
                  - custom
                  - unserviceable_zip
                  - ended_subscription
                  - duplicate_grid_reduction
                  - missing_smart_meter
                  - missing_module_1
                  - unsupported_product
                  - unsupported_meter_order
                  - duplicate_meter_order
                  - unsupported_meter
                  - out_of_period_meter_reading
                  - unsupported_meter_reading
                  - duplicate_customer_email
                  - invalid_iban
                  - upgrade_api_version
                  - withdrawal_not_allowed
                  - invalid_termination_date
                example: invalid_type
              field:
                type: string
                example: favoriteNumbers.1
              message:
                type: string
                example: 'Invalid input: expected string, received number'
            required:
              - code
              - field
              - message
          description: >-
            Per-field breakdown of a validation or business-rule failure.
            Omitted for API versions before the structured-errors cutoff.
      required:
        - code
        - message
        - requestId
        - docs
    ErrTooManyRequests:
      type: object
      properties:
        code:
          type: string
          enum:
            - TOO_MANY_REQUESTS
          description: The error code related to the status code.
          example: TOO_MANY_REQUESTS
        message:
          type: string
          description: A human readable message describing the issue.
          example: Wait 30 seconds before retrying.
        requestId:
          type: string
          description: The request id to be used for debugging and error reporting.
          example: 37a04f8f-e791-491c-81e1-86cd304649bb
        docs:
          type: string
          description: The docs related to the error code.
          example: https://docs.nomos.energy/api-references/errors/TOO_MANY_REQUESTS
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - invalid_type
                  - too_big
                  - too_small
                  - invalid_format
                  - not_multiple_of
                  - unrecognized_keys
                  - invalid_union
                  - invalid_key
                  - invalid_element
                  - invalid_value
                  - custom
                  - unserviceable_zip
                  - ended_subscription
                  - duplicate_grid_reduction
                  - missing_smart_meter
                  - missing_module_1
                  - unsupported_product
                  - unsupported_meter_order
                  - duplicate_meter_order
                  - unsupported_meter
                  - out_of_period_meter_reading
                  - unsupported_meter_reading
                  - duplicate_customer_email
                  - invalid_iban
                  - upgrade_api_version
                  - withdrawal_not_allowed
                  - invalid_termination_date
                example: invalid_type
              field:
                type: string
                example: favoriteNumbers.1
              message:
                type: string
                example: 'Invalid input: expected string, received number'
            required:
              - code
              - field
              - message
          description: >-
            Per-field breakdown of a validation or business-rule failure.
            Omitted for API versions before the structured-errors cutoff.
      required:
        - code
        - message
        - requestId
        - docs
    ErrInternalServerError:
      type: object
      properties:
        code:
          type: string
          enum:
            - INTERNAL_SERVER_ERROR
          description: The error code related to the status code.
          example: INTERNAL_SERVER_ERROR
        message:
          type: string
          description: A human readable message describing the issue.
          example: Internal Server Error
        requestId:
          type: string
          description: The request id to be used for debugging and error reporting.
          example: 37a04f8f-e791-491c-81e1-86cd304649bb
        docs:
          type: string
          description: The docs related to the error code.
          example: >-
            https://docs.nomos.energy/api-references/errors/INTERNAL_SERVER_ERROR
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - invalid_type
                  - too_big
                  - too_small
                  - invalid_format
                  - not_multiple_of
                  - unrecognized_keys
                  - invalid_union
                  - invalid_key
                  - invalid_element
                  - invalid_value
                  - custom
                  - unserviceable_zip
                  - ended_subscription
                  - duplicate_grid_reduction
                  - missing_smart_meter
                  - missing_module_1
                  - unsupported_product
                  - unsupported_meter_order
                  - duplicate_meter_order
                  - unsupported_meter
                  - out_of_period_meter_reading
                  - unsupported_meter_reading
                  - duplicate_customer_email
                  - invalid_iban
                  - upgrade_api_version
                  - withdrawal_not_allowed
                  - invalid_termination_date
                example: invalid_type
              field:
                type: string
                example: favoriteNumbers.1
              message:
                type: string
                example: 'Invalid input: expected string, received number'
            required:
              - code
              - field
              - message
          description: >-
            Per-field breakdown of a validation or business-rule failure.
            Omitted for API versions before the structured-errors cutoff.
      required:
        - code
        - message
        - requestId
        - docs
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````