> ## 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. # Create a smart meter order > Create a new meter order for a subscription. The subscription's plan must support a smart-meter product type. Not applicable for feed-in subscriptions, as a smart meter must be present before starting a feed-in subscription. From `2026-09-08.gauss`, a subscription that has ended is refused with `ended_subscription`, and one with `terminated_at` set with `terminated_subscription`. ## OpenAPI ````yaml /openapi/openapi.curie.json post /meter-orders 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: /meter-orders: post: tags: - Smart Meter Orders summary: Create a smart meter order description: >- Create a new meter order for a subscription. The subscription's plan must support a smart-meter product type. Not applicable for feed-in subscriptions, as a smart meter must be present before starting a feed-in subscription. From `2026-09-08.gauss`, a subscription that has ended is refused with `ended_subscription`, and one with `terminated_at` set with `terminated_subscription`. requestBody: description: The meter order to create required: true content: application/json: schema: $ref: '#/components/schemas/InsertMeterOrder' responses: '200': description: The created meter order details content: application/json: schema: $ref: '#/components/schemas/LegacyMeterOrder' '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: Missing subscription: $ref: '#/components/examples/400-missing-subscription' Not a subscription ID: summary: Not a subscription ID value: code: BAD_REQUEST message: 'Invalid string: must start with "sub_"' requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: >- https://docs.nomos.energy/api-references/errors/BAD_REQUEST errors: - code: invalid_format field: subscription message: 'Invalid string: must start with "sub_"' 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 /meter-orders 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: Order already exists: summary: Order already exists value: code: CONFLICT message: >- A meter order of type smart-meter-metrify already exists for this subscription requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/CONFLICT errors: - code: duplicate_meter_order field: '' message: >- A meter order of type smart-meter-metrify already exists for this subscription '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: InsertMeterOrder: type: object properties: subscription: type: string description: ID of the subscription to create the meter order for example: sub_mi4f0oda6x9m7gcsvjk0ole1 required: - subscription LegacyMeterOrder: type: object properties: object: type: string enum: - meter_order description: Type of the object, always 'meter_order' id: type: string description: Unique identifier for the meter order example: smo_mi4f0oda6x9m7gcsvjk0ole1 subscription: type: string description: ID of the subscription example: sub_mi4f0oda6x9m7gcsvjk0ole1 customer: type: string description: ID of the customer example: cus_mi4f0oda6x9m7gcsvjk0ole1 provider: type: string enum: - energy-metering - metrify - inexogy description: The smart meter provider example: energy-metering status: type: string enum: - waiting - ordered - checked - installation_planning - installation_scheduled - installation_waiting - installation_finished - activated - installed - pre_installed - cancelled - intended - blocked - blocked_wim description: >- Current status of the meter order. Possible values: - `waiting`: The customer has requested a smart meter - waiting to transfer the order to the meter provider (e.g. missing MaLo, MeLo,..) - `ordered`: We have transferred the order to the meter provider - `checked`: The meter provider did a smart meter check and confirmed to process the order - `installation_planning`: The meter provider is planning the installation (e.g. waiting for the customer to confirm the installation date) - `installation_scheduled`: The meter provider has scheduled the installation with the customer (e.g. waiting for the customer to confirm the installation date) - `installation_waiting`: The meter provider is waiting for the installation to start (e.g. waiting for the customer to confirm the installation date) - `installation_finished`: The meter provider has finished the installation and the new meter data has been transferred to the network operator - `activated`: The smart meter is activated and can be used for automatic consumption data transmission - `installed`: The smart meter is installed - `pre_installed`: There is already a smart meter installed - no installation is needed - `cancelled`: The order has been cancelled - `intended`: The customer shows interest but has not yet completed the order - `blocked`: The order is artificially blocked by our system - waiting for admin approval - `blocked_wim`: The smart meter is blocked in Wechselprozess im Messwesen (WiM) - waiting for the network operator to confirm the installation example: waiting created_at: anyOf: - type: string - type: string format: date-time description: Timestamp when the order was created example: '2024-03-14T12:00:00Z' updated_at: anyOf: - type: string - type: string format: date-time description: Timestamp when the order was last updated example: '2024-03-14T12:00:00Z' required: - object - id - subscription - customer - provider - status - created_at - updated_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-missing-subscription: summary: Missing subscription 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: subscription message: 'Invalid input: expected string, received undefined' 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.