> ## Documentation Index > Fetch the complete documentation index at: https://docs.nomos.energy/llms.txt > Use this file to discover all available pages before exploring further. # Create a subscription > Create a new subscription. **Consumption plans:** - `meter.type` may be `smart` or `analog` - `customer.vat_id` is optional - `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 - `previous_supplier` may be set to cancel the customer's existing contract - `product_orders` may order a smart meter or §14a EnWG grid fee reductions, if the plan supports them Requests that break one of these rules are rejected with `400 BAD_REQUEST` and a message naming the violated rule. Feed-in plans are only available from the `2026-05-27.curie` API version onwards; requesting one returns `400 BAD_REQUEST`. ## OpenAPI ````yaml /openapi/openapi.batman.json post /subscriptions openapi: 3.0.0 info: title: Nomos API version: 2025-12-16.batman servers: - url: http://localhost description: test security: [] tags: - name: Plans - name: Leads - name: Subscriptions - name: Customers - name: Usage - name: Prices - name: Invoices - name: Market Partners - name: Events - name: Authentication paths: /subscriptions: post: tags: - Subscriptions summary: Create a subscription description: >- Create a new subscription. **Consumption plans:** - `meter.type` may be `smart` or `analog` - `customer.vat_id` is optional - `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 - `previous_supplier` may be set to cancel the customer's existing contract - `product_orders` may order a smart meter or §14a EnWG grid fee reductions, if the plan supports them Requests that break one of these rules are rejected with `400 BAD_REQUEST` and a message naming the violated rule. Feed-in plans are only available from the `2026-05-27.curie` API version onwards; requesting one returns `400 BAD_REQUEST`. requestBody: description: The subscription to create required: true content: application/json: schema: type: object properties: plan: type: string description: Plan ID example: pln_ 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_ 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_ 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_ plan: type: string description: ID of the plan example: pln_ customer: type: string description: ID of the customer example: cus_ address: type: string description: ID of the address example: adr_ meter: type: string description: ID of the meter example: mtr_ payment_method: type: string description: ID of the payment method example: pm_ supplier: type: string nullable: true description: ID of the previous supplier example: mp_ 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 direction: type: string enum: - consumption - feed_in description: >- Whether the subscription covers electricity consumption or feed-in. Feed-in subscriptions are only available from the 2026-05-27.curie API version onwards. example: consumption 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 - direction - 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' security: - Bearer: [] components: schemas: 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 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 securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ````