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

# Invoice Create Api

> Creates a new invoice with line items. PDF is auto-generated.



## OpenAPI

````yaml post /api/v1/invoice/
openapi: 3.1.0
info:
  title: NinjaAPI
  version: 1.0.0
  description: ''
servers:
  - url: https://api.justpaid.io
security: []
paths:
  /api/v1/invoice/:
    post:
      summary: Invoice Create Api
      description: Creates a new invoice with line items. PDF is auto-generated.
      operationId: loopfour_backend_invoice_external_api_invoice_create_api
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoiceCreateIn'
        required: true
      responses:
        '201':
          description: Invoice created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceOut2'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                additionalProperties: true
                title: Response
                type: object
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                additionalProperties: true
                title: Response
                type: object
      security:
        - HttpBearerAuth: []
components:
  schemas:
    InvoiceCreateIn:
      description: Input schema for creating an invoice.
      properties:
        customer_uuid:
          description: UUID of the customer (required, must exist)
          example: 123e4567-e89b-12d3-a456-426614174000
          title: Customer Uuid
          type: string
        invoice_number:
          anyOf:
            - maxLength: 100
              type: string
            - type: 'null'
          description: Unique invoice number (auto-generated if not provided)
          example: INV-2024-001
          title: Invoice Number
        invoice_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: Invoice date (defaults to today)
          example: '2024-03-21'
          title: Invoice Date
        due_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: Payment due date
          example: '2024-04-21'
          title: Due Date
        currency:
          default: USD
          description: ISO 4217 currency code
          example: USD
          title: Currency
          type: string
        description:
          anyOf:
            - type: string
            - type: 'null'
          description: Invoice description
          example: Monthly services for March 2024
          title: Description
        service_start_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: Service period start date
          example: '2024-03-01'
          title: Service Start Date
        service_end_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: Service period end date
          example: '2024-03-31'
          title: Service End Date
        notes:
          anyOf:
            - type: string
            - type: 'null'
          description: Internal notes for the invoice
          title: Notes
        recipients:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: Additional email recipients
          title: Recipients
        custom_fields:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          description: Custom fields as list of {field_name, field_value}
          title: Custom Fields
        invoice_status:
          default: draft
          description: Initial invoice status (draft, ready-to-send, or sent)
          example: draft
          title: Invoice Status
          type: string
        line_items:
          description: Invoice line items (at least one required)
          items:
            $ref: '#/components/schemas/LineItemCreateIn'
          minItems: 1
          title: Line Items
          type: array
      required:
        - customer_uuid
        - line_items
      title: InvoiceCreateIn
      type: object
    InvoiceOut2:
      description: Output schema for invoice information.
      properties:
        uuid:
          description: The unique identifier for the invoice
          example: 123e4567-e89b-12d3-a456-426614174000
          format: uuid
          title: Uuid
          type: string
        invoice_status:
          description: The current status of the invoice
          example: draft
          title: Invoice Status
          type: string
        amount:
          description: The total amount due for the invoice
          example: 1000
          title: Amount
          type: number
        currency:
          description: The currency code for the invoice
          example: USD
          title: Currency
          type: string
        invoice_number:
          description: The unique invoice number
          example: INV-2024-001
          title: Invoice Number
          type: string
        invoice_date:
          description: The date when the invoice was created
          example: '2024-03-21'
          format: date
          title: Invoice Date
          type: string
        due_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: The date by which the invoice must be paid
          example: '2024-04-21'
          title: Due Date
        service_start_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: The start date of the service period
          example: '2024-03-01'
          title: Service Start Date
        service_end_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: The end date of the service period
          example: '2024-03-31'
          title: Service End Date
        description:
          anyOf:
            - type: string
            - type: 'null'
          description: A description of the invoice
          example: Monthly services for March 2024
          title: Description
        created_at:
          description: The timestamp when the invoice was created
          example: '2024-03-21T10:00:00Z'
          format: date-time
          title: Created At
          type: string
        is_recurring:
          description: Indicates if this is a recurring invoice
          example: false
          title: Is Recurring
          type: boolean
        from_external_source:
          description: Indicates if the invoice was created from an external source
          example: false
          title: From External Source
          type: boolean
        external_source:
          anyOf:
            - type: string
            - type: 'null'
          description: The name of the external source if applicable
          example: stripe
          title: External Source
        external_source_id:
          anyOf:
            - type: string
            - type: 'null'
          description: The ID of the invoice in the external system
          example: inv_123456
          title: External Source Id
        payment_link:
          anyOf:
            - type: string
            - type: 'null'
          description: URL where the customer can pay this invoice
          example: https://app.justpaid.ai/portal/inv/123
          title: Payment Link
        line_items:
          description: List of line items included in this invoice
          items:
            $ref: '#/components/schemas/InvoiceLineItemOut2'
          title: Line Items
          type: array
        file_url:
          anyOf:
            - type: string
            - type: 'null'
          description: URL to download the invoice PDF
          example: https://api.justpaid.ai/invoices/123.pdf
          title: File Url
        customer:
          anyOf:
            - $ref: '#/components/schemas/CustomerOut2'
            - type: 'null'
          description: Details of the customer associated with this invoice
      title: InvoiceOut2
      type: object
    LineItemCreateIn:
      description: Input schema for creating a line item.
      properties:
        name:
          description: Name of the line item
          example: Product A
          title: Name
          type: string
        description:
          anyOf:
            - type: string
            - type: 'null'
          description: Additional details about the line item
          example: Detailed description of the product or service
          title: Description
        quantity:
          default: 1
          description: Quantity of units
          example: 2
          minimum: 1
          title: Quantity
          type: integer
        unit_price:
          description: Price per unit
          example: 100
          title: Unit Price
          type: number
        flat_fee:
          anyOf:
            - type: number
            - type: 'null'
          description: Fixed flat fee amount
          example: 10
          title: Flat Fee
        discount_amount:
          anyOf:
            - type: number
            - type: 'null'
          description: Discount amount in currency
          example: 5
          title: Discount Amount
        discount_percent:
          anyOf:
            - maximum: 100
              minimum: 0
              type: number
            - type: 'null'
          description: Discount percentage (0-100)
          example: 10
          title: Discount Percent
        tax_rate:
          anyOf:
            - maximum: 100
              minimum: 0
              type: number
            - type: 'null'
          description: Tax rate percentage (0-100)
          example: 10
          title: Tax Rate
        tax_name:
          anyOf:
            - type: string
            - type: 'null'
          description: Name of the tax applied
          example: Sales Tax
          title: Tax Name
        service_start_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: Service period start date
          example: '2024-03-01'
          title: Service Start Date
        service_end_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: Service period end date
          example: '2024-03-31'
          title: Service End Date
        display_order:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
          description: Display order for line item
          title: Display Order
      required:
        - name
        - unit_price
      title: LineItemCreateIn
      type: object
    InvoiceLineItemOut2:
      description: Output schema for invoice line items with UUID for external API.
      properties:
        uuid:
          format: uuid
          title: Uuid
          type: string
        name:
          anyOf:
            - maxLength: 255
              type: string
            - type: 'null'
          title: Name
        unit_price:
          anyOf:
            - type: number
            - type: 'null'
          title: Unit Price
        quantity:
          anyOf:
            - type: integer
            - type: 'null'
          default: 1
          title: Quantity
        amount:
          anyOf:
            - type: number
            - type: 'null'
          title: Amount
        currency:
          anyOf:
            - maxLength: 3
              type: string
            - type: 'null'
          default: USD
          title: Currency
        description:
          anyOf:
            - type: string
            - type: 'null'
          description: The description of the line item
          title: Description
        flat_fee:
          anyOf:
            - type: number
            - type: 'null'
          description: Fixed flat fee added to the line item amount
          title: Flat Fee
        tax_rate:
          anyOf:
            - type: number
            - type: 'null'
          default: 0
          title: Tax Rate
        tax_amount:
          anyOf:
            - type: number
            - type: 'null'
          default: 0
          title: Tax Amount
        tax_name:
          anyOf:
            - maxLength: 255
              type: string
            - type: 'null'
          title: Tax Name
        discount_amount:
          anyOf:
            - type: number
            - type: 'null'
          title: Discount Amount
        discount_percent:
          anyOf:
            - type: number
            - type: 'null'
          title: Discount Percent
        service_start_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: The date the service starts for the item
          title: Service Start Date
        service_end_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: The date the service ends for the item
          title: Service End Date
        display_order:
          anyOf:
            - type: integer
            - type: 'null'
          description: The order in which the line item will be displayed in the UI/pdf
          title: Display Order
      title: InvoiceLineItemOut2
      type: object
    CustomerOut2:
      description: Output schema for customer information.
      properties:
        external_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            An optional external identifier for the customer. This can be used
            to link the customer to an external system.
          example: CUST-001
          title: External Id
        uuid:
          format: uuid
          title: Uuid
          type: string
        name:
          anyOf:
            - maxLength: 100
              type: string
            - type: 'null'
          description: Customer name
          title: Name
        contact_name:
          anyOf:
            - maxLength: 100
              type: string
            - type: 'null'
          description: The name of the contact person
          title: Contact Name
        email:
          anyOf:
            - maxLength: 100
              type: string
            - type: 'null'
          title: Email
        additional_emails:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          description: A list of additional customer email addresses
          title: Additional Emails
        billing_emails:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          description: Billing email addresses
          title: Billing Emails
        phone_number:
          anyOf:
            - maxLength: 20
              type: string
            - type: 'null'
          description: Customer phone number with country code
          title: Phone Number
        currency:
          anyOf:
            - maxLength: 3
              type: string
            - type: 'null'
          default: USD
          title: Currency
        tax_id:
          anyOf:
            - maxLength: 25
              type: string
            - type: 'null'
          description: Customer tax id
          title: Tax Id
      title: CustomerOut2
      type: object
  securitySchemes:
    HttpBearerAuth:
      type: http
      scheme: bearer

````