> ## Documentation Index
> Fetch the complete documentation index at: https://billing-docs.platform.ai71services.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create new invoice

> Create a new invoice for the authenticated customer.



## OpenAPI

````yaml specs/billing_api_docs.json post /api/v1/invoices
openapi: 3.0.1
info:
  title: Billing API
  description: Billing service for managing subscriptions, payments, and entitlements
  contact: {}
  version: '1.0'
servers:
  - url: https://dev-billing-api.iqraa.ai/api/v1
security: []
tags:
  - name: Customers
    description: Customers related endpoints
  - name: Subscriptions
    description: Subscription related endpoints
  - name: Plans
    description: Plans related endpoints
  - name: Entitlements
    description: Entitlements related endpoints
  - name: Payments
    description: Payments related endpoints
  - name: Emails
    description: Email related endpoints
paths:
  /api/v1/invoices:
    post:
      tags:
        - Invoices
      summary: Create new invoice
      description: Create a new invoice for the authenticated customer.
      operationId: InvoicesController_createInvoice
      parameters: []
      requestBody:
        required: true
        description: Invoice creation details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInvoiceDto'
      responses:
        '201':
          description: Invoice created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceResponseDto'
        '400':
          description: Bad request - Invalid invoice data
        '403':
          description: Forbidden - Customer ID is missing or invalid
        '404':
          description: Customer not found
      security:
        - bearer: []
components:
  schemas:
    CreateInvoiceDto:
      type: object
      properties:
        amount:
          type: number
          description: >-
            The total amount for the invoice in smallest currency unit (e.g.,
            cents)
          example: 9999
          minimum: 0
        currency:
          type: string
          description: The currency code in ISO 4217 format
          example: USD
          enum:
            - USD
            - EUR
            - GBP
            - AED
        description:
          type: string
          description: A clear description of what this invoice is for
          example: Monthly Premium Plan Subscription - January 2024
        planCode:
          type: string
          description: The unique identifier of the plan being billed
          example: PREMIUM_MONTHLY
        planName:
          type: string
          description: The display name of the plan being billed
          example: Premium Monthly Plan
        templateId:
          type: string
          description: >-
            ID of the invoice template to use. If not provided, default template
            will be used
          example: template-123
        status:
          type: string
          description: Current status of the invoice
          enum:
            - DRAFT
            - FINALIZED
            - PAYMENT_FAILED
            - PAID
            - VOID
          example: DRAFT
          default: DRAFT
        components:
          description: Custom invoice components including line items and customer details
          allOf:
            - $ref: '#/components/schemas/InvoiceComponentsDto'
        startDate:
          format: date-time
          type: string
          description: The start date of the billing period
          example: '2024-01-01T00:00:00.000Z'
        renewalDate:
          format: date-time
          type: string
          description: The next renewal date for recurring invoices
          example: '2024-02-01T00:00:00.000Z'
        paymentTerms:
          type: number
          description: Number of days until payment is due
          example: 30
          minimum: 0
      required:
        - amount
        - currency
        - description
    InvoiceResponseDto:
      type: object
      properties:
        id:
          type: string
        invoiceNumber:
          type: string
        date:
          type: string
        status:
          type: string
          enum:
            - DRAFT
            - FINALIZED
            - PAYMENT_FAILED
            - PAID
            - VOID
        amount:
          type: number
        currency:
          type: string
        description:
          type: string
        downloadLink:
          type: string
        planType:
          type: string
        customerName:
          type: string
        customerEmail:
          type: string
      required:
        - id
        - invoiceNumber
        - date
        - status
        - amount
        - currency
        - description
        - customerName
        - customerEmail
    InvoiceComponentsDto:
      type: object
      properties:
        lineItems:
          description: List of items being charged in this invoice
          example:
            - description: Premium Plan Subscription
              quantity: 1
              unitPrice: 99.99
              amount: 99.99
          type: array
          items:
            $ref: '#/components/schemas/LineItemDto'
        customerDetails:
          description: Customer billing information
          allOf:
            - $ref: '#/components/schemas/CustomerDetailsDto'
      required:
        - lineItems
        - customerDetails
    LineItemDto:
      type: object
      properties:
        description:
          type: string
          description: Description of the line item
          example: Premium Plan Subscription
        quantity:
          type: number
          description: Quantity of items
          example: 1
          minimum: 1
        unitPrice:
          type: number
          description: Price per unit
          example: 99.99
        amount:
          type: number
          description: Total amount for this line item (quantity * unitPrice)
          example: 99.99
      required:
        - description
        - quantity
        - unitPrice
        - amount
    CustomerDetailsDto:
      type: object
      properties:
        customerName:
          type: string
          description: Full name of the customer
          example: John Doe
        customerEmail:
          type: string
          description: Email address of the customer
          example: john.doe@example.com
        customerAddress:
          type: string
          description: Billing address of the customer
          example: 123 Business Street, Suite 100
        customerCity:
          type: string
          description: City of the customer
          example: San Francisco
        customerCountry:
          type: string
          description: Country of the customer
          example: United States
      required:
        - customerName
        - customerEmail
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: opaque
      type: http

````