{"openapi":"3.0.0","info":{"title":"Nomos API","version":"2026-05-27.curie"},"servers":[{"url":"https://api.sandbox.nomos.energy","description":"production"}],"tags":[{"name":"Plans"},{"name":"Leads"},{"name":"Subscriptions"},{"name":"Customers"},{"name":"Consumption"},{"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"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"}},"required":["code","message","requestId","docs"]},"UsageInvoice":{"type":"object","properties":{"object":{"type":"string","enum":["invoice"]},"id":{"type":"string","description":"Unique identifier of the invoice.","example":"inv_drjjua6ampd1op2fg98k89x8"},"invoice_number":{"type":"string","description":"Human-readable invoice number displayed on the invoice document","example":"H62SU12A-003"},"month":{"type":"number","description":"Numeric month (1-12) for which the invoice is issued","example":4},"year":{"type":"number","description":"Four-digit year for which the invoice is issued","example":2025},"period_start":{"type":"string","nullable":true,"description":"Timestamp marking the beginning of the billing period (inclusive)","example":"2025-03-31T22:00:00Z"},"period_end":{"type":"string","nullable":true,"description":"Timestamp marking the end of the billing period (exclusive)","example":"2025-04-30T22:00:00Z"},"period_number":{"type":"number","description":"Sequential number of the billing period within the subscription (1-based)","example":3},"status":{"type":"string","enum":["open","paid","voided"],"description":"Current status of the invoice:","example":"open"},"issued_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the invoice was issued","example":"2024-03-14T12:00:00Z"},"paid_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the invoice was paid","example":"2024-03-14T12:00:00Z"},"type":{"type":"string","enum":["usage"],"description":"Discriminator for usage invoices, which bill metered electricity consumption for the period.","example":"usage"},"usage":{"type":"number","description":"Total energy consumption in kilowatt-hours (kWh) during the billing period","example":100},"total":{"type":"number","description":"Total amount due in euros (EUR) including all fees, taxes, and energy costs","example":110.04}},"required":["object","id","invoice_number","month","year","period_start","period_end","period_number","status","type","usage","total"]},"PrepaymentInvoice":{"type":"object","properties":{"object":{"type":"string","enum":["invoice"]},"id":{"type":"string","description":"Unique identifier of the invoice.","example":"inv_drjjua6ampd1op2fg98k89x8"},"invoice_number":{"type":"string","description":"Human-readable invoice number displayed on the invoice document","example":"H62SU12A-003"},"month":{"type":"number","description":"Numeric month (1-12) for which the invoice is issued","example":4},"year":{"type":"number","description":"Four-digit year for which the invoice is issued","example":2025},"period_start":{"type":"string","nullable":true,"description":"Timestamp marking the beginning of the billing period (inclusive)","example":"2025-03-31T22:00:00Z"},"period_end":{"type":"string","nullable":true,"description":"Timestamp marking the end of the billing period (exclusive)","example":"2025-04-30T22:00:00Z"},"period_number":{"type":"number","description":"Sequential number of the billing period within the subscription (1-based)","example":3},"status":{"type":"string","enum":["open","paid","voided"],"description":"Current status of the invoice:","example":"open"},"issued_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the invoice was issued","example":"2024-03-14T12:00:00Z"},"paid_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the invoice was paid","example":"2024-03-14T12:00:00Z"},"type":{"type":"string","enum":["prepayment"],"description":"Discriminator for prepayment invoices, which charge a fixed advance amount and carry no metered usage.","example":"prepayment"},"total":{"type":"number","description":"Prepayment amount due in euros (EUR), including taxes","example":99}},"required":["object","id","invoice_number","month","year","period_start","period_end","period_number","status","type","total"]},"InvoiceUnion":{"oneOf":[{"$ref":"#/components/schemas/UsageInvoice"},{"$ref":"#/components/schemas/PrepaymentInvoice"}],"discriminator":{"propertyName":"type","mapping":{"usage":"#/components/schemas/UsageInvoice","prepayment":"#/components/schemas/PrepaymentInvoice"}}},"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_nc007zhcdr54t17daxtfkf3p"},"subscription":{"type":"string","description":"ID of the subscription","example":"sub_okebktefilpowemkt825ndjg"},"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"}},"required":["object","id","subscription","type","status","valid_from","valid_until","created_at","updated_at"]},"InsertGridFeeReduction":{"type":"object","properties":{"subscription":{"type":"string","description":"ID of the subscription","example":"sub_x4nh1ew9yua6sjg8713oqlfb"},"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"]},"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_zmx0pikh0pydq30kp2e2nyag"},"subscription":{"type":"string","description":"ID of the subscription","example":"sub_vagq9el877fki7xx964yksxy"},"customer":{"type":"string","description":"ID of the customer","example":"cus_k6enrets9v1rh7lrq0ov69lx"},"provider":{"type":"string","enum":["energy-metering","metrify","inexogy"],"description":"The smart meter provider","example":"energy-metering"},"status":{"type":"string","enum":["waiting","ordered","checked","installation_planning","installation_scheduled","installation_waiting","installation_finished","activated","installed","pre_installed","cancelled","intended","blocked","blocked_wim"],"description":"Current status of the meter order.\n\nPossible values:\n- `waiting`: The customer has requested a smart meter - waiting to transfer the order to the meter provider (e.g. missing MaLo, MeLo,..)\n- `ordered`: We have transferred the order to the meter provider\n- `checked`: The meter provider did a smart meter check and confirmed to process the order\n- `installation_planning`: The meter provider is planning the installation (e.g. waiting for the customer to confirm the installation date)\n- `installation_scheduled`: The meter provider has scheduled the installation with the customer (e.g. waiting for the customer to confirm the installation date)\n- `installation_waiting`: The meter provider is waiting for the installation to start (e.g. waiting for the customer to confirm the installation date)\n- `installation_finished`: The meter provider has finished the installation and the new meter data has been transferred to the network operator\n- `activated`: The smart meter is activated and can be used for automatic consumption data transmission\n- `installed`: The smart meter is installed\n- `pre_installed`: There is already a smart meter installed - no installation is needed\n- `cancelled`: The order has been cancelled\n- `intended`: The customer shows interest but has not yet completed the order\n- `blocked`: The order is artificially blocked by our system - waiting for admin approval\n- `blocked_wim`: The smart meter is blocked in Wechselprozess im Messwesen (WiM) - waiting for the network operator to confirm the installation","example":"waiting"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the order was created","example":"2024-03-14T12:00:00Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the order was last updated","example":"2024-03-14T12:00:00Z"}},"required":["object","id","subscription","customer","provider","status","created_at","updated_at"]},"InsertMeterOrder":{"type":"object","properties":{"subscription":{"type":"string","description":"ID of the subscription to create the meter order for","example":"sub_z9b36tye291mjg6h2rw4kwtu"}},"required":["subscription"]},"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"]},"Invoice":{"type":"object","properties":{"object":{"type":"string","enum":["invoice"]},"id":{"type":"string","description":"Unique identifier of the invoice.","example":"inv_drjjua6ampd1op2fg98k89x8"},"invoice_number":{"type":"string","description":"Human-readable invoice number displayed on the invoice document","example":"H62SU12A-003"},"month":{"type":"number","description":"Numeric month (1-12) for which the invoice is issued","example":4},"year":{"type":"number","description":"Four-digit year for which the invoice is issued","example":2025},"period_start":{"type":"string","nullable":true,"description":"Timestamp marking the beginning of the billing period (inclusive)","example":"2025-03-31T22:00:00Z"},"period_end":{"type":"string","nullable":true,"description":"Timestamp marking the end of the billing period (exclusive)","example":"2025-04-30T22:00:00Z"},"period_number":{"type":"number","description":"Sequential number of the billing period within the subscription (1-based)","example":3},"status":{"type":"string","enum":["open","paid","voided"],"description":"Current status of the invoice:","example":"open"},"usage":{"type":"number","description":"Total energy consumption in kilowatt-hours (kWh) during the billing period","example":100},"total":{"type":"number","description":"Total amount due in euros (EUR) including all fees, taxes, and energy costs","example":110.04},"issued_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the invoice was issued","example":"2024-03-14T12:00:00Z"},"paid_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the invoice was paid","example":"2024-03-14T12:00:00Z"}},"required":["object","id","invoice_number","month","year","period_start","period_end","period_number","status","usage","total"]},"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_ymlh25x9iym6qs2ic7fyus8m"},"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"]},{"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_lhtphkzn2ob0v53ac405v22t"},"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"]}]},"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"]},"Plan":{"type":"object","properties":{"object":{"type":"string","enum":["plan"]},"id":{"type":"string","description":"Unique identifier of the plan.","example":"pln_bn1sny3aczwq5jkz8xcf4klf"},"name":{"type":"string","description":"Name of the plan.","example":"Nomos Friends & Family"},"slug":{"type":"string","description":"Unique slug of the plan. Used to generate the [slug].checkout.energy or [slug].customerportal.energy url.","example":"nomos"},"description":{"type":"string","description":"Description of the plan.","example":"A plan for friends and family"},"direction":{"type":"string","enum":["consumption","feed_in"],"description":"Whether the plan covers electricity consumption or feed-in.","example":"consumption"},"price":{"type":"number","description":"Monthly base fee charged excl. grid and metering operator fees, as well as taxes and levies. Includes VAT.","example":10.99},"currency":{"type":"string","description":"Currency of the fees.","example":"EUR"},"created_at":{"type":"string","nullable":true,"description":"Date and time when the plan was created.","example":"2021-01-01T00:00:00.000Z"}},"required":["object","id","name","slug","description","direction","price","currency","created_at"]},"Supplier":{"type":"object","properties":{"object":{"type":"string","enum":["supplier"]},"id":{"type":"string","description":"Unique identifier of the supplier.","example":"mp_a0x6jm5h92wde6s5dnuvha4c"},"name":{"type":"string","description":"Name of the supplier.","example":"Nomos Friends & Family"},"code":{"type":"string","description":"Supplier code.","example":"9903964000002"},"code_type":{"type":"string","description":"Type of supplier code.","example":"BDEW"},"country":{"type":"string","description":"Country of the supplier.","example":"DE"},"created_at":{"type":"string","nullable":true,"description":"Date and time when the supplier was created.","example":"2021-01-01T00:00:00.000Z"}},"required":["object","id","name","code","code_type","country","created_at"]},"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_e5tglr3669bkgx3nhk368stw"},"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"]},"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":{"allOf":[{"$ref":"#/components/schemas/Supplier"},{"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"]}]},"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"}}},"required":["object","id","plan","customer","address","meter","payment_method","status","estimated_usage","created_at","updated_at"]},"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"]},"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"]},"InsertAddress":{"type":"object","properties":{"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"}},"required":["street","house_number","zip","city"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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","description":"When this quote was generated","example":"2024-10-30T16:04:06.122Z"}},"required":["object","amount","currency","components","quoted_at"]},"Price":{"type":"object","properties":{"object":{"type":"string","enum":["price"]},"subscription":{"type":"string","description":"The id of the subscription","example":"sub_rocbrf1u5e48mm0reeqoag90"},"period":{"type":"object","properties":{"start":{"type":"string","description":"Start date of the period at 00:00:00 local time in UTC.","example":"2025-04-01"},"end":{"type":"string","description":"End date of the period at 23:59:59 local time in UTC.","example":"2025-04-01"}},"required":["start","end"]},"unit":{"type":"string","description":"The unit of the price","example":"ct/kWh"},"currency":{"type":"string","description":"The currency of the price","example":"EUR"},"resolution":{"type":"string","enum":["hourly","15min"],"description":"The time resolution of the price data points","example":"hourly"},"reference":{"type":"string","description":"Reference market for electricity prices","example":"EPEX Day-Ahead Hourly"},"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"]},"subscription.created":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_a3do553s5bpjzep0uybmu5uh"},"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_zh6m7g6bhizsxend3pibmlhq"},"lead":{"type":"string","description":"ID of the lead that was converted to this subscription (if applicable)","example":"lead_qh96qobk5vjdz9xykbpqsx2h"}},"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_d6gucsd2bmgao5qyz65ukds6"},"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_m1uoriaof35rnjbgi8qb208f"}},"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_ih2f6h2uynm2kimqnc2lrwb9"},"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_u1bwqmv28b85t1mlmlpy3cw9"}},"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_tlqnfoi2rsfj5w9pw8c0unkt"},"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_fx3uz15u8enla1ibuvfi2rhq"}},"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_mekifjallpewd3ux1v0sckol"},"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_ytd35fgc69bhb1sl1jy2x6y3"}},"required":["subscription"],"description":"The context of the `subscription.terminated` event"}},"required":["id","topic","timestamp","context"]},"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"}],"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"}}},"InsertLead":{"type":"object","properties":{"plan":{"type":"string","description":"Plan ID","example":"pln_xprpj79h74grnwzieizyz1km"},"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"}}},{"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"}}},{"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_wtwacoyl6mi0cf3oxbnowh3a"},"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"]},"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,"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},"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 VAT-exempt customer (`customer_type: \"person\"` with no `vat_id`, § 19 UStG) are quoted without VAT, matching what the customer is later credited. The §14a EnWG module options only apply to consumption plans; feed-in plans do not pay grid fees, so requesting them returns `400 BAD_REQUEST`.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"pln_1"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"ZIP code for the delivery address","example":"10115"},"required":true,"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,"name":"usage","in":"query"},{"schema":{"type":"string","enum":["analog","smart"],"default":"analog","description":"Type of the meter","example":"analog"},"required":false,"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,"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,"name":"14a_module_2","in":"query"},{"schema":{"type":"string","enum":["person","company"],"default":"person","description":"Type of the prospective customer. Together with `vat_id`, this determines the VAT treatment of feed-in payouts; consumption quotes are unaffected.","example":"person"},"required":false,"name":"customer_type","in":"query"},{"schema":{"type":"string","description":"VAT ID (USt-IdNr.) of the prospective customer, if they have one. For feed-in plans, a person without one is treated as VAT-exempt (§ 19 UStG) and quoted the net payout.","example":"DE123456789"},"required":false,"name":"vat_id","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","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,"name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"Retrieve all leads with cursor pagination","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},"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.","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_rprmknscg1pc0w9xuxhk0qx3"},"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":{"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,"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"}}},"required":["object","id","plan","customer","address","meter","payment_method","status","estimated_usage","created_at","updated_at"]}},"next_page":{"type":"string","nullable":true},"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_dqds8o97popazpzrxbovx95t"},"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_wtwacoyl6mi0cf3oxbnowh3a"},"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_sk3vl2aufe1go7mfwfiq43yo"},"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"}}},"required":["object","id","plan","customer","address","meter","payment_method","status","estimated_usage","created_at","updated_at"]}}}},"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}":{"get":{"tags":["Subscriptions"],"summary":"Retrieve a subscription","description":"Retrieve a subscription details by its id","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"sub_p3wogjj2c2vsfnjcbj8udql2"},"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"}}}}}}},"/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,"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},"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"}}}}}}},"/customers/{id}":{"get":{"tags":["Customers"],"summary":"Retrieve a customer","description":"Retrieve customer details by their id","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"cus_fyzs9cyg8wj1zzc6owexmesi"},"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"}}}}}}},"/subscriptions/{id}/usage":{"get":{"tags":["Consumption"],"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","description":"The resolution of the consumption. 'auto' will choose a good resolution based on the start and end date.","example":"auto"},"required":false,"name":"resolution","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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.","example":"2026-06-04"},"required":false,"name":"start","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","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.","example":"2026-06-05"},"required":false,"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"],"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.","example":"smart"},"resolution":{"type":"string","enum":["15min","hour","day","week","month"],"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.","example":"15min"},"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"]},"description":"The consumption of the meter","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"}]}},"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"}}}}}}},"/subscriptions/{id}/meter_readings":{"get":{"tags":["Consumption"],"summary":"List meter readings","description":"Retrieve all meter readings for a subscription with cursor pagination","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"sub_ig1f5x45789r3ax7dlfff4q4"},"required":true,"name":"id","in":"path"},{"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- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"Retrieve all meter readings for a subscription with cursor pagination","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},"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":["Consumption"],"summary":"Create a meter reading","description":"Submit a customer-reported analog meter reading for the active meter of a subscription.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"sub_ig1f5x45789r3ax7dlfff4q4"},"required":true,"name":"id","in":"path"}],"requestBody":{"description":"Meter reading input","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsertMeterReading"}}}},"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":["Consumption"],"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, including the variable price time series to optimize your consumption against. All prices are inclusive of VAT.","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}$","description":"Start date of the period at 00:00:00 in local time of the customer (format yyyy-mm-dd)","example":"2025-02-01"},"required":true,"name":"start","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"End date of the period at 23:59:59 in local time of the customer (format yyyy-mm-dd)","example":"2025-02-01"},"required":true,"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"}}}}}}},"/subscriptions/{id}/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. The related PDFs are available via the `/invoices/{id}/file` endpoint.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"sub_jd8mlscm062jb6ks50tck9gi"},"required":true,"name":"id","in":"path"},{"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\n- `period_start` (date)\n- `period_end` (date)\n- `type` (enum): usage, prepayment\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"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. The related PDFs are available via the `/invoices/{id}/file` endpoint.","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},"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}":{"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/{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","description":"The invoice id to access the pdf file","example":"inv_drjjua6ampd1op2fg98k89x8"},"required":true,"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":{"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): waiting, ordered, checked, installation_planning, installation_scheduled, installation_waiting, installation_finished, activated, installed, pre_installed, cancelled, intended, blocked, blocked_wim\n- `product` (enum): smart-meter-energy-metering, smart-meter-metrify, smart-meter-inexogy\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,"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},"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"}}}}}}},"/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_ni0em8zoj2ay7kbgp4rz9e4r"},"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"}}}}}}},"/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,"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},"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_da819d02aghmxkx4q4nurwn4"},"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"}}}}}}},"/suppliers":{"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,"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/Supplier"}},"next_page":{"type":"string","nullable":true},"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"}}}}}}},"/suppliers/search":{"get":{"tags":["Market Partners"],"summary":"Search market partners","deprecated":true,"description":"Deprecated: Use GET /suppliers with filter[name][contains]=<query> instead. This is a list of all German electricity retailers, which a customer can select as their previous supplier in the checkout process.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","description":"Name or partial name to search for.","example":"Stadtwerke"},"required":true,"name":"name","in":"query"},{"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"}],"responses":{"200":{"description":"Deprecated: Use GET /suppliers with filter[name][contains]=<query> instead. This is a list of all German electricity retailers, which a customer can select as their previous supplier in the checkout process.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/Supplier"}},"next_page":{"type":"string","nullable":true},"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_vkuxynyx4fo0i9nnfztj4xsp"},"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"],"description":"The OAuth 2.0 grant type being used for the token request","example":"authorization_code"},"code":{"type":"string","description":"The authorization code received from the authorization server (required for authorization_code grant type)","example":"4/P7q7W91a-oMsCeLvIaQm6bTrgtp7"},"refresh_token":{"type":"string","description":"The refresh token used to obtain a new access token (required for refresh_token grant type)","example":"1B4a2e77838347a7E420ce178F2E7c6912E169246c"},"client_id":{"type":"string","description":"The client identifier issued to the client during registration (required for public clients, when not authenticating via Basic Auth)","example":"client_12345"},"scope":{"type":"string"},"code_verifier":{"type":"string","description":"PKCE code verifier used to verify the authorization request (required when PKCE was used in authorization request)","example":"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"}},"required":["grant_type"]}}}},"responses":{"200":{"description":"Retrieve the quote details","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string","description":"The access token to access the API endpoints","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlcyI6WyJhZG1pbiJdLCJwYJ0bmVyIjoi..."},"token_type":{"type":"string","enum":["Bearer"],"description":"The type of token issued, always 'Bearer'","example":"Bearer"},"expires_in":{"type":"number","description":"The lifetime of the access token in seconds (60 minutes)","example":3600},"refresh_token":{"type":"string","description":"The refresh token to create a new access_token","example":"21cc84a3ad98736f4e5eddc88a1f4b58a29ae96206027c9b59d874cb2a7f7e02"},"scope":{"type":"string","description":"Space-delimited list of scopes granted on this token (RFC 6749).","example":"read:* write:*"}},"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"],"description":"The response type, must be 'code' for authorization code flow","example":"code"},"required":true,"name":"response_type","in":"query"},{"schema":{"type":"string","description":"The client identifier issued to the client during registration","example":"client_12345"},"required":true,"name":"client_id","in":"query"},{"schema":{"type":"string","format":"uri","description":"The URI to redirect to after authorization is complete","example":"https://your-app.com/callback"},"required":true,"name":"redirect_uri","in":"query"},{"schema":{"type":"string"},"required":false,"name":"scope","in":"query"},{"schema":{"type":"string","description":"Optional value used by the client to maintain state between request and callback","example":"xcoiv98sj3coijs"},"required":false,"name":"state","in":"query"},{"schema":{"type":"string","description":"PKCE code challenge derived from the code verifier","example":"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"},"required":false,"name":"code_challenge","in":"query"},{"schema":{"type":"string","enum":["S256","plain"],"description":"Method used to derive the code challenge, either 'S256' or 'plain'","example":"S256"},"required":false,"name":"code_challenge_method","in":"query"},{"schema":{"type":"string","enum":["login","signup"],"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.","example":"login"},"required":false,"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_lc1pptqztiq1x46jh9cjsi8e"}},"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"}}}}}}}}}