> ## 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 request is invalid: a field fails validation, breaks a business rule, or the body is not valid JSON. `errors` lists every problem with its field. content: application/json: schema: $ref: '#/components/schemas/ErrBadRequest' examples: Move-out without end date: summary: Move-out without end date value: code: BAD_REQUEST message: 'Invalid input: expected string, received undefined' requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: >- https://docs.nomos.energy/api-references/errors/BAD_REQUEST errors: - code: invalid_type field: intended_end_at message: 'Invalid input: expected string, received undefined' End date not at midnight: summary: End date not at midnight value: code: BAD_REQUEST message: end_at must be exactly midnight Europe/Berlin requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: >- https://docs.nomos.energy/api-references/errors/BAD_REQUEST errors: - code: custom field: intended_end_at message: end_at must be exactly midnight Europe/Berlin Body is not valid JSON: $ref: '#/components/examples/400-body-is-not-valid-json' Unsupported version header: $ref: '#/components/examples/400-unsupported-version-header' '401': description: The access token is missing, expired or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrUnauthorized' examples: No token: $ref: '#/components/examples/401-no-token' Expired token: $ref: '#/components/examples/401-expired-token' Invalid token: $ref: '#/components/examples/401-invalid-token' '403': description: The access token is valid but not allowed to use this endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrForbidden' examples: Role without access: $ref: '#/components/examples/403-role-without-access' Token without scope: $ref: '#/components/examples/403-token-without-scope-2' Customer token without customer: $ref: '#/components/examples/403-customer-token-without-customer' '404': description: >- A resource in the path or the body does not exist or belongs to another organization, or the endpoint does not exist in the API version of your token. content: application/json: schema: $ref: '#/components/schemas/ErrNotFound' examples: Unknown subscription: $ref: '#/components/examples/404-unknown-subscription' Endpoint not in your API version: summary: Endpoint not in your API version value: code: NOT_FOUND message: >- There is no POST /subscriptions/{id}/terminate in API version 2025-12-01.chucky. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/NOT_FOUND '409': description: >- The request conflicts with the current state of a resource, for example a duplicate or a resource that has ended. content: application/json: schema: $ref: '#/components/schemas/ErrConflict' examples: Already terminated: summary: Already terminated value: code: CONFLICT message: Subscription is already terminated requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/CONFLICT '500': description: >- Something went wrong on our side. Retry later, and send us the `requestId` if it persists. content: application/json: schema: $ref: '#/components/schemas/ErrInternalServerError' examples: Unexpected error: $ref: '#/components/examples/500-unexpected-error' 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. 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 description: >- What is wrong with the field, such as `invalid_type` or `asset_not_found`. `x-extensible-enum` lists the values known today. New values can be added in any API version, so treat an unknown value like any other error of the response's status. example: invalid_type x-extensible-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 - incompatible_grid_reduction - unsupported_product - unsupported_meter_order - duplicate_meter_order - unsupported_meter - out_of_period_meter_reading - unsupported_meter_reading - duplicate_meter_reading - implausible_meter_reading - duplicate_customer_email - invalid_iban - upgrade_api_version - withdrawal_not_allowed - invalid_termination_date - subscription_not_started - terminated_subscription - missing_household - invalid_household_customer - invalid_household_meter - duplicate_consumption_subscription - invalid_inverter - read_only_asset - duplicate_external_id - asset_has_children - asset_decommissioned - asset_not_found - mixed_households - field_not_allowed - invalid_direction - duplicate_timestamp - asset_not_steerable - mode_not_allowed - slot_missing field: type: string example: customer.email message: type: string example: 'Invalid input: expected string, received undefined' 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. 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 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. 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 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. 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 description: >- What is wrong with the field, such as `invalid_type` or `asset_not_found`. `x-extensible-enum` lists the values known today. New values can be added in any API version, so treat an unknown value like any other error of the response's status. example: invalid_type x-extensible-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 - incompatible_grid_reduction - unsupported_product - unsupported_meter_order - duplicate_meter_order - unsupported_meter - out_of_period_meter_reading - unsupported_meter_reading - duplicate_meter_reading - implausible_meter_reading - duplicate_customer_email - invalid_iban - upgrade_api_version - withdrawal_not_allowed - invalid_termination_date - subscription_not_started - terminated_subscription - missing_household - invalid_household_customer - invalid_household_meter - duplicate_consumption_subscription - invalid_inverter - read_only_asset - duplicate_external_id - asset_has_children - asset_decommissioned - asset_not_found - mixed_households - field_not_allowed - invalid_direction - duplicate_timestamp - asset_not_steerable - mode_not_allowed - slot_missing field: type: string example: customer.email message: type: string example: 'Invalid input: expected string, received undefined' 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. 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 description: >- What is wrong with the field, such as `invalid_type` or `asset_not_found`. `x-extensible-enum` lists the values known today. New values can be added in any API version, so treat an unknown value like any other error of the response's status. example: invalid_type x-extensible-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 - incompatible_grid_reduction - unsupported_product - unsupported_meter_order - duplicate_meter_order - unsupported_meter - out_of_period_meter_reading - unsupported_meter_reading - duplicate_meter_reading - implausible_meter_reading - duplicate_customer_email - invalid_iban - upgrade_api_version - withdrawal_not_allowed - invalid_termination_date - subscription_not_started - terminated_subscription - missing_household - invalid_household_customer - invalid_household_meter - duplicate_consumption_subscription - invalid_inverter - read_only_asset - duplicate_external_id - asset_has_children - asset_decommissioned - asset_not_found - mixed_households - field_not_allowed - invalid_direction - duplicate_timestamp - asset_not_steerable - mode_not_allowed - slot_missing field: type: string example: customer.email message: type: string example: 'Invalid input: expected string, received undefined' 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. 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 required: - code - message - requestId - docs examples: 400-body-is-not-valid-json: summary: Body is not valid JSON value: code: BAD_REQUEST message: Malformed JSON in request body requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/BAD_REQUEST 400-unsupported-version-header: summary: Unsupported version header value: code: BAD_REQUEST message: Version header 2026-01-01.foo is invalid. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/BAD_REQUEST 401-no-token: summary: No token value: code: UNAUTHORIZED message: No authorization header provided. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/UNAUTHORIZED 401-expired-token: summary: Expired token value: code: UNAUTHORIZED message: Token expired requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/UNAUTHORIZED 401-invalid-token: summary: Invalid token value: code: UNAUTHORIZED message: Invalid or malformed token requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/UNAUTHORIZED 403-role-without-access: summary: Role without access value: code: FORBIDDEN message: Forbidden to access this route. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/FORBIDDEN 403-token-without-scope-2: summary: Token without scope value: code: FORBIDDEN message: 'Insufficient scope: write:* required.' requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/FORBIDDEN 403-customer-token-without-customer: summary: Customer token without customer value: code: FORBIDDEN message: Customer not found. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/FORBIDDEN 404-unknown-subscription: summary: Unknown subscription value: code: NOT_FOUND message: Subscription not found requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/NOT_FOUND 500-unexpected-error: summary: Unexpected error value: code: INTERNAL_SERVER_ERROR message: Internal Server Error requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/INTERNAL_SERVER_ERROR securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.