{"openapi":"3.0.0","info":{"title":"Nomos API","version":"2026-05-27.curie"},"servers":[{"url":"https://api.stage.nomos.energy","description":"production"}],"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"}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"Basic":{"type":"http","scheme":"basic"}},"schemas":{"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_meter_reading","implausible_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_meter_reading","implausible_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_meter_reading","implausible_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_meter_reading","implausible_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_meter_reading","implausible_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_meter_reading","implausible_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_meter_reading","implausible_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_meter_reading","implausible_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_meter_reading","implausible_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_meter_reading","implausible_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"]},"Customer":{"anyOf":[{"type":"object","properties":{"object":{"type":"string","enum":["customer"],"description":"Type of the object, always 'customer'"},"id":{"type":"string","description":"Unique identifier for the customer","example":"cus_mi4f0oda6x9m7gcsvjk0ole1"},"type":{"type":"string","enum":["person"],"default":"person","description":"Type of the customer, always 'person'"},"first_name":{"type":"string","minLength":1,"maxLength":100,"description":"Customer's first name","example":"John"},"last_name":{"type":"string","minLength":1,"maxLength":100,"description":"Customer's last name","example":"Doe"},"email":{"type":"string","format":"email","description":"Email address","example":"john.doe@example.com"},"vat_id":{"type":"string","nullable":true,"description":"VAT identification number (USt-IdNr.) of the customer","example":"DE123456789"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the customer was created","example":"2024-03-14T12:00:00Z"}},"required":["object","id","first_name","last_name","email","created_at"],"title":"Person"},{"type":"object","properties":{"object":{"type":"string","enum":["customer"],"description":"Type of the object, always 'customer'"},"id":{"type":"string","description":"Unique identifier for the customer","example":"cus_mi4f0oda6x9m7gcsvjk0ole1"},"type":{"type":"string","enum":["company"],"description":"Type of the customer, always 'company'"},"first_name":{"type":"string","minLength":1,"maxLength":100,"description":"First name of the customer","example":"John"},"last_name":{"type":"string","minLength":1,"maxLength":100,"description":"Last name of the customer","example":"Doe"},"company_name":{"type":"string","minLength":1,"maxLength":100,"description":"Company name","example":"Example GmbH"},"email":{"type":"string","format":"email","description":"Email address","example":"gmbh@example.com"},"vat_id":{"type":"string","nullable":true,"description":"VAT identification number (USt-IdNr.) of the customer","example":"DE123456789"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the customer was created","example":"2024-03-14T12:00:00Z"}},"required":["object","id","type","first_name","last_name","company_name","email","created_at"],"title":"Company"}]},"UpdateCustomer":{"type":"object","properties":{"first_name":{"type":"string","minLength":1,"maxLength":100,"description":"Customer's first name","example":"John"},"last_name":{"type":"string","minLength":1,"maxLength":100,"description":"Customer's last name","example":"Doe"},"company_name":{"type":"string","minLength":1,"maxLength":100,"description":"Company name. Only valid for company customers; must be non-empty when provided.","example":"Example GmbH"}},"example":{"first_name":"John","last_name":"Doe"}},"Subscription":{"type":"object","properties":{"object":{"type":"string","enum":["subscription"],"description":"Type of the object, always 'subscription'"},"id":{"type":"string","description":"Unique identifier for the subscription","example":"sub_rocbrf1u5e48mm0reeqoag90"},"plan":{"type":"string","description":"ID of the plan","example":"pln_ctj3tjzc7dywznuw1dy80lb3"},"customer":{"$ref":"#/components/schemas/Customer"},"address":{"$ref":"#/components/schemas/Address"},"meter":{"$ref":"#/components/schemas/Meter"},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"supplier":{"$ref":"#/components/schemas/Supplier"},"number":{"type":"string","nullable":true,"description":"Human-readable identifier for the subscription","example":"4X44EMKX"},"status":{"type":"string","enum":["pending","active","ended"],"description":"Status of the subscription","example":"active"},"estimated_usage":{"type":"number","description":"Estimated yearly usage in kWh, provided by the customer in the checkout."},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the subscription was created","example":"2024-03-14T12:00:00Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the subscription was updated","example":"2024-03-14T12:00:00Z"},"start_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when delivery was started / will start","example":"2024-03-14T12:00:00Z"},"terminated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when delivery was terminated","example":"2024-03-14T12:00:00Z"},"end_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the subscription was ended / will end","example":"2024-03-14T12:00:00Z"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Metadata of the subscription. Store any type of information, custom to your needs. E.g. the `user_id` of your in-house user. Restricted to 10KB.","example":{"utm_source":"google","utm_campaign":"campaign_name","user_id":"1234567890"}},"type":{"type":"string","enum":["consumption","feed_in"],"description":"Whether the subscription covers electricity consumption or feed-in. Feed-in subscriptions are only available from the 2026-05-27.curie API version onwards.","example":"consumption"},"billing_address":{"$ref":"#/components/schemas/Address"}},"required":["object","id","plan","customer","address","meter","payment_method","status","estimated_usage","created_at","updated_at","type","billing_address"]},"Address":{"type":"object","properties":{"object":{"type":"string","enum":["address"],"description":"Type of the object, always 'address'"},"id":{"type":"string","description":"Unique identifier for the address","example":"adr_mi4f0oda6x9m7gcsvjk0ole1"},"street":{"type":"string","minLength":1,"description":"Street name of the address","example":"Torstraße"},"house_number":{"type":"string","minLength":1,"description":"House number including any additions","example":"119"},"zip":{"type":"string","minLength":5,"description":"ZIP/Postal code","example":"10115"},"city":{"type":"string","minLength":1,"description":"City name","example":"Berlin"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the address was created","example":"2024-03-14T12:00:00Z"}},"required":["object","id","street","house_number","zip","city","created_at"]},"Meter":{"type":"object","properties":{"object":{"type":"string","enum":["meter"],"description":"Type of the object, always 'meter'"},"id":{"type":"string","description":"Unique identifier for the meter","example":"mtr_tihqsqnxx3xs1gonbnk0ccou"},"melo":{"type":"string","nullable":true,"description":"Metering Location ID","example":"DE0000001234567890"},"number":{"type":"string","minLength":1,"description":"Meter identification number","example":"1APA0195124010"},"type":{"type":"string","enum":["smart","analog"],"description":"Type of the meter. Must be 'smart' for feed-in plans","example":"smart"},"malo":{"type":"string","nullable":true,"description":"Market Location Identifier (MaLo) for the meter","example":"50491310272"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the meter was created","example":"2024-03-14T12:00:00Z"}},"required":["object","id","number","type","created_at"]},"PaymentMethod":{"type":"object","properties":{"object":{"type":"string","enum":["payment_method"],"description":"Type of the object, always 'payment_method'"},"id":{"type":"string","description":"Unique identifier for the payment method","example":"pm_adc9utqqpcp7tx054l7vg56s2"},"type":{"type":"string","enum":["sepa_debit"],"description":"Type of payment method - Currently only SEPA direct debit is supported","example":"sepa_debit"},"sepa_debit":{"type":"object","properties":{"iban":{"type":"string","description":"International Bank Account Number (IBAN) for SEPA direct debit, partially masked for security","example":"DE************6485"},"account_holder":{"type":"string","minLength":1,"description":"Full legal name of the bank account holder as registered with the bank","example":"John Doe"}},"required":["iban","account_holder"]},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the payment method was created","example":"2024-03-14T12:00:00Z"}},"required":["object","id","type","sepa_debit","created_at"]},"Supplier":{"type":"object","nullable":true,"properties":{"object":{"type":"string","enum":["supplier"],"description":"Type of the object, always 'supplier'"},"id":{"type":"string","description":"Unique identifier for the supplier","example":"mp_a0x6jm5h92wde6s5dnuvha4c"},"name":{"type":"string","minLength":1,"description":"Name of the energy supplier","example":"Sample Energy GmbH"},"country":{"type":"string","minLength":2,"maxLength":2,"description":"Two-letter country code","example":"DE"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the supplier was created","example":"2024-03-14T12:00:00Z"}},"required":["object","id","name","country","created_at"]},"UpdateSubscription":{"type":"object","properties":{"billing_address":{"$ref":"#/components/schemas/InsertAddress"},"payment_method":{"$ref":"#/components/schemas/InsertPaymentMethod"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Key-based metadata update. Keys sent here are merged onto the stored metadata; set a key to `null` to remove it. Send `metadata: null` to clear every key. Omit the field to leave the metadata unchanged. The resulting metadata is restricted to 10KB.","example":{"utm_source":"google","utm_campaign":"campaign_name","user_id":"1234567890"}}},"example":{"billing_address":{"street":"Torstraße","house_number":"119","zip":"10115","city":"Berlin"},"payment_method":{"type":"sepa_debit","sepa_debit":{"iban":"DE68500105178297336485","account_holder":"John Doe"}},"metadata":{"user_id":"1234567890"}}},"InsertAddress":{"type":"object","properties":{"street":{"type":"string","minLength":2,"maxLength":100,"pattern":"[a-zA-Z\\u00E4\\u00F6\\u00FC\\u00DF\\u00C4\\u00D6\\u00DC]","description":"Street name of the address","example":"Torstraße"},"house_number":{"type":"string","minLength":1,"maxLength":10,"pattern":"^[A-Za-z0-9\\-/\\s]+$","description":"House number including any additions","example":"119"},"zip":{"type":"string","minLength":5,"maxLength":5,"pattern":"^\\d+$","description":"ZIP/Postal code","example":"10115"},"city":{"type":"string","minLength":2,"maxLength":100,"pattern":"^[^\\d]*$","description":"City name","example":"Berlin"}},"required":["street","house_number","zip","city"],"description":"New billing address for the subscription"},"InsertPaymentMethod":{"type":"object","properties":{"type":{"type":"string","enum":["sepa_debit"],"description":"Type of payment method","example":"sepa_debit"},"sepa_debit":{"type":"object","properties":{"iban":{"type":"string","pattern":"^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$","description":"IBAN number","example":"DE68500105178297336485"},"account_holder":{"type":"string","minLength":1,"description":"Name of the account holder","example":"John Doe"}},"required":["iban","account_holder"]}},"required":["type","sepa_debit"],"description":"Attach a new SEPA direct-debit mandate. The new payment method replaces the subscription's current mandate."},"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"]},"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"]}]},"InvoiceUnion":{"oneOf":[{"$ref":"#/components/schemas/UsageInvoice"},{"$ref":"#/components/schemas/PrepaymentInvoice"},{"$ref":"#/components/schemas/VoidInvoice"}],"discriminator":{"propertyName":"type","mapping":{"usage":"#/components/schemas/UsageInvoice","prepayment":"#/components/schemas/PrepaymentInvoice","void":"#/components/schemas/VoidInvoice"}}},"UsageInvoice":{"type":"object","properties":{"object":{"type":"string","enum":["invoice"]},"id":{"type":"string","example":"inv_drjjua6ampd1op2fg98k89x8","description":"Unique identifier of the invoice."},"customer":{"type":"string","example":"cus_a8n8ol7yd4h0wohx824f0bui","description":"ID of the customer the invoice belongs to."},"subscription":{"type":"string","example":"sub_jd8mlscm062jb6ks50tck9gi","description":"ID of the subscription the invoice belongs to."},"invoice_number":{"type":"string","example":"H62SU12A-003","description":"Human-readable invoice number displayed on the invoice document"},"month":{"type":"number","example":4,"description":"Numeric month (1-12) for which the invoice is issued"},"year":{"type":"number","example":2025,"description":"Four-digit year for which the invoice is issued"},"period_start":{"type":"string","example":"2025-03-31T22:00:00Z","description":"Timestamp marking the beginning of the billing period (inclusive)"},"period_end":{"type":"string","example":"2025-04-30T22:00:00Z","description":"Timestamp marking the end of the billing period (exclusive)"},"period_number":{"type":"number","example":3,"description":"Sequential number of the billing period within the subscription (1-based)"},"status":{"type":"string","enum":["open","paid","voided"],"example":"open","description":"Current status of the invoice:"},"issued_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"example":"2024-03-14T12:00:00Z","description":"Timestamp when the invoice was issued"},"paid_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"example":"2024-03-14T12:00:00Z","description":"Timestamp when the invoice was paid"},"type":{"type":"string","enum":["usage"],"example":"usage","description":"Discriminator for usage invoices, which bill metered electricity consumption for the period."},"usage":{"type":"number","example":100,"description":"Total energy consumption in kilowatt-hours (kWh) during the billing period"},"total":{"type":"number","example":110.04,"description":"Total amount due in euros (EUR) including all fees, taxes, and energy costs"}},"required":["object","id","customer","subscription","invoice_number","month","year","period_start","period_end","period_number","status","type","usage","total"],"title":"Usage invoice"},"PrepaymentInvoice":{"type":"object","properties":{"object":{"type":"string","enum":["invoice"]},"id":{"type":"string","example":"inv_drjjua6ampd1op2fg98k89x8","description":"Unique identifier of the invoice."},"customer":{"type":"string","example":"cus_a8n8ol7yd4h0wohx824f0bui","description":"ID of the customer the invoice belongs to."},"subscription":{"type":"string","example":"sub_jd8mlscm062jb6ks50tck9gi","description":"ID of the subscription the invoice belongs to."},"invoice_number":{"type":"string","example":"H62SU12A-003","description":"Human-readable invoice number displayed on the invoice document"},"month":{"type":"number","example":4,"description":"Numeric month (1-12) for which the invoice is issued"},"year":{"type":"number","example":2025,"description":"Four-digit year for which the invoice is issued"},"period_start":{"type":"string","example":"2025-03-31T22:00:00Z","description":"Timestamp marking the beginning of the billing period (inclusive)"},"period_end":{"type":"string","example":"2025-04-30T22:00:00Z","description":"Timestamp marking the end of the billing period (exclusive)"},"period_number":{"type":"number","example":3,"description":"Sequential number of the billing period within the subscription (1-based)"},"status":{"type":"string","enum":["open","paid","voided","uncollectible"],"example":"open","description":"Current status of the invoice:"},"issued_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"example":"2024-03-14T12:00:00Z","description":"Timestamp when the invoice was issued"},"paid_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"example":"2024-03-14T12:00:00Z","description":"Timestamp when the invoice was paid"},"type":{"type":"string","enum":["prepayment"],"example":"prepayment","description":"Discriminator for prepayment invoices, which charge a fixed advance amount and carry no metered usage."},"total":{"type":"number","example":99,"description":"Prepayment amount due in euros (EUR), including taxes"}},"required":["object","id","customer","subscription","invoice_number","month","year","period_start","period_end","period_number","status","type","total"],"title":"Prepayment invoice"},"VoidInvoice":{"type":"object","properties":{"object":{"type":"string","enum":["invoice"]},"id":{"type":"string","example":"inv_drjjua6ampd1op2fg98k89x8","description":"Unique identifier of the invoice."},"customer":{"type":"string","example":"cus_a8n8ol7yd4h0wohx824f0bui","description":"ID of the customer the invoice belongs to."},"subscription":{"type":"string","example":"sub_jd8mlscm062jb6ks50tck9gi","description":"ID of the subscription the invoice belongs to."},"invoice_number":{"type":"string","example":"H62SU12A-003","description":"Human-readable invoice number displayed on the invoice document"},"month":{"type":"number","example":4,"description":"Numeric month (1-12) for which the invoice is issued"},"year":{"type":"number","example":2025,"description":"Four-digit year for which the invoice is issued"},"period_start":{"type":"string","example":"2025-03-31T22:00:00Z","description":"Timestamp marking the beginning of the billing period (inclusive)"},"period_end":{"type":"string","example":"2025-04-30T22:00:00Z","description":"Timestamp marking the end of the billing period (exclusive)"},"period_number":{"type":"number","example":3,"description":"Sequential number of the billing period within the subscription (1-based)"},"status":{"type":"string","enum":["open","paid","voided"],"example":"open","description":"Current status of the invoice:"},"issued_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"example":"2024-03-14T12:00:00Z","description":"Timestamp when the invoice was issued"},"paid_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"example":"2024-03-14T12:00:00Z","description":"Timestamp when the invoice was paid"},"type":{"type":"string","enum":["void"],"example":"void","description":"Discriminator for void invoices (Storno documents) that reverse a previously paid invoice."},"voids":{"type":"string","example":"inv_mi4f0oda6x9m7gcsvjk0ole1","description":"Identifier of the original invoice that this Storno document voids."},"total":{"type":"number","example":-99,"description":"Amount reversed in euros (EUR), including taxes. Typically negative."}},"required":["object","id","customer","subscription","invoice_number","month","year","period_start","period_end","period_number","status","type","voids","total"],"title":"Void invoice"},"Plan":{"type":"object","properties":{"object":{"type":"string","enum":["plan"]},"id":{"type":"string","example":"pln_bn1sny3aczwq5jkz8xcf4klf","description":"Unique identifier of the plan."},"name":{"type":"string","example":"Nomos Friends & Family","description":"Name of the plan."},"slug":{"type":"string","example":"nomos","description":"Unique slug of the plan. Used to generate the [slug].checkout.energy or [slug].customerportal.energy url."},"description":{"type":"string","example":"A plan for friends and family","description":"Description of the plan."},"price":{"type":"number","example":10.99,"description":"Monthly base fee charged excl. grid and metering operator fees, as well as taxes and levies. Includes VAT."},"currency":{"type":"string","example":"EUR","description":"Currency of the fees."},"created_at":{"type":"string","example":"2021-01-01T00:00:00.000Z","description":"Date and time when the plan was created."},"type":{"type":"string","enum":["consumption","feed_in"],"example":"consumption","description":"Whether the plan covers electricity consumption or feed-in. Feed-in plans are only available from the 2026-05-27.curie API version onwards."}},"required":["object","id","name","slug","description","price","currency","created_at","type"]},"Price":{"type":"object","properties":{"object":{"type":"string","enum":["price"]},"subscription":{"type":"string","example":"sub_rocbrf1u5e48mm0reeqoag90","description":"The id of the subscription"},"period":{"type":"object","properties":{"start":{"type":"string","example":"2025-04-01","description":"Start date of the period at 00:00:00 local time in UTC."},"end":{"type":"string","example":"2025-04-01","description":"End date of the period at 23:59:59 local time in UTC."}},"required":["start","end"]},"unit":{"type":"string","example":"ct/kWh","description":"The unit of the price"},"currency":{"type":"string","example":"EUR","description":"The currency of the price"},"resolution":{"type":"string","enum":["hourly","15min"],"example":"hourly","description":"The time resolution of the price data points"},"reference":{"type":"string","example":"EPEX Day-Ahead Hourly","description":"Reference market for electricity prices"},"items":{"type":"array","nullable":true,"items":{"type":"object","properties":{"timestamp":{"type":"string","description":"Timestamp for the price point in UTC","example":"2024-03-14T12:00:00Z"},"amount":{"type":"number","nullable":true,"description":"Total price per unit. In rare cases, the price might be null if parts of the price information is currently not available.","example":24.44},"components":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["electricity","grid","levies"],"description":"Type of price component","example":"electricity"},"amount":{"type":"number","nullable":true,"description":"Amount for this component","example":8.77}},"required":["type","amount"]},"description":"Breakdown of price components","example":[{"type":"electricity","amount":8.77},{"type":"grid","amount":9.47},{"type":"levies","amount":6.2}]}},"required":["timestamp","amount","components"]},"description":"List of price data points. Null if subscription is not active (either hasn't started yet or has ended).","example":[{"timestamp":"2024-01-31T00:00:00Z","amount":24.44,"components":[{"type":"electricity","amount":8.77},{"type":"grid","amount":9.47},{"type":"levies","amount":6.2}]},{"timestamp":"2024-01-31T01:00:00Z","amount":22.15,"components":[{"type":"electricity","amount":7.48},{"type":"grid","amount":9.47},{"type":"levies","amount":5.2}]},{"timestamp":"2024-01-31T02:00:00Z","amount":20.88,"components":[{"type":"electricity","amount":6.21},{"type":"grid","amount":9.47},{"type":"levies","amount":5.2}]},{"timestamp":"2024-01-31T03:00:00Z","amount":19.97,"components":[{"type":"electricity","amount":5.3},{"type":"grid","amount":9.47},{"type":"levies","amount":5.2}]},{"timestamp":"2024-01-31T04:00:00Z","amount":21.56,"components":[{"type":"electricity","amount":6.89},{"type":"grid","amount":9.47},{"type":"levies","amount":5.2}]}]}},"required":["object","subscription","period","unit","currency","resolution","reference","items"]},"Quote":{"type":"object","properties":{"object":{"type":"string","enum":["quote"]},"amount":{"type":"number","description":"Total amount of the quote","example":71.9},"currency":{"type":"string","enum":["EUR"],"description":"Currency of the quote"},"discount":{"$ref":"#/components/schemas/QuoteDiscount"},"components":{"type":"array","items":{"$ref":"#/components/schemas/QuoteComponent"},"description":"Components of the quote","example":[{"group":"base","amount":4.35,"quantity":1,"quantity_unit":"month","unit_amount":4.35,"subcomponents":[{"subgroup":"fee","name":"Grundgebühr","amount":10.99},{"subgroup":"grid","name":"Netzentgelte","amount":3.31},{"subgroup":"grid","name":"Pauschale Netzentgeltreduktion (§14a EnWG Modul 1)","amount":-11.21},{"subgroup":"metering","name":"Messstellengebühren","amount":1.26}]},{"group":"variable","amount":56.34,"quantity":208,"quantity_unit":"kWh","unit_amount":0.27042,"subcomponents":[{"subgroup":"energy","name":"EPEX Day-Ahead Preis (12m avg.)","amount":0.0877},{"subgroup":"grid","name":"Netzentgelte","amount":0.1111},{"subgroup":"levies","name":"Konzessionsabgabe","amount":0.0284},{"subgroup":"levies","name":"Stromsteuer","amount":0.0244},{"subgroup":"levies","name":"Offshore-Umlage","amount":0.0078},{"subgroup":"levies","name":"§19-NEV Umlage","amount":0.0077},{"subgroup":"levies","name":"KWK-Umlage","amount":0.0033}]}]},"quoted_at":{"type":"string","format":"date-time","example":"2024-10-30T16:04:06.122Z","description":"When this quote was generated"}},"required":["object","amount","currency","components","quoted_at"]},"QuoteDiscount":{"type":"object","properties":{"name":{"type":"string","description":"Name of the discount","example":"Early bird discount"},"amount_off":{"type":"number","description":"Amount off for the discount","example":10},"duration":{"type":"string","description":"Duration either 'once' or 'recurring'","example":"recurring"},"duration_in_months":{"type":"number","nullable":true,"description":"Duration in months for the discount if recurring","example":10},"regular_amount":{"type":"number","description":"Regular amount without the discount","example":60}},"required":["name","amount_off","duration","duration_in_months","regular_amount"]},"QuoteComponent":{"type":"object","properties":{"group":{"type":"string","enum":["base","variable"],"description":"Component group type","example":"base"},"amount":{"type":"number","description":"Total amount for this component group","example":5.5},"quantity":{"type":"number","description":"Quantity of the component group","example":1},"quantity_unit":{"type":"string","enum":["month","kWh"],"description":"Unit for the quantity","example":"month"},"unit_amount":{"type":"number","description":"Amount per unit for this component group","example":5.5},"subcomponents":{"type":"array","items":{"$ref":"#/components/schemas/QuoteSubcomponent"}}},"required":["group","amount","quantity","quantity_unit","unit_amount","subcomponents"]},"QuoteSubcomponent":{"type":"object","properties":{"subgroup":{"type":"string","enum":["fee","grid","metering","energy","levies"],"description":"Component subgroup type","example":"fee"},"name":{"type":"string","description":"Display name of the component"},"amount":{"type":"number","description":"Amount for this component"}},"required":["subgroup","name","amount"]},"InsertPersonCustomer":{"type":"object","properties":{"type":{"type":"string","enum":["person"],"default":"person","description":"Type of the customer, always 'person'"},"first_name":{"type":"string","minLength":1,"maxLength":100,"description":"Customer's first name","example":"John"},"last_name":{"type":"string","minLength":1,"maxLength":100,"description":"Customer's last name","example":"Doe"},"email":{"type":"string","format":"email","description":"Email address","example":"john.doe@example.com"},"vat_id":{"type":"string","minLength":1,"description":"VAT identification number (USt-IdNr.), stored on the customer","example":"DE123456789"}},"required":["first_name","last_name","email"],"title":"Person"},"InsertCompanyCustomer":{"type":"object","properties":{"type":{"type":"string","enum":["company"],"description":"Type of the customer, always 'company'"},"first_name":{"type":"string","minLength":1,"maxLength":100,"description":"First name of the customer","example":"John"},"last_name":{"type":"string","minLength":1,"maxLength":100,"description":"Last name of the customer","example":"Doe"},"company_name":{"type":"string","minLength":1,"maxLength":100,"description":"Company name","example":"Example GmbH"},"email":{"type":"string","format":"email","description":"Email address","example":"gmbh@example.com"},"vat_id":{"type":"string","minLength":1,"description":"VAT identification number (USt-IdNr.), stored on the customer. Required when the plan is a feed-in plan.","example":"DE123456789"}},"required":["type","first_name","last_name","company_name","email"],"title":"Company"},"InsertMeter":{"type":"object","properties":{"number":{"type":"string","minLength":1,"description":"Meter identification number","example":"1APA0195124010"},"type":{"type":"string","enum":["smart","analog"],"description":"Type of the meter. Must be 'smart' for feed-in plans","example":"smart"},"estimated_usage":{"type":"number","minimum":100,"description":"Estimated yearly consumption in kWh","example":2500},"malo":{"type":"string","nullable":true,"description":"Market Location Identifier (MaLo) for the meter","example":"50491310272"}},"required":["number","type","estimated_usage"]},"Lead":{"type":"object","properties":{"object":{"type":"string","enum":["lead"]},"id":{"type":"string","description":"Unique identifier for the lead","example":"lead_a8n8ol7yd4h0wohx824f0bui"},"subscription":{"type":"string","nullable":true,"description":"ID of the subscription, if the lead is converted to a subscription","example":"sub_a8n8ol7yd4h0wohx824f0bui"},"subscribed_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the lead was converted to a subscription","example":"2024-03-14T12:00:00Z"},"link":{"type":"string","description":"URL of the lead","example":"https://nomos.checkout.energy/?id=lead_a8n8ol7yd4h0wohx824f0bui"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the lead was created","example":"2024-03-14T12:00:00Z"},"created_by":{"type":"string","nullable":true,"description":"Email of the user who created the lead","example":"john.doe@example.com"},"last_visited_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the lead was last visited","example":"2024-03-14T12:00:00Z"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Metadata of the lead, can be internal data","example":{"utm_source":"google","utm_campaign":"campaign_name","user_id":"1234567890"}}},"required":["object","id","link","created_at"]},"InsertLead":{"type":"object","properties":{"plan":{"type":"string","description":"Plan ID","example":"pln_mi4f0oda6x9m7gcsvjk0ole1"},"customer":{"anyOf":[{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["person"],"default":"person","description":"Type of the customer, always 'person'"},"first_name":{"type":"string","minLength":1,"maxLength":100,"description":"Customer's first name","example":"John"},"last_name":{"type":"string","minLength":1,"maxLength":100,"description":"Customer's last name","example":"Doe"},"email":{"type":"string","format":"email","description":"Email address","example":"john.doe@example.com"}},"title":"Person"},{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["company"],"description":"Type of the customer, always 'company'"},"first_name":{"type":"string","minLength":1,"maxLength":100,"description":"First name of the customer","example":"John"},"last_name":{"type":"string","minLength":1,"maxLength":100,"description":"Last name of the customer","example":"Doe"},"company_name":{"type":"string","minLength":1,"maxLength":100,"description":"Company name","example":"Example GmbH"},"email":{"type":"string","format":"email","description":"Email address","example":"gmbh@example.com"}},"title":"Company"},{"nullable":true}]},"address":{"type":"object","properties":{"zip":{"type":"string","minLength":5,"description":"ZIP/Postal code","example":"10115"},"street":{"type":"string","nullable":true,"minLength":1,"description":"Street name of the address","example":"Torstraße"},"city":{"type":"string","nullable":true,"minLength":1,"description":"City name","example":"Berlin"},"house_number":{"type":"string","nullable":true,"minLength":1,"description":"House number including any additions","example":"119"}},"required":["zip"]},"meter":{"type":"object","properties":{"estimated_usage":{"type":"number","minimum":100,"description":"Estimated yearly consumption in kWh","example":2500},"type":{"type":"string","nullable":true,"enum":["smart","analog"],"description":"Type of the meter. Must be 'smart' for feed-in plans","example":"smart"},"number":{"type":"string","nullable":true,"minLength":1,"description":"Meter identification number","example":"1APA0195124010"}},"required":["estimated_usage"]},"payment_method":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["sepa_debit"],"default":"sepa_debit","description":"Type of payment method","example":"sepa_debit"},"sepa_debit":{"type":"object","properties":{"iban":{"type":"string","nullable":true,"pattern":"^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$","description":"IBAN number","example":"DE68500105178297336485"},"account_holder":{"type":"string","nullable":true,"minLength":1,"description":"Name of the account holder","example":"John Doe"}}}}},"previous_supplier":{"type":"string","nullable":true,"description":"ID of the previous supplier, possible to obtain via /suppliers. Only supported for consumption plans.","example":"mp_mi4f0oda6x9m7gcsvjk0ole1"},"next_possible_start":{"type":"boolean","nullable":true,"description":"If set to false we will request the cancellation of the previous supplier / grid operator signup to the date provided in intended_start_date. If set to true we will request the next possible date. ","example":true},"intended_start_date":{"type":"string","nullable":true,"format":"date","description":"Intended start date of the subscription. Must be a date in the future. For feed-in plans it must be the first day of a month, at least one month in the future; when omitted, the next possible production start date is used.","example":"2024-01-01"},"change_reason":{"type":"string","enum":["supplier_change","move_in"],"description":"Reason of changing the supplier","example":"supplier_change"},"created_by":{"type":"string","nullable":true,"description":"Email of the user who created the lead","example":"john.doe@example.com"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Metadata of the lead, can be internal data","example":{"utm_source":"google","utm_campaign":"campaign_name","user_id":"1234567890"}}},"required":["plan","address","meter"]},"MeterReading":{"type":"object","properties":{"object":{"type":"string","enum":["meter_reading"]},"id":{"type":"string","description":"The unique identifier for the meter reading","example":"mr_rocbrf1u5e48mm0reeqoag90"},"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"},"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"}},"required":["object","id","customer","subscription","meter","value","timestamp","type","created_at"]},"InsertMeterReading":{"type":"object","properties":{"value":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Cumulative meter value in kWh","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"]},"MarketPartner":{"type":"object","properties":{"object":{"type":"string","enum":["market_partner"]},"id":{"type":"string","example":"mp_a0x6jm5h92wde6s5dnuvha4c","description":"Unique identifier of the market partner."},"name":{"type":"string","example":"Nomos Friends & Family","description":"Name of the market partner."},"type":{"type":"string","enum":["supplier"],"example":"supplier","description":"Type of market partner."},"code":{"type":"string","example":"9903964000002","description":"Market partner code."},"code_type":{"type":"string","example":"BDEW","description":"Type of market partner code."},"country":{"type":"string","example":"DE","description":"Country of the market partner."},"created_at":{"type":"string","example":"2021-01-01T00:00:00.000Z","description":"Date and time when the market partner was created."}},"required":["object","id","name","type","code","code_type","country","created_at"]},"MeterOrder":{"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":"prdo_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":["created","placed","check_submitted","check_reviewed","scheduled","installed","activated","cancelled"],"description":"Lifecycle milestone of the meter order. Progresses roughly `created` → `placed` → `check_submitted` → `check_reviewed` → `scheduled` → `installed` → `activated`; `cancelled` is a terminal state.","example":"created"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the order was created","example":"2026-06-30T12:00:00Z"},"installed_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the smart meter was installed, or null if the order has not reached the installed milestone.","example":null},"activated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the smart meter began delivering readings, or null if the order has not been activated.","example":null},"cancelled_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the order was cancelled, or null if the order is not cancelled.","example":null},"cancelled_reason":{"type":"string","nullable":true,"enum":["pre_existing","customer_request",null],"description":"Why the order was cancelled: `pre_existing` when a smart meter was already installed at the location, `customer_request` when the customer or an operator cancelled the order. Null when the order is not cancelled.","example":null},"blocked_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the order was blocked, or null if the order is not blocked.","example":null},"blocked_reason":{"type":"string","nullable":true,"enum":["check_missing","grid_operator_registration",null],"description":"Why the order is blocked: `check_missing` when the smart-meter check has not been performed yet, `grid_operator_registration` when the grid operator registration is pending. Null when the order is not blocked.","example":null},"appointment_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Scheduled installation appointment, when the provider has communicated one. Null while no appointment is known.","example":null}},"required":["object","id","subscription","customer","provider","status","created_at","installed_at","activated_at","cancelled_at","cancelled_reason","blocked_at","blocked_reason","appointment_at"]},"GridFeeReduction":{"type":"object","properties":{"object":{"type":"string","enum":["grid_fee_reduction"],"description":"Type of the object, always 'grid_fee_reduction'"},"id":{"type":"string","description":"Unique identifier for the grid fee reduction","example":"prdo_mi4f0oda6x9m7gcsvjk0ole1"},"subscription":{"type":"string","description":"ID of the subscription","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"},"type":{"type":"string","enum":["enwg-14a-module-1","enwg-14a-module-2","enwg-14a-module-3"],"description":"Grid fee reduction module type according to §14a EnWG","example":"enwg-14a-module-1"},"status":{"type":"string","enum":["intended","ordered","rejected","activated","ended"],"description":"Current status of the grid fee reduction order","example":"intended"},"valid_from":{"type":"string","nullable":true,"format":"date-time","description":"Start date of the grid fee reduction validity period","example":"2024-03-14T12:00:00Z"},"valid_until":{"type":"string","nullable":true,"format":"date-time","description":"End date of the grid fee reduction validity period","example":"2024-03-14T12:00:00Z"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the grid fee reduction was created","example":"2024-03-14T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when the grid fee reduction was last updated","example":"2024-03-14T12:00:00Z"},"customer":{"type":"string","description":"ID of the customer the grid fee reduction belongs to","example":"cus_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["object","id","subscription","type","status","valid_from","valid_until","created_at","updated_at","customer"]},"InsertGridFeeReduction":{"type":"object","properties":{"subscription":{"type":"string","description":"ID of the subscription","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"},"type":{"type":"string","enum":["enwg-14a-module-1","enwg-14a-module-2","enwg-14a-module-3"],"description":"Grid fee reduction module type according to §14a EnWG","example":"enwg-14a-module-1"}},"required":["subscription","type"]},"InsertMeterOrder":{"type":"object","properties":{"subscription":{"type":"string","description":"ID of the subscription to create the meter order for","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["subscription"]},"Invoice":{"type":"object","properties":{"object":{"type":"string","enum":["invoice"]},"id":{"type":"string","example":"inv_drjjua6ampd1op2fg98k89x8","description":"Unique identifier of the invoice."},"invoice_number":{"type":"string","example":"H62SU12A-003","description":"Human-readable invoice number displayed on the invoice document"},"month":{"type":"number","example":4,"description":"Numeric month (1-12) for which the invoice is issued"},"year":{"type":"number","example":2025,"description":"Four-digit year for which the invoice is issued"},"period_start":{"type":"string","example":"2025-03-31T22:00:00Z","description":"Timestamp marking the beginning of the billing period (inclusive)"},"period_end":{"type":"string","example":"2025-04-30T22:00:00Z","description":"Timestamp marking the end of the billing period (exclusive)"},"period_number":{"type":"number","example":3,"description":"Sequential number of the billing period within the subscription (1-based)"},"status":{"type":"string","enum":["open","paid","voided"],"example":"open","description":"Current status of the invoice:"},"usage":{"type":"number","example":100,"description":"Total energy consumption in kilowatt-hours (kWh) during the billing period"},"total":{"type":"number","example":110.04,"description":"Total amount due in euros (EUR) including all fees, taxes, and energy costs"},"issued_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"example":"2024-03-14T12:00:00Z","description":"Timestamp when the invoice was issued"},"paid_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"example":"2024-03-14T12:00:00Z","description":"Timestamp when the invoice was paid"}},"required":["object","id","invoice_number","month","year","period_start","period_end","period_number","status","usage","total"]},"Event":{"oneOf":[{"$ref":"#/components/schemas/subscription.created"},{"$ref":"#/components/schemas/subscription.confirmed"},{"$ref":"#/components/schemas/subscription.activated"},{"$ref":"#/components/schemas/subscription.ended"},{"$ref":"#/components/schemas/subscription.terminated"},{"$ref":"#/components/schemas/invoice.created"},{"$ref":"#/components/schemas/invoice.paid"},{"$ref":"#/components/schemas/invoice.payment_failed"},{"$ref":"#/components/schemas/invoice.voided"},{"$ref":"#/components/schemas/invoice.uncollectible"},{"$ref":"#/components/schemas/meter_order.created"},{"$ref":"#/components/schemas/meter_order.placed"},{"$ref":"#/components/schemas/meter_order.check_submitted"},{"$ref":"#/components/schemas/meter_order.check_reviewed"},{"$ref":"#/components/schemas/meter_order.scheduled"},{"$ref":"#/components/schemas/meter_order.installed"},{"$ref":"#/components/schemas/meter_order.activated"},{"$ref":"#/components/schemas/meter_order.blocked"},{"$ref":"#/components/schemas/meter_order.cancelled"}],"discriminator":{"propertyName":"topic","mapping":{"subscription.created":"#/components/schemas/subscription.created","subscription.confirmed":"#/components/schemas/subscription.confirmed","subscription.activated":"#/components/schemas/subscription.activated","subscription.ended":"#/components/schemas/subscription.ended","subscription.terminated":"#/components/schemas/subscription.terminated","invoice.created":"#/components/schemas/invoice.created","invoice.paid":"#/components/schemas/invoice.paid","invoice.payment_failed":"#/components/schemas/invoice.payment_failed","invoice.voided":"#/components/schemas/invoice.voided","invoice.uncollectible":"#/components/schemas/invoice.uncollectible","meter_order.created":"#/components/schemas/meter_order.created","meter_order.placed":"#/components/schemas/meter_order.placed","meter_order.check_submitted":"#/components/schemas/meter_order.check_submitted","meter_order.check_reviewed":"#/components/schemas/meter_order.check_reviewed","meter_order.scheduled":"#/components/schemas/meter_order.scheduled","meter_order.installed":"#/components/schemas/meter_order.installed","meter_order.activated":"#/components/schemas/meter_order.activated","meter_order.blocked":"#/components/schemas/meter_order.blocked","meter_order.cancelled":"#/components/schemas/meter_order.cancelled"}}},"subscription.created":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["subscription.created"],"description":"Event type identifier","example":"subscription.created"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"subscription":{"type":"string","description":"ID of the subscription that was created","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"},"lead":{"type":"string","description":"ID of the lead that was converted to this subscription (if applicable)","example":"lead_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["subscription"],"description":"The context of the `subscription.created` event"}},"required":["id","topic","timestamp","context"]},"subscription.confirmed":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["subscription.confirmed"],"description":"Event type identifier","example":"subscription.confirmed"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"subscription":{"type":"string","description":"ID of the subscription that was confirmed","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["subscription"],"description":"The context of the `subscription.confirmed` event"}},"required":["id","topic","timestamp","context"]},"subscription.activated":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["subscription.activated"],"description":"Event type identifier","example":"subscription.activated"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"subscription":{"type":"string","description":"ID of the subscription that was active","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["subscription"],"description":"The context of the `subscription.activated` event"}},"required":["id","topic","timestamp","context"]},"subscription.ended":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["subscription.ended"],"description":"Event type identifier","example":"subscription.ended"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"subscription":{"type":"string","description":"ID of the subscription that was ended","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["subscription"],"description":"The context of the `subscription.ended` event"}},"required":["id","topic","timestamp","context"]},"subscription.terminated":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["subscription.terminated"],"description":"Event type identifier","example":"subscription.terminated"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"subscription":{"type":"string","description":"ID of the subscription that was terminated (cancelled)","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["subscription"],"description":"The context of the `subscription.terminated` event"}},"required":["id","topic","timestamp","context"]},"invoice.created":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["invoice.created"],"description":"Event type identifier","example":"invoice.created"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"invoice":{"type":"string","description":"ID of the invoice that was created","example":"inv_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["invoice"],"description":"The context of the `invoice.created` event"}},"required":["id","topic","timestamp","context"]},"invoice.paid":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["invoice.paid"],"description":"Event type identifier","example":"invoice.paid"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"invoice":{"type":"string","description":"ID of the invoice that was paid","example":"inv_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["invoice"],"description":"The context of the `invoice.paid` event"}},"required":["id","topic","timestamp","context"]},"invoice.payment_failed":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["invoice.payment_failed"],"description":"Event type identifier","example":"invoice.payment_failed"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"invoice":{"type":"string","description":"ID of the invoice whose payment attempt failed","example":"inv_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["invoice"],"description":"The context of the `invoice.payment_failed` event"}},"required":["id","topic","timestamp","context"]},"invoice.voided":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["invoice.voided"],"description":"Event type identifier","example":"invoice.voided"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"invoice":{"type":"string","description":"ID of the invoice that was voided","example":"inv_mi4f0oda6x9m7gcsvjk0ole1"},"voiding_invoice":{"type":"string","description":"ID of the offsetting voiding invoice","example":"inv_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["invoice","voiding_invoice"],"description":"The context of the `invoice.voided` event"}},"required":["id","topic","timestamp","context"]},"invoice.uncollectible":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["invoice.uncollectible"],"description":"Event type identifier","example":"invoice.uncollectible"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"invoice":{"type":"string","description":"ID of the invoice that was marked uncollectible","example":"inv_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["invoice"],"description":"The context of the `invoice.uncollectible` event"}},"required":["id","topic","timestamp","context"]},"meter_order.created":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["meter_order.created"],"description":"Event type identifier","example":"meter_order.created"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"meter_order":{"type":"string","description":"ID of the smart meter order that was created","example":"prdo_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["meter_order"],"description":"The context of the `meter_order.created` event"}},"required":["id","topic","timestamp","context"]},"meter_order.placed":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["meter_order.placed"],"description":"Event type identifier","example":"meter_order.placed"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"meter_order":{"type":"string","description":"ID of the smart meter order that was placed with the meter provider","example":"prdo_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["meter_order"],"description":"The context of the `meter_order.placed` event"}},"required":["id","topic","timestamp","context"]},"meter_order.check_submitted":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["meter_order.check_submitted"],"description":"Event type identifier","example":"meter_order.check_submitted"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"meter_order":{"type":"string","description":"ID of the smart meter order whose check request was submitted","example":"prdo_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["meter_order"],"description":"The context of the `meter_order.check_submitted` event"}},"required":["id","topic","timestamp","context"]},"meter_order.check_reviewed":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["meter_order.check_reviewed"],"description":"Event type identifier","example":"meter_order.check_reviewed"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"meter_order":{"type":"string","description":"ID of the smart meter order whose check was reviewed by the meter provider","example":"prdo_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["meter_order"],"description":"The context of the `meter_order.check_reviewed` event"}},"required":["id","topic","timestamp","context"]},"meter_order.scheduled":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["meter_order.scheduled"],"description":"Event type identifier","example":"meter_order.scheduled"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"meter_order":{"type":"string","description":"ID of the smart meter order that was scheduled for installation","example":"prdo_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["meter_order"],"description":"The context of the `meter_order.scheduled` event"}},"required":["id","topic","timestamp","context"]},"meter_order.installed":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["meter_order.installed"],"description":"Event type identifier","example":"meter_order.installed"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"meter_order":{"type":"string","description":"ID of the smart meter order whose meter was installed","example":"prdo_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["meter_order"],"description":"The context of the `meter_order.installed` event"}},"required":["id","topic","timestamp","context"]},"meter_order.activated":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["meter_order.activated"],"description":"Event type identifier","example":"meter_order.activated"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"meter_order":{"type":"string","description":"ID of the smart meter order whose meter was activated","example":"prdo_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["meter_order"],"description":"The context of the `meter_order.activated` event"}},"required":["id","topic","timestamp","context"]},"meter_order.blocked":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["meter_order.blocked"],"description":"Event type identifier","example":"meter_order.blocked"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"meter_order":{"type":"string","description":"ID of the smart meter order that was blocked","example":"prdo_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["meter_order"],"description":"The context of the `meter_order.blocked` event"}},"required":["id","topic","timestamp","context"]},"meter_order.cancelled":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["meter_order.cancelled"],"description":"Event type identifier","example":"meter_order.cancelled"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"meter_order":{"type":"string","description":"ID of the smart meter order that was cancelled","example":"prdo_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["meter_order"],"description":"The context of the `meter_order.cancelled` event"}},"required":["id","topic","timestamp","context"]},"LoadForecasts":{"type":"object","properties":{"scope":{"type":"string","enum":["subscription"]},"subscription":{"type":"string"},"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"},"total":{"type":"number"}},"required":["scope","subscription","start","end","total"]}},"parameters":{}},"paths":{"/plans":{"get":{"tags":["Plans"],"summary":"List plans","description":"Retrieve all plans with cursor pagination","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","nullable":true},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"nullable":true,"description":"**Filterable fields:**\n- `status` (string)\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"description":"**Filterable fields:**\n- `status` (string)\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"Retrieve all plans with cursor pagination","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/Plan"}},"next_page":{"type":"string","nullable":true,"example":"eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0="},"has_more":{"type":"boolean","default":false}},"required":["object","items"]}}}},"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"}}}}}}},"/plans/{id}":{"get":{"tags":["Plans"],"summary":"Retrieve a plan","description":"Retrieve a plan details by its id","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"pln_1"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve a plan details by its id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Plan"}}}},"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"}}}}}}},"/plans/{id}/quote":{"get":{"tags":["Plans"],"summary":"Retrieve a quote","description":"Retrieve a quote details by its id. All prices are inclusive of VAT, with one exception: feed-in payouts to a tax-exempt customer (`is_tax_exempt: true`, e.g. a Kleinunternehmer under § 19 UStG) are quoted without VAT, matching what the customer is later credited. The §14a EnWG module options only apply to consumption plans as feed-in plans do not pay grid fees.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"pln_1"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","example":"10115","description":"ZIP code for the delivery address"},"required":true,"description":"ZIP code for the delivery address","name":"zip_code","in":"query"},{"schema":{"type":"number","minimum":100,"maximum":50000,"description":"Annual electricity usage in kWh. Must be between 100 and 50000","example":2500},"required":true,"description":"Annual electricity usage in kWh. Must be between 100 and 50000","name":"usage","in":"query"},{"schema":{"type":"string","enum":["analog","smart"],"default":"analog","description":"Type of the meter","example":"analog"},"required":false,"description":"Type of the meter","name":"meter_type","in":"query"},{"schema":{"type":"boolean","nullable":true,"default":false,"description":"Whether to include §14a EnWG Module 1 (Pauschale Netzentgeltreduktion) in the quote. Only applicable to consumption plans; requests for feed-in plans are rejected with `400 BAD_REQUEST`.","example":true},"required":false,"description":"Whether to include §14a EnWG Module 1 (Pauschale Netzentgeltreduktion) in the quote. Only applicable to consumption plans; requests for feed-in plans are rejected with `400 BAD_REQUEST`.","name":"14a_module_1","in":"query"},{"schema":{"type":"boolean","nullable":true,"default":false,"description":"Whether to include §14a EnWG Module 2 (Prozentuale Netzentgeltreduktion) in the quote. Only applicable to consumption plans; requests for feed-in plans are rejected with `400 BAD_REQUEST`.","example":true},"required":false,"description":"Whether to include §14a EnWG Module 2 (Prozentuale Netzentgeltreduktion) in the quote. Only applicable to consumption plans; requests for feed-in plans are rejected with `400 BAD_REQUEST`.","name":"14a_module_2","in":"query"},{"schema":{"type":"boolean","description":"Whether the prospective customer is exempt from VAT. Private operators are typically exempt as Kleinunternehmer under [§ 19 UStG](https://www.gesetze-im-internet.de/ustg_1980/__19.html) when their revenue stayed under 25,000 EUR the previous year and stays under 100,000 EUR the current year; companies are not. Only affects feed-in plans. Consumption plans are always quoted inclusive of VAT.","example":false},"required":false,"description":"Whether the prospective customer is exempt from VAT. Private operators are typically exempt as Kleinunternehmer under [§ 19 UStG](https://www.gesetze-im-internet.de/ustg_1980/__19.html) when their revenue stayed under 25,000 EUR the previous year and stays under 100,000 EUR the current year; companies are not. Only affects feed-in plans. Consumption plans are always quoted inclusive of VAT.","name":"is_tax_exempt","in":"query"}],"responses":{"200":{"description":"Retrieve the quote details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"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"}}}}}}},"/leads":{"get":{"tags":["Leads"],"summary":"List leads","description":"Retrieve all leads with cursor pagination. Leads for feed-in plans are only available from the `2026-05-27.curie` API version onwards.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","nullable":true},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"nullable":true,"description":"**Filterable fields:**\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"description":"**Filterable fields:**\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"Retrieve all leads with cursor pagination. Leads for feed-in plans are only available from the `2026-05-27.curie` API version onwards.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"next_page":{"type":"string","nullable":true,"example":"eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0="},"has_more":{"type":"boolean","default":false}},"required":["object","items"]}}}},"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"}}}}}},"post":{"tags":["Leads"],"summary":"Create a lead","description":"This endpoint can be used to create a secure, pre-filled checkout link. The link (returned in the \"link\" property) contains all provided customer, address and meter data, allowing the prospect to finalize their signup with only providing the missing payment information, essentially enabling a 2-click checkout experience. Leads are tracked in the Nomos Dashboard for detailed conversion analytics. Leads can be created for both consumption and feed-in plans.","security":[{"Bearer":[]}],"requestBody":{"description":"The lead to create","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsertLead"}}}},"responses":{"200":{"description":"The created lead details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"}}}},"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"}}}}}}},"/leads/{id}":{"get":{"tags":["Leads"],"summary":"Retrieve a lead","description":"Retrieve lead details by its id","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"lead_mi4f0oda6x9m7gcsvjk0ole1"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve the lead details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"}}}},"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"}}}}}}},"/subscriptions/{id}":{"patch":{"tags":["Subscriptions"],"summary":"Update a subscription","description":"Update the editable fields of a subscription. Only the allow-listed properties may be changed; any other field is ignored. `billing_address` replaces the subscription's billing address (all of street, house number, zip, city are required); the address row is mutated in place, so a row shared across a customer's subscriptions changes everywhere it is referenced. `payment_method` attaches a new SEPA direct-debit mandate to the subscription, replacing the current mandate. `metadata` is merged key-by-key onto the stored metadata (a key set to `null` is removed; `metadata: null` clears every key). Returns the updated subscription.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"},"required":true,"name":"id","in":"path"}],"requestBody":{"description":"The subscription fields to update","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubscription"}}}},"responses":{"200":{"description":"The updated subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"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"}}}}}},"get":{"tags":["Subscriptions"],"summary":"Retrieve a subscription","description":"Retrieve a subscription details by its id","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve the subscription details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"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"}}}}}}},"/subscriptions/{id}/terminate":{"post":{"tags":["Subscriptions"],"summary":"Terminate a subscription","description":"Terminate a subscription. Three reasons are supported:\n\n- `ORDINARY`: regular termination. `intended_end_at` is optional; when omitted, the plan's cancellation period applies.\n- `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.\n- `WITHDRAWAL`: 14-day cooling-off period (Widerruf) after contract confirmation. The end date is calculated to comply with grid-operator notice periods.\n\nAll 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.\n\nEvery termination reason has to clear the grid operator's working-day notice; ORDINARY additionally has to respect the plan's cancellation period.\n\nConflict responses (`409`) carry a dedicated `errors[].code`:\n- `invalid_termination_date` — the requested date is in the past or violates the plan's / grid operator's notice period.\n- `withdrawal_not_allowed` — the 14-day withdrawal window has elapsed (or the subscription has no confirmed_at to count from).","security":[{"Bearer":[]}],"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"}}}}}}},"/subscriptions":{"get":{"tags":["Subscriptions"],"summary":"List subscriptions","description":"Retrieve all subscriptions","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","nullable":true},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"nullable":true,"description":"**Filterable fields:**\n- `status` (enum): pending, active, ended\n- `customer` (string)\n- `plan` (string)\n- `created_at` (date)\n- `updated_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"description":"**Filterable fields:**\n- `status` (enum): pending, active, ended\n- `customer` (string)\n- `plan` (string)\n- `created_at` (date)\n- `updated_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"Retrieve all subscriptions","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["subscription"],"description":"Type of the object, always 'subscription'"},"id":{"type":"string","description":"Unique identifier for the subscription","example":"sub_rocbrf1u5e48mm0reeqoag90"},"plan":{"type":"string","description":"ID of the plan","example":"pln_ctj3tjzc7dywznuw1dy80lb3"},"customer":{"type":"string","description":"ID of the customer","example":"cus_a8n8ol7yd4h0wohx824f0bui"},"address":{"type":"string","description":"ID of the address","example":"adr_a7gurqkul8lzzsy1pf9p9388"},"meter":{"type":"string","description":"ID of the meter","example":"mtr_azk4zue2ijx4ff1dbjt14m5h"},"payment_method":{"type":"string","description":"ID of the payment method","example":"pm_adc9utqqpcp7tx054l7vg56s2"},"supplier":{"type":"string","nullable":true,"description":"ID of the previous supplier","example":"mp_a0x6jm5h92wde6s5dnuvha4c"},"number":{"type":"string","nullable":true,"description":"Human-readable identifier for the subscription","example":"4X44EMKX"},"status":{"type":"string","enum":["pending","active","ended"],"description":"Status of the subscription","example":"active"},"estimated_usage":{"type":"number","description":"Estimated yearly usage in kWh, provided by the customer in the checkout."},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the subscription was created","example":"2024-03-14T12:00:00Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the subscription was updated","example":"2024-03-14T12:00:00Z"},"start_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when delivery was started / will start","example":"2024-03-14T12:00:00Z"},"terminated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when delivery was terminated","example":"2024-03-14T12:00:00Z"},"end_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the subscription was ended / will end","example":"2024-03-14T12:00:00Z"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Metadata of the subscription. Store any type of information, custom to your needs. E.g. the `user_id` of your in-house user. Restricted to 10KB.","example":{"utm_source":"google","utm_campaign":"campaign_name","user_id":"1234567890"}},"type":{"type":"string","enum":["consumption","feed_in"],"description":"Whether the subscription covers electricity consumption or feed-in. Feed-in subscriptions are only available from the 2026-05-27.curie API version onwards.","example":"consumption"},"billing_address":{"type":"string","description":"ID of the billing address","example":"adr_a7gurqkul8lzzsy1pf9p9388"}},"required":["object","id","plan","customer","address","meter","payment_method","status","estimated_usage","created_at","updated_at","type","billing_address"]}},"next_page":{"type":"string","nullable":true,"example":"eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0="},"has_more":{"type":"boolean","default":false}},"required":["object","items"]}}}},"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"}}}}}},"post":{"tags":["Subscriptions"],"summary":"Create a subscription","description":"Create a new subscription. The plan's direction decides which signup rules apply.\n\n**Consumption plans:**\n- `meter.type` may be `smart` or `analog`\n- `customer.vat_id` is optional\n- `intended_start_date` may be any future date; a date in the past is corrected to the next possible date, and when omitted, the next possible start date is used\n- `previous_supplier` may be set to cancel the customer's existing contract\n- `product_orders` may order a smart meter or §14a EnWG grid fee reductions, if the plan supports them\n\n**Feed-in plans:**\n- `meter.type` must be `smart`: a smart meter has to be installed before the signup\n- `customer.vat_id` is required when `customer.type` is `company`, optional for persons\n- `intended_start_date` must be the first day of a month, at least one month in the future; when omitted, the next possible production start date is used\n- `previous_supplier` is not required for previous EEG customers.\n- `product_orders` are not supported: §14a EnWG does not apply to feed-in, and the smart meter must already be present\n\nRequests that break one of these rules are rejected with `400 BAD_REQUEST` and a message naming the violated rule.","security":[{"Bearer":[]}],"requestBody":{"description":"The subscription to create","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string","description":"Plan ID","example":"pln_mi4f0oda6x9m7gcsvjk0ole1"},"customer":{"anyOf":[{"$ref":"#/components/schemas/InsertPersonCustomer"},{"$ref":"#/components/schemas/InsertCompanyCustomer"}]},"address":{"$ref":"#/components/schemas/InsertAddress"},"meter":{"$ref":"#/components/schemas/InsertMeter"},"payment_method":{"$ref":"#/components/schemas/InsertPaymentMethod"},"previous_supplier":{"type":"string","description":"ID of the previous supplier, possible to obtain via /suppliers. Only supported for consumption plans.","example":"mp_mi4f0oda6x9m7gcsvjk0ole1"},"next_possible_start":{"type":"boolean","description":"If set to false we will request the cancellation of the previous supplier / grid operator signup to the date provided in intended_start_date. If set to true we will request the next possible date. ","example":true},"intended_start_date":{"type":"string","format":"date","description":"Intended start date of the subscription. Must be a date in the future. For feed-in plans it must be the first day of a month, at least one month in the future; when omitted, the next possible production start date is used.","example":"2024-01-01"},"lead":{"type":"string","description":"Lead to track attribution of the subscription","example":"lead_mi4f0oda6x9m7gcsvjk0ole1"},"product_orders":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["smart-meter","14a_enwg"],"description":"Order type"},"14a_enwg":{"type":"object","properties":{"module_1":{"type":"boolean","description":"Order §14a EnWG Module 1 if the customer is applicable"},"module_2":{"type":"boolean","description":"Order §14a EnWG Module 2 if the customer is applicable"},"module_3":{"type":"boolean","description":"Order §14a EnWG Module 3 if the customer is applicable"}}}},"required":["type"]},"description":"Array of additional product orders. Each item has a 'type' and may include an additional object with the same name as the type for its details. Only supported for consumption plans: §14a EnWG does not apply to feed-in, and feed-in requires a smart meter before signup.","example":[{"type":"smart-meter"},{"type":"14a_enwg","14a_enwg":{"module_1":true}}]},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Metadata of the subscription. Store any type of information, custom to your needs. E.g. the `user_id` of your in-house user. Restricted to 10KB.","example":{"utm_source":"google","utm_campaign":"campaign_name","user_id":"1234567890"}}},"required":["plan","customer","address","meter","payment_method","next_possible_start"]}}}},"responses":{"200":{"description":"The created subscription details","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["subscription"],"description":"Type of the object, always 'subscription'"},"id":{"type":"string","description":"Unique identifier for the subscription","example":"sub_rocbrf1u5e48mm0reeqoag90"},"plan":{"type":"string","description":"ID of the plan","example":"pln_ctj3tjzc7dywznuw1dy80lb3"},"customer":{"type":"string","description":"ID of the customer","example":"cus_a8n8ol7yd4h0wohx824f0bui"},"address":{"type":"string","description":"ID of the address","example":"adr_a7gurqkul8lzzsy1pf9p9388"},"meter":{"type":"string","description":"ID of the meter","example":"mtr_azk4zue2ijx4ff1dbjt14m5h"},"payment_method":{"type":"string","description":"ID of the payment method","example":"pm_adc9utqqpcp7tx054l7vg56s2"},"supplier":{"type":"string","nullable":true,"description":"ID of the previous supplier","example":"mp_a0x6jm5h92wde6s5dnuvha4c"},"number":{"type":"string","nullable":true,"description":"Human-readable identifier for the subscription","example":"4X44EMKX"},"status":{"type":"string","enum":["pending","active","ended"],"description":"Status of the subscription","example":"active"},"estimated_usage":{"type":"number","description":"Estimated yearly usage in kWh, provided by the customer in the checkout."},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the subscription was created","example":"2024-03-14T12:00:00Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the subscription was updated","example":"2024-03-14T12:00:00Z"},"start_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when delivery was started / will start","example":"2024-03-14T12:00:00Z"},"terminated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when delivery was terminated","example":"2024-03-14T12:00:00Z"},"end_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the subscription was ended / will end","example":"2024-03-14T12:00:00Z"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Metadata of the subscription. Store any type of information, custom to your needs. E.g. the `user_id` of your in-house user. Restricted to 10KB.","example":{"utm_source":"google","utm_campaign":"campaign_name","user_id":"1234567890"}},"type":{"type":"string","enum":["consumption","feed_in"],"description":"Whether the subscription covers electricity consumption or feed-in. Feed-in subscriptions are only available from the 2026-05-27.curie API version onwards.","example":"consumption"},"billing_address":{"type":"string","description":"ID of the billing address","example":"adr_a7gurqkul8lzzsy1pf9p9388"}},"required":["object","id","plan","customer","address","meter","payment_method","status","estimated_usage","created_at","updated_at","type","billing_address"]}}}},"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"}}}}}}},"/customers/{id}":{"patch":{"tags":["Customers"],"summary":"Update a customer","description":"Update the editable fields of a customer. Only `first_name` and `last_name` may be changed; both are optional so a request may update just one. Returns the updated customer.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"cus_mi4f0oda6x9m7gcsvjk0ole1"},"required":true,"name":"id","in":"path"}],"requestBody":{"description":"The customer fields to update","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomer"}}}},"responses":{"200":{"description":"The updated customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"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"}}}}}},"get":{"tags":["Customers"],"summary":"Retrieve a customer","description":"Retrieve customer details by their id","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"cus_mi4f0oda6x9m7gcsvjk0ole1"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve the customer details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"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"}}}}}}},"/customers":{"get":{"tags":["Customers"],"summary":"List customers","description":"Retrieve all customers with cursor pagination","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","nullable":true},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"nullable":true,"description":"**Filterable fields:**\n- `email` (string)\n- `type` (string)\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"description":"**Filterable fields:**\n- `email` (string)\n- `type` (string)\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"Retrieve all customers with cursor pagination","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"next_page":{"type":"string","nullable":true,"example":"eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0="},"has_more":{"type":"boolean","default":false}},"required":["object","items"]}}}},"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"}}}}}}},"/subscriptions/{id}/usage":{"get":{"tags":["Usage"],"summary":"Retrieve usage data","description":"Retrieve the usage data for a subscription. Usage is the electricity consumed from the grid, or fed into the grid for feed-in subscriptions. Values are positive magnitudes for both directions; the direction comes from the plan. Results depend on the meter type.\n\n**Smart meters**:\nUsage data becomes available from 4pm on the following day. Metering Service Providers (MSB) might share preliminary values until replaced by final values up to the 8th working day of the following month. Data is available as soon as provided by the responsible MSB. Delays or missing data may occur.\n\n**Analog meters**:\nData is based on meter readings by customers and MSBs and available on a monthly level. In the absence of metering readings, Nomos creates a preliminary estimation at the end of each month. Subsequent meter readings take precedence over existing estimates and trigger invoice corrections if applicable.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"sub_ig1f5x45789r3ax7dlfff4q4"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["auto","15min","hour","day","week","month"],"default":"auto","example":"auto","description":"The resolution of the consumption. 'auto' will choose a good resolution based on the start and end date."},"required":false,"description":"The resolution of the consumption. 'auto' will choose a good resolution based on the start and end date.","name":"resolution","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2025-03-30","description":"The start date of the interval (inclusive). Defaults depend on the meter type.  \n        **Smart meters**: yesterday start of day (00:00:00) in the customers's timezone.\n        **Analog meters**: subscription start date or 12 months ago, whichever is later."},"required":false,"description":"The start date of the interval (inclusive). Defaults depend on the meter type.  \n        **Smart meters**: yesterday start of day (00:00:00) in the customers's timezone.\n        **Analog meters**: subscription start date or 12 months ago, whichever is later.","name":"start","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2025-03-31","description":"The end date of the interval (exclusive). Defaults depend on the meter type. \n        **Smart meters**: today start of day (00:00:00) in the customers's timezone.\n        **Analog meters**: latest available reading date."},"required":false,"description":"The end date of the interval (exclusive). Defaults depend on the meter type. \n        **Smart meters**: today start of day (00:00:00) in the customers's timezone.\n        **Analog meters**: latest available reading date.","name":"end","in":"query"}],"responses":{"200":{"description":"Retrieve the subscription usage","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["usage"]},"meter_type":{"type":"string","enum":["analog","smart"],"example":"smart","description":"The meter type. Smart meters record consumption data in 15min intervals, analog meter readings only get reported periodically by the metering operator or the customer."},"resolution":{"type":"string","enum":["15min","hour","day","week","month"],"example":"15min","description":"The resolution of the consumption. An optimal resolution will be chosen based on the start and end date if no `resolution` is provided in the query params."},"data":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","format":"date-time","description":"The start date of the consumption interval"},"usage":{"type":"number","description":"Consumption in kWh in the interval"},"type":{"type":"string","enum":["final","preliminary"],"description":"Preliminary values are still subject to change"}},"required":["start","usage","type"]},"example":[{"start":"2025-03-31T22:00:00.000Z","usage":0.2,"type":"final"},{"start":"2025-03-31T22:15:00.000Z","usage":0.15,"type":"final"},{"start":"2025-03-31T22:30:00.000Z","usage":0.18,"type":"final"},{"start":"2025-03-31T22:45:00.000Z","usage":0.12,"type":"final"},{"start":"2025-03-31T23:00:00.000Z","usage":0.1,"type":"final"},{"start":"2025-03-31T23:15:00.000Z","usage":0.08,"type":"final"},{"start":"2025-03-31T23:30:00.000Z","usage":0.09,"type":"final"},{"start":"2025-03-31T23:45:00.000Z","usage":0.11,"type":"final"},{"start":"2025-04-01T00:00:00.000Z","usage":0.13,"type":"final"},{"start":"2025-04-01T00:15:00.000Z","usage":0.14,"type":"final"},{"start":"2025-04-01T00:30:00.000Z","usage":0.16,"type":"final"},{"start":"2025-04-01T00:45:00.000Z","usage":0.17,"type":"final"},{"start":"2025-04-01T01:00:00.000Z","usage":0.19,"type":"final"},{"start":"2025-04-01T01:15:00.000Z","usage":0.21,"type":"final"},{"start":"2025-04-01T01:30:00.000Z","usage":0.23,"type":"final"},{"start":"2025-04-01T01:45:00.000Z","usage":0.25,"type":"final"},{"start":"2025-04-01T02:00:00.000Z","usage":0.28,"type":"final"},{"start":"2025-04-01T02:15:00.000Z","usage":0.31,"type":"final"},{"start":"2025-04-01T02:30:00.000Z","usage":0.34,"type":"final"},{"start":"2025-04-01T02:45:00.000Z","usage":0.37,"type":"final"},{"start":"2025-04-01T03:00:00.000Z","usage":0.41,"type":"final"},{"start":"2025-04-01T03:15:00.000Z","usage":0.45,"type":"final"},{"start":"2025-04-01T03:30:00.000Z","usage":0.49,"type":"final"},{"start":"2025-04-01T03:45:00.000Z","usage":0.53,"type":"final"},{"start":"2025-04-01T04:00:00.000Z","usage":0.58,"type":"final"},{"start":"2025-04-01T04:15:00.000Z","usage":0.63,"type":"final"},{"start":"2025-04-01T04:30:00.000Z","usage":0.68,"type":"final"},{"start":"2025-04-01T04:45:00.000Z","usage":0.73,"type":"final"},{"start":"2025-04-01T05:00:00.000Z","usage":0.79,"type":"final"},{"start":"2025-04-01T05:15:00.000Z","usage":0.85,"type":"final"},{"start":"2025-04-01T05:30:00.000Z","usage":0.91,"type":"final"},{"start":"2025-04-01T05:45:00.000Z","usage":0.97,"type":"final"},{"start":"2025-04-01T06:00:00.000Z","usage":1.04,"type":"final"},{"start":"2025-04-01T06:15:00.000Z","usage":1.11,"type":"final"},{"start":"2025-04-01T06:30:00.000Z","usage":1.18,"type":"final"},{"start":"2025-04-01T06:45:00.000Z","usage":1.25,"type":"final"},{"start":"2025-04-01T07:00:00.000Z","usage":1.32,"type":"final"},{"start":"2025-04-01T07:15:00.000Z","usage":1.39,"type":"final"},{"start":"2025-04-01T07:30:00.000Z","usage":1.46,"type":"final"},{"start":"2025-04-01T07:45:00.000Z","usage":1.53,"type":"final"},{"start":"2025-04-01T08:00:00.000Z","usage":1.6,"type":"final"},{"start":"2025-04-01T08:15:00.000Z","usage":1.67,"type":"final"},{"start":"2025-04-01T08:30:00.000Z","usage":1.74,"type":"final"},{"start":"2025-04-01T08:45:00.000Z","usage":1.81,"type":"final"},{"start":"2025-04-01T09:00:00.000Z","usage":1.88,"type":"final"},{"start":"2025-04-01T09:15:00.000Z","usage":1.95,"type":"final"},{"start":"2025-04-01T09:30:00.000Z","usage":2.02,"type":"final"},{"start":"2025-04-01T09:45:00.000Z","usage":2.09,"type":"final"},{"start":"2025-04-01T10:00:00.000Z","usage":2.16,"type":"final"},{"start":"2025-04-01T10:15:00.000Z","usage":2.23,"type":"final"},{"start":"2025-04-01T10:30:00.000Z","usage":2.3,"type":"final"},{"start":"2025-04-01T10:45:00.000Z","usage":2.37,"type":"final"},{"start":"2025-04-01T11:00:00.000Z","usage":2.44,"type":"final"},{"start":"2025-04-01T11:15:00.000Z","usage":2.51,"type":"final"},{"start":"2025-04-01T11:30:00.000Z","usage":2.58,"type":"final"},{"start":"2025-04-01T11:45:00.000Z","usage":2.65,"type":"final"},{"start":"2025-04-01T12:00:00.000Z","usage":2.72,"type":"final"},{"start":"2025-04-01T12:15:00.000Z","usage":2.79,"type":"final"},{"start":"2025-04-01T12:30:00.000Z","usage":2.86,"type":"final"},{"start":"2025-04-01T12:45:00.000Z","usage":2.93,"type":"final"},{"start":"2025-04-01T13:00:00.000Z","usage":3,"type":"final"},{"start":"2025-04-01T13:15:00.000Z","usage":3.07,"type":"final"},{"start":"2025-04-01T13:30:00.000Z","usage":3.14,"type":"final"},{"start":"2025-04-01T13:45:00.000Z","usage":3.21,"type":"final"},{"start":"2025-04-01T14:00:00.000Z","usage":3.28,"type":"final"},{"start":"2025-04-01T14:15:00.000Z","usage":3.35,"type":"final"},{"start":"2025-04-01T14:30:00.000Z","usage":3.42,"type":"final"},{"start":"2025-04-01T14:45:00.000Z","usage":3.49,"type":"final"},{"start":"2025-04-01T15:00:00.000Z","usage":3.56,"type":"final"},{"start":"2025-04-01T15:15:00.000Z","usage":3.63,"type":"final"},{"start":"2025-04-01T15:30:00.000Z","usage":3.7,"type":"final"},{"start":"2025-04-01T15:45:00.000Z","usage":3.77,"type":"final"},{"start":"2025-04-01T16:00:00.000Z","usage":3.84,"type":"final"},{"start":"2025-04-01T16:15:00.000Z","usage":3.91,"type":"final"},{"start":"2025-04-01T16:30:00.000Z","usage":3.98,"type":"final"},{"start":"2025-04-01T16:45:00.000Z","usage":4.05,"type":"final"},{"start":"2025-04-01T17:00:00.000Z","usage":4.12,"type":"final"},{"start":"2025-04-01T17:15:00.000Z","usage":4.19,"type":"final"},{"start":"2025-04-01T17:30:00.000Z","usage":4.26,"type":"final"},{"start":"2025-04-01T17:45:00.000Z","usage":4.33,"type":"final"},{"start":"2025-04-01T18:00:00.000Z","usage":4.4,"type":"final"},{"start":"2025-04-01T18:15:00.000Z","usage":4.47,"type":"final"},{"start":"2025-04-01T18:30:00.000Z","usage":4.54,"type":"final"},{"start":"2025-04-01T18:45:00.000Z","usage":4.61,"type":"final"},{"start":"2025-04-01T19:00:00.000Z","usage":4.68,"type":"final"},{"start":"2025-04-01T19:15:00.000Z","usage":4.75,"type":"final"},{"start":"2025-04-01T19:30:00.000Z","usage":4.82,"type":"final"},{"start":"2025-04-01T19:45:00.000Z","usage":4.89,"type":"final"},{"start":"2025-04-01T20:00:00.000Z","usage":4.96,"type":"final"},{"start":"2025-04-01T20:15:00.000Z","usage":5.03,"type":"final"},{"start":"2025-04-01T20:30:00.000Z","usage":5.1,"type":"final"},{"start":"2025-04-01T20:45:00.000Z","usage":5.17,"type":"final"},{"start":"2025-04-01T21:00:00.000Z","usage":5.24,"type":"final"},{"start":"2025-04-01T21:15:00.000Z","usage":5.31,"type":"final"},{"start":"2025-04-01T21:30:00.000Z","usage":5.38,"type":"final"},{"start":"2025-04-01T21:45:00.000Z","usage":5.45,"type":"final"}],"description":"The consumption of the meter"}},"required":["object","meter_type","resolution","data"]}}}},"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"}}}}}}},"/meter-readings":{"get":{"tags":["Usage"],"summary":"List meter readings","description":"Retrieve all meter readings for the organization with cursor pagination. Customer users will only see their own. Use filter[subscription][eq]=<id> to scope to a single subscription.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","nullable":true},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"nullable":true,"description":"**Filterable fields:**\n- `type` (string)\n- `subscription` (string)\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"description":"**Filterable fields:**\n- `type` (string)\n- `subscription` (string)\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"Retrieve all meter readings for the organization with cursor pagination. Customer users will only see their own. Use filter[subscription][eq]=<id> to scope to a single subscription.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/MeterReading"}},"next_page":{"type":"string","nullable":true,"example":"eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0="},"has_more":{"type":"boolean","default":false}},"required":["object","items"]}}}},"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"}}}}}},"post":{"tags":["Usage"],"summary":"Create a meter reading","description":"Submit a customer-reported analog meter reading for the active meter of a subscription.","security":[{"Bearer":[]}],"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 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"}}}}}}},"/load-forecasts":{"post":{"tags":["Usage"],"summary":"Create a load forecast","description":"This endpoint is used to transmit a load forecast for a subscription. Values must be submitted by 9:00 a.m. local time on the previous day to be considered in the day-ahead auction, and at least 15 minutes before delivery to be included in continuous intraday trading. Data points must be strictly consecutive and can only be provided for full days at a time (local time of the subscription).","security":[{"Bearer":[]}],"requestBody":{"description":"Load forecast input","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","enum":["subscription"],"description":"Reference point for the load forecast","example":"subscription"},"subscription":{"type":"string","description":"Required subscription ID when scope is 'subscription'","example":"sub_123456789"},"resolution":{"type":"string","enum":["15min"],"description":"Time resolution of the load forecast data points","example":"15min"},"unit":{"type":"string","enum":["KW"],"description":"Unit of measurement for the forecast values","example":"KW"},"data":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","format":"date-time","description":"Timestamp of the data point","example":"2025-03-31T22:00:00.000Z"},"value":{"type":"number","minimum":0,"description":"Power value at this timestamp. Must not be negative.","example":0.2}},"required":["start","value"]},"description":"Array of load forecast data points. Must be strictly consecutive with exactly 15-minute intervals and without overlaps or gaps and can only contain one data point per 15-minute interval.","example":[{"start":"2025-03-31T22:00:00.000Z","value":0.2},{"start":"2025-03-31T22:15:00.000Z","value":0.22}]}},"required":["scope","subscription","resolution","unit","data"]}}}},"responses":{"200":{"description":"Positive response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoadForecasts"}}}},"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"}}}}}}},"/subscriptions/{id}/prices":{"get":{"tags":["Prices"],"summary":"Retrieve a price time series","description":"Retrieve a price object for a given subscription. For a consumption subscription this is the variable price time series the customer pays and can optimize consumption against; for a feed-in subscription it is the payout the customer is credited per kWh, based on EPEX day-ahead spot prices and without grid fees. All prices are inclusive of VAT, except feed-in payouts to a VAT-exempt customer.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"sub_1"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2025-02-01","description":"Start date of the period at 00:00:00 in local time of the customer (format yyyy-mm-dd)"},"required":true,"description":"Start date of the period at 00:00:00 in local time of the customer (format yyyy-mm-dd)","name":"start","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2025-02-01","description":"End date of the period at 23:59:59 in local time of the customer (format yyyy-mm-dd)"},"required":true,"description":"End date of the period at 23:59:59 in local time of the customer (format yyyy-mm-dd)","name":"end","in":"query"}],"responses":{"200":{"description":"Retrieve the price details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}},"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"}}}}}}},"/invoices/{id}":{"get":{"tags":["Invoices"],"summary":"Retrieve an invoice","description":"Download the PDF of an invoice","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"inv_drjjua6ampd1op2fg98k89x8"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve the invoice details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceUnion"}}}},"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"}}}}}}},"/invoices":{"get":{"tags":["Invoices"],"summary":"List invoices","description":"Invoices summarise the amounts owed/payed for a subscription. Usage invoices (`type: \"usage\"`) bill the metered electricity consumption of a billing period and include all line items such as energy, grid fees and taxes. Prepayment invoices (`type: \"prepayment\"`) charge a fixed advance amount and carry no usage; an unpaid prepayment that is cancelled surfaces with `status: \"uncollectible\"`. Void invoices (`type: \"void\"`) are Storno documents that reverse a previously paid invoice and reference the original via `voids`. Voided originals are included with `status: \"voided\"`. The related PDFs are available via the `/invoices/{id}/file` endpoint. Customer users will only see their own. Use filter[subscription][eq]=<id> to scope to a single subscription.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","nullable":true},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"nullable":true,"description":"**Filterable fields:**\n- `status` (enum): open, paid, voided, uncollectible\n- `period_start` (date)\n- `period_end` (date)\n- `type` (enum): usage, prepayment, void\n- `subscription` (string)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"description":"**Filterable fields:**\n- `status` (enum): open, paid, voided, uncollectible\n- `period_start` (date)\n- `period_end` (date)\n- `type` (enum): usage, prepayment, void\n- `subscription` (string)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"Invoices summarise the amounts owed/payed for a subscription. Usage invoices (`type: \"usage\"`) bill the metered electricity consumption of a billing period and include all line items such as energy, grid fees and taxes. Prepayment invoices (`type: \"prepayment\"`) charge a fixed advance amount and carry no usage; an unpaid prepayment that is cancelled surfaces with `status: \"uncollectible\"`. Void invoices (`type: \"void\"`) are Storno documents that reverse a previously paid invoice and reference the original via `voids`. Voided originals are included with `status: \"voided\"`. The related PDFs are available via the `/invoices/{id}/file` endpoint. Customer users will only see their own. Use filter[subscription][eq]=<id> to scope to a single subscription.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceUnion"}},"next_page":{"type":"string","nullable":true,"example":"eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0="},"has_more":{"type":"boolean","default":false}},"required":["object","items"]}}}},"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"}}}}}}},"/invoices/{id}/file":{"get":{"tags":["Invoices"],"summary":"Retrieve an invoice PDF","description":"Retrieve a PDF file of an invoice from the storage","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"inv_drjjua6ampd1op2fg98k89x8","description":"The invoice id to access the pdf file"},"required":true,"description":"The invoice id to access the pdf file","name":"id","in":"path"}],"responses":{"302":{"description":"Redirect to the file. The link is valid for 1 hour."},"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"}}}}}}},"/meter-orders/{id}":{"get":{"tags":["Smart Meter Orders"],"summary":"Retrieve a smart meter order","description":"Retrieve a meter order by its ID","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"prdo_mi4f0oda6x9m7gcsvjk0ole1"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The meter order details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeterOrder"}}}},"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"}}}}}}},"/meter-orders":{"get":{"tags":["Smart Meter Orders"],"summary":"List smart meter orders","description":"Retrieve all meter orders for the organization","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","nullable":true},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"nullable":true,"description":"**Filterable fields:**\n- `status` (enum): created, placed, check_submitted, check_reviewed, scheduled, installed, activated, cancelled\n- `customer` (string)\n- `subscription` (string)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"description":"**Filterable fields:**\n- `status` (enum): created, placed, check_submitted, check_reviewed, scheduled, installed, activated, cancelled\n- `customer` (string)\n- `subscription` (string)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"Retrieve all meter orders for the organization","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/MeterOrder"}},"next_page":{"type":"string","nullable":true,"example":"eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0="},"has_more":{"type":"boolean","default":false}},"required":["object","items"]}}}},"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"}}}}}},"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.","security":[{"Bearer":[]}],"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/MeterOrder"}}}},"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"}}}}}}},"/grid-fee-reductions":{"get":{"tags":["Grid Fee Reductions"],"summary":"List grid fee reductions","description":"Retrieve all grid fee reductions for the organization. Customer users will only see their own.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","nullable":true},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"nullable":true,"description":"**Filterable fields:**\n- `status` (enum): intended, ordered, rejected, activated, ended\n- `customer` (string)\n- `subscription` (string)\n- `created_at` (date)\n- `updated_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"description":"**Filterable fields:**\n- `status` (enum): intended, ordered, rejected, activated, ended\n- `customer` (string)\n- `subscription` (string)\n- `created_at` (date)\n- `updated_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"Retrieve all grid fee reductions for the organization. Customer users will only see their own.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/GridFeeReduction"}},"next_page":{"type":"string","nullable":true,"example":"eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0="},"has_more":{"type":"boolean","default":false}},"required":["object","items"]}}}},"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"}}}}}},"post":{"tags":["Grid Fee Reductions"],"summary":"Create a grid fee reduction","description":"Create a new grid fee reduction for §14a EnWG modules. Not applicable for feed-in subscriptions, which do not pay grid fees.\n\n**Grid fee reduction status:**\n- If the subscription is active: grid fee reduction is created with `ordered` status. Order is submitted immediately\n- If the subscription is pending: grid fee reduction is created with `intended` status. Order will be submitted once the subscription is confirmed\n\n**Re-ordering after rejection:**\nRe-ordering is allowed if the previous grid fee reduction was rejected or ended.","security":[{"Bearer":[]}],"requestBody":{"description":"The grid fee reduction to create","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsertGridFeeReduction"}}}},"responses":{"200":{"description":"The newly created grid fee reduction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GridFeeReduction"}}}},"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"}}}}}}},"/grid-fee-reductions/{id}":{"get":{"tags":["Grid Fee Reductions"],"summary":"Retrieve a grid fee reduction","description":"Retrieve a grid reduction details by its id","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"prdo_mi4f0oda6x9m7gcsvjk0ole1"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve the grid fee reduction details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GridFeeReduction"}}}},"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"}}}}}}},"/market-partners":{"get":{"tags":["Market Partners"],"summary":"List market partners","description":"This is a list of all German electricity retailers, which a customer can select as their previous supplier in the checkout process. It can be used to build a dropdown menu in an embedded checkout to select the previous supplier.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","nullable":true},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"nullable":true,"description":"**Filterable fields:**\n- `name` (string)\n- `code` (string)\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"description":"**Filterable fields:**\n- `name` (string)\n- `code` (string)\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"This is a list of all German electricity retailers, which a customer can select as their previous supplier in the checkout process. It can be used to build a dropdown menu in an embedded checkout to select the previous supplier.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/MarketPartner"}},"next_page":{"type":"string","nullable":true,"example":"eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0="},"has_more":{"type":"boolean","default":false}},"required":["object","items"]}}}},"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"}}}}}}},"/events/{id}":{"get":{"tags":["Events"],"summary":"Retrieve an event","description":"Retrieve event details by their id","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve the event details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"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"}}}}}}},"/oauth/token":{"post":{"tags":["Authentication"],"summary":"Create a token","description":"Retrieve a token","security":[{"Basic":[]}],"requestBody":{"description":"The token request","content":{"application/json":{"schema":{"type":"object","properties":{"grant_type":{"type":"string","enum":["authorization_code","refresh_token","client_credentials"],"example":"authorization_code","description":"The OAuth 2.0 grant type being used for the token request"},"code":{"type":"string","example":"4/P7q7W91a-oMsCeLvIaQm6bTrgtp7","description":"The authorization code received from the authorization server (required for authorization_code grant type)"},"refresh_token":{"type":"string","example":"1B4a2e77838347a7E420ce178F2E7c6912E169246c","description":"The refresh token used to obtain a new access token (required for refresh_token grant type)"},"client_id":{"type":"string","example":"client_12345","description":"The client identifier issued to the client during registration (required for public clients, when not authenticating via Basic Auth)"},"scope":{"type":"string"},"code_verifier":{"type":"string","example":"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk","description":"PKCE code verifier used to verify the authorization request (required when PKCE was used in authorization request)"}},"required":["grant_type"]}}}},"responses":{"200":{"description":"Retrieve the quote details","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlcyI6WyJhZG1pbiJdLCJwYJ0bmVyIjoi...","description":"The access token to access the API endpoints"},"token_type":{"type":"string","enum":["Bearer"],"example":"Bearer","description":"The type of token issued, always 'Bearer'"},"expires_in":{"type":"number","example":3600,"description":"The lifetime of the access token in seconds (60 minutes)"},"refresh_token":{"type":"string","example":"21cc84a3ad98736f4e5eddc88a1f4b58a29ae96206027c9b59d874cb2a7f7e02","description":"The refresh token to create a new access_token"},"scope":{"type":"string","example":"read:* write:*","description":"Space-delimited list of scopes granted on this token (RFC 6749)."}},"required":["access_token","token_type","expires_in","refresh_token","scope"]}}}},"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"}}}}}}},"/oauth/authorize":{"get":{"tags":["Authentication"],"summary":"Authorize","description":"Create an authorized session","parameters":[{"schema":{"type":"string","enum":["code"],"example":"code","description":"The response type, must be 'code' for authorization code flow"},"required":true,"description":"The response type, must be 'code' for authorization code flow","name":"response_type","in":"query"},{"schema":{"type":"string","example":"client_12345","description":"The client identifier issued to the client during registration"},"required":true,"description":"The client identifier issued to the client during registration","name":"client_id","in":"query"},{"schema":{"type":"string","format":"uri","example":"https://your-app.com/callback","description":"The URI to redirect to after authorization is complete"},"required":true,"description":"The URI to redirect to after authorization is complete","name":"redirect_uri","in":"query"},{"schema":{"type":"string"},"required":false,"name":"scope","in":"query"},{"schema":{"type":"string","example":"xcoiv98sj3coijs","description":"Optional value used by the client to maintain state between request and callback"},"required":false,"description":"Optional value used by the client to maintain state between request and callback","name":"state","in":"query"},{"schema":{"type":"string","example":"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM","description":"PKCE code challenge derived from the code verifier"},"required":false,"description":"PKCE code challenge derived from the code verifier","name":"code_challenge","in":"query"},{"schema":{"type":"string","enum":["S256","plain"],"example":"S256","description":"Method used to derive the code challenge, either 'S256' or 'plain'"},"required":false,"description":"Method used to derive the code challenge, either 'S256' or 'plain'","name":"code_challenge_method","in":"query"},{"schema":{"type":"string","enum":["login","signup"],"example":"login","description":"If you want to use Nomos as identity provider, you can support a login or signup flow via explicitly setting this parameter. In contrast to the default, the login options skips the consent screen. The signup options allows your users to create a new customer without a subscription attached to it, and therefore register an account."},"required":false,"description":"If you want to use Nomos as identity provider, you can support a login or signup flow via explicitly setting this parameter. In contrast to the default, the login options skips the consent screen. The signup options allows your users to create a new customer without a subscription attached to it, and therefore register an account.","name":"flow_type","in":"query"}],"responses":{"302":{"description":"Redirect to the defined redirect_uri"},"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"}}}}}}},"/admin/magic_link":{"post":{"tags":["Authentication"],"summary":"Create a magic link (customer portal)","description":"This endpoint can be used to create a customer portal magic link. The link (returned in the `link` property) allows your customer to directly access the customer portal. This is useful if you want to integrate the customer portal into your own application. Remember that it is your responsibility to make sure to provide the correct `customerId` for your user you'd like to log in.","security":[{"Bearer":[]}],"requestBody":{"description":"The magic link to create for a customerId","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","description":"ID of the customer","example":"cus_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["customerId"]}}}},"responses":{"200":{"description":"The created magic link","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["magic_link"]},"link":{"type":"string","format":"uri","description":"URL of the magic link","example":"https://nomos.customerportal.energy/?token_hash=1234567890&type=magiclink&next=/overview"}},"required":["object","link"]}}}},"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"}}}}}}}}}