> ## 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 meter reading

> Submit a customer-reported analog meter reading. The reading is attributed to the meter that was installed on the reading date.



## OpenAPI

````yaml /openapi/openapi.curie.json post /meter-readings
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-readings:
    post:
      tags:
        - Usage
      summary: Create a meter reading
      description: >-
        Submit a customer-reported analog meter reading. The reading is
        attributed to the meter that was installed on the reading date.
      requestBody:
        description: Meter reading input
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/InsertMeterReading'
                - type: object
                  properties:
                    subscription:
                      type: string
                      description: The subscription the meter reading belongs to
                      example: sub_rocbrf1u5e48mm0reeqoag90
                  required:
                    - subscription
      responses:
        '200':
          description: Meter reading accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeterReading'
        '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 timestamp:
                  summary: Missing timestamp
                  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: timestamp
                        message: 'Invalid input: expected string, received undefined'
                Negative value:
                  summary: Negative value
                  value:
                    code: BAD_REQUEST
                    message: 'Too small: expected number to be >=0'
                    requestId: 37a04f8f-e791-491c-81e1-86cd304649bb
                    docs: >-
                      https://docs.nomos.energy/api-references/errors/BAD_REQUEST
                    errors:
                      - code: too_small
                        field: value
                        message: 'Too small: expected number to be >=0'
                Timestamp outside the subscription period:
                  summary: Timestamp outside the subscription period
                  value:
                    code: BAD_REQUEST
                    message: >-
                      Reading timestamp must be within the subscription period
                      and not in the future
                    requestId: 37a04f8f-e791-491c-81e1-86cd304649bb
                    docs: >-
                      https://docs.nomos.energy/api-references/errors/BAD_REQUEST
                    errors:
                      - code: out_of_period_meter_reading
                        field: timestamp
                        message: >-
                          Reading timestamp must be within the subscription
                          period and not in the future
                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:
                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-readings 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:
                Reading for this day exists:
                  summary: Reading for this day exists
                  value:
                    code: CONFLICT
                    message: A meter reading already exists for this day
                    requestId: 37a04f8f-e791-491c-81e1-86cd304649bb
                    docs: https://docs.nomos.energy/api-references/errors/CONFLICT
                    errors:
                      - code: duplicate_meter_reading
                        field: timestamp
                        message: A meter reading already exists for this day
        '422':
          description: >-
            A query parameter, such as a filter value or a date range, is
            invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrUnprocessableEntity'
              examples:
                Value below the last reading:
                  summary: Value below the last reading
                  value:
                    code: UNPROCESSABLE_ENTITY
                    message: >-
                      Reading value (1200) must be greater than or equal to the
                      last reported value (1250)
                    requestId: 37a04f8f-e791-491c-81e1-86cd304649bb
                    docs: >-
                      https://docs.nomos.energy/api-references/errors/UNPROCESSABLE_ENTITY
                    errors:
                      - code: too_small
                        field: value
                        message: >-
                          Reading value must be greater than or equal to the
                          last reported value
                Value above a later reading:
                  summary: Value above a later reading
                  value:
                    code: UNPROCESSABLE_ENTITY
                    message: >-
                      Reading value (1300) must be less than or equal to the
                      next reported value (1250)
                    requestId: 37a04f8f-e791-491c-81e1-86cd304649bb
                    docs: >-
                      https://docs.nomos.energy/api-references/errors/UNPROCESSABLE_ENTITY
                    errors:
                      - code: too_big
                        field: value
                        message: >-
                          Reading value must be less than or equal to the next
                          reported value
                Daily consumption over the maximum:
                  summary: Daily consumption over the maximum
                  value:
                    code: UNPROCESSABLE_ENTITY
                    message: >-
                      Reading implies a daily consumption above the plausible
                      maximum of 150 kWh per day
                    requestId: 37a04f8f-e791-491c-81e1-86cd304649bb
                    docs: >-
                      https://docs.nomos.energy/api-references/errors/UNPROCESSABLE_ENTITY
                    errors:
                      - code: implausible_meter_reading
                        field: value
                        message: >-
                          Reading implies a daily consumption above the
                          plausible maximum of 150 kWh per day
                Daily consumption out of range:
                  summary: Daily consumption out of range
                  value:
                    code: UNPROCESSABLE_ENTITY
                    message: >-
                      Reading implies a daily consumption outside the plausible
                      range compared to previous readings
                    requestId: 37a04f8f-e791-491c-81e1-86cd304649bb
                    docs: >-
                      https://docs.nomos.energy/api-references/errors/UNPROCESSABLE_ENTITY
                    errors:
                      - code: implausible_meter_reading
                        field: value
                        message: >-
                          Reading implies a daily consumption outside the
                          plausible range compared to previous readings
        '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:
    InsertMeterReading:
      type: object
      properties:
        value:
          type: number
          minimum: 0
          description: >-
            Cumulative meter value in kWh. A freshly exchanged meter may report
            0.
          example: 150
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the reading in UTC
          example: '2024-03-14T12:00:00Z'
        message:
          type: string
          maxLength: 500
          description: Optional message from the submitter
          example: Reading to start the subscription
      required:
        - value
        - timestamp
    MeterReading:
      type: object
      properties:
        object:
          type: string
          enum:
            - meter_reading
        id:
          type: string
          description: The unique identifier for the meter reading
          example: read_k3n9x2v7q1m8p4t6w0z5c2bd
        customer:
          type: string
          description: The unique identifier for the customer
          example: cus_a8n8ol7yd4h0wohx824f0bui
        subscription:
          type: string
          description: The unique identifier for the subscription
          example: sub_rocbrf1u5e48mm0reeqoag90
        meter:
          type: string
          description: The unique identifier for the meter
          example: mtr_azk4zue2ijx4ff1dbjt14m5h
        value:
          type: number
          description: The value of the meter reading
          example: 150
        timestamp:
          type: string
          format: date-time
          description: >-
            Timestamp get's always adjusted to the start of the day in
            Europe/Berlin
          example: '2024-03-13T23:00:00.000Z'
        type:
          type: string
          enum:
            - customer_report
            - grid_reading
            - grid_estimation
          description: The type of the meter reading
          example: customer_report
        created_at:
          type: string
          format: date-time
          example: '2024-03-14T12:00:03.512Z'
      required:
        - object
        - id
        - customer
        - subscription
        - meter
        - value
        - timestamp
        - type
        - created_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
    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.
        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
                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-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.