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

# Create line_items



## OpenAPI

````yaml /openapi.json post /line_items
openapi: 3.0.3
info:
  title: PracticeHub API
  version: 1.0.0
  description: >
    The canonical PracticeHub REST API. Every clinic account is a tenant
    addressed by the host the practice signs in on:
    `https://{clinic}.{region}.practicehub.io` (region host `neptune` London,
    `mercury` Frankfurt, `vulcan` Ohio, `jupiter` Singapore, `apollo` Sydney).


    ## Filtering

    List endpoints accept `?attribute=operator:value` with operators `eq`, `ne`,
    `gt`, `gte`, `lt`, `lte`, `null`, `not-null`, `like`, `contains`, `in`,
    `not-in`, `between` (`null`/`not-null` take no value; `in`, `not-in`,
    `between` take comma-separated values; `contains` is a case-insensitive
    substring match with no wildcards to escape). A value with no operator is an
    equality match. Only attributes marked filterable may be filtered (422
    otherwise).


    ## Metadata

    Every record carries an integrator-owned `metadata` object of string, number
    or boolean values (max 50 keys). Send `metadata` on create/update to merge
    keys (`null` removes a key) and filter with `?metadata[key]=operator:value`.


    ## Sorting & pagination

    `?sort=attr[,attr]:asc|desc` on sortable attributes; `?page=` and
    `?page_size=` (max 100). List responses wrap rows in `data` with `links` and
    `meta`.
servers:
  - url: https://{clinic}.{region}.practicehub.io/v3/api
    description: PracticeHub API — the host the practice signs in on
    variables:
      clinic:
        default: your-clinic
        description: The clinic subdomain
      region:
        default: neptune
        enum:
          - neptune
          - mercury
          - vulcan
          - jupiter
          - apollo
        description: >-
          The region host from the practice login URL: neptune (London), mercury
          (Frankfurt), vulcan (Ohio), jupiter (Singapore), apollo (Sydney)
security:
  - bearerAuth: []
tags:
  - name: Utility
    description: Liveness, identity and discovery
  - name: Availability
    description: Free, bookable slots — check before creating an appointment
  - name: Appointments
    description: The appointments resource
  - name: Appointment Types
    description: The appointment_types resource
  - name: Practitioner Availabilities
    description: The practitioner_availabilities resource
  - name: Resources
    description: The resources resource
  - name: Patients
    description: The patients resource
  - name: Tags
    description: The tags resource
  - name: Patient Tags
    description: The patient_tags resource
  - name: Numbers
    description: The numbers resource
  - name: Addresses
    description: The addresses resource
  - name: Patient Logs
    description: The patient_logs resource
  - name: Patient Log Tags
    description: The patient_log_tags resource
  - name: Files
    description: The files resource
  - name: Care Plans
    description: The care_plans resource
  - name: Clinical Notes
    description: Clinical notes on the patient record
  - name: Form Templates
    description: The form_templates resource
  - name: Invoices
    description: The invoices resource
  - name: Line Items
    description: The line_items resource
  - name: Payments
    description: The payments resource
  - name: Refunds
    description: The refunds resource
  - name: Payment Allocations
    description: The payment_allocations resource
  - name: Payment Methods
    description: The payment_methods resource
  - name: Billable Items
    description: The billable_items resource
  - name: Locations
    description: The locations resource
  - name: Practitioners
    description: The practitioners resource
  - name: Modalities
    description: The modalities resource
  - name: Referral Sources
    description: The referral_sources resource
  - name: Deleted Entities
    description: The deleted_entities resource
paths:
  /line_items:
    post:
      tags:
        - Line Items
      summary: Create line_items
      operationId: create_line_items
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LineItemsCreate'
      responses:
        '201':
          description: The resource
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/LineItems'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/ReadOnlyKey'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Any unique string (≤255 chars). A retry with the same key within 24
        hours replays the original response (Idempotent-Replayed: true) instead
        of creating a second record.
      schema:
        type: string
        maxLength: 255
  schemas:
    LineItemsCreate:
      oneOf:
        - title: Add one line
          type: object
          properties:
            invoice_id:
              type: integer
              minimum: 1
              description: >-
                The invoice the line belongs to. Every invoice keeps at least
                one line — the last line can't be removed; void the invoice
                instead.
            description:
              type: string
              maxLength: 255
              description: What the line bills for, up to 255 characters.
            quantity:
              type: integer
              minimum: 1
              maximum: 2147483647
              description: Units billed — a whole number, at least 1.
            price:
              type: string
              pattern: ^-?\d+(\.\d{1,2})?$
              example: '45.00'
              description: >-
                Unit price, 2 dp, within ±99,999,999.99 — negative for a
                discount or credit line, exactly as on the invoice screen.
            billable_item_id:
              type: integer
              minimum: 1
              description: >-
                The account service or product this line bills — required on
                every new line. On update, omit it to keep the existing link; a
                line can never be stripped of its link.
            provider_id:
              type: integer
              nullable: true
              description: >-
                The practitioner credited with the line. Defaults to the
                invoice's practitioner_id when omitted; null is a deliberate
                no-provider.
            metadata:
              $ref: '#/components/schemas/Metadata'
          required:
            - invoice_id
            - description
            - quantity
            - price
            - billable_item_id
        - title: Add several lines
          type: object
          properties:
            invoice_id:
              type: integer
              minimum: 1
              description: >-
                The invoice the line belongs to. Every invoice keeps at least
                one line — the last line can't be removed; void the invoice
                instead.
            provider_id:
              type: integer
              nullable: true
              description: >-
                The practitioner credited with the line. Defaults to the
                invoice's practitioner_id when omitted; null is a deliberate
                no-provider.
            lines:
              type: array
              items:
                type: object
                properties:
                  description:
                    type: string
                    maxLength: 255
                  quantity:
                    type: integer
                    minimum: 1
                    maximum: 2147483647
                  price:
                    type: string
                    pattern: ^-?\d+(\.\d{1,2})?$
                    example: '45.00'
                  billable_item_id:
                    type: integer
                    minimum: 1
                  provider_id:
                    type: integer
                    nullable: true
                required:
                  - description
                  - quantity
                  - price
                  - billable_item_id
            metadata:
              $ref: '#/components/schemas/Metadata'
          required:
            - invoice_id
            - lines
    LineItems:
      type: object
      properties:
        id:
          type: integer
          description: Unique line item id.
        invoice_id:
          type: integer
          minimum: 1
          description: >-
            The invoice the line belongs to. Every invoice keeps at least one
            line — the last line can't be removed; void the invoice instead.
        billable_item_id:
          type: integer
          minimum: 1
          description: >-
            The account service or product this line bills — required on every
            new line. On update, omit it to keep the existing link; a line can
            never be stripped of its link.
        provider_id:
          type: integer
          nullable: true
          description: >-
            The practitioner credited with the line. Defaults to the invoice's
            practitioner_id when omitted; null is a deliberate no-provider.
        provider_type:
          type: string
          maxLength: 255
          nullable: true
          description: >-
            chiropractor whenever the line has a provider, null otherwise.
            Server-managed alongside provider_id.
        description:
          type: string
          maxLength: 255
          description: What the line bills for, up to 255 characters.
        quantity:
          type: integer
          minimum: 1
          maximum: 2147483647
          description: Units billed — a whole number, at least 1.
        currency:
          type: string
          maxLength: 255
          nullable: true
          description: >-
            Currency code stamped on some legacy and gateway-written lines (e.g.
            GBP); often null. The account operates in a single currency either
            way.
        price:
          type: string
          pattern: ^-?\d+(\.\d{1,2})?$
          example: '45.00'
          nullable: true
          description: >-
            Unit price, 2 dp, within ±99,999,999.99 — negative for a discount or
            credit line, exactly as on the invoice screen.
        tax_amount:
          type: string
          pattern: ^-?\d+(\.\d{1,2})?$
          example: '45.00'
          nullable: true
          description: >-
            Tax recorded against the line, 2 dp. Lines written through
            PracticeHub's services carry 0.
        subtotal:
          type: string
          pattern: ^-?\d+(\.\d{1,2})?$
          example: '45.00'
          nullable: true
          description: >-
            quantity × price, recomputed on every change. Derived, never written
            directly.
        total:
          type: string
          pattern: ^-?\d+(\.\d{1,2})?$
          example: '45.00'
          nullable: true
          description: >-
            The line's total (quantity × price), recalculated on every save.
            Active line totals sum into the invoice's total.
        updated_at:
          type: string
          description: When the line last changed, UTC. Server-managed.
        created_at:
          type: string
          description: When the line was created, UTC. Server-managed.
        metadata:
          $ref: '#/components/schemas/Metadata'
      example:
        id: 501
        invoice_id: 98
        billable_item_id: 17
        provider_id: 12
        provider_type: chiropractor
        description: Initial consultation
        quantity: 1
        currency: GBP
        price: '65.00'
        tax_amount: '0.00'
        subtotal: '65.00'
        total: '65.00'
        updated_at: '2026-09-01T14:30:00Z'
        created_at: '2026-09-01T09:15:00Z'
    Metadata:
      type: object
      description: >-
        Integrator-owned key/value metadata (max 50 keys). Values are strings
        (≤500 chars), numbers or booleans and read back with the type they were
        written with. On write, a null value removes the key. Filter with
        metadata[key]=op:value; number operands compare numerically.
      additionalProperties:
        nullable: true
        oneOf:
          - type: string
            maxLength: 500
          - type: number
          - type: boolean
    Error:
      type: object
      required:
        - message
        - code
      properties:
        message:
          type: string
          description: Human-readable; may change — do not parse
        code:
          type: string
          description: >-
            Stable machine-readable code (snake_case), e.g. validation_failed,
            not_found, key_read_only, not_online_bookable, group_full,
            appointment_rule, billing_rule, idempotency_key_reused, rate_limited
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Present on validation failures, keyed by attribute
  responses:
    Unauthenticated:
      description: Missing or invalid credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ReadOnlyKey:
      description: The API key is read-only
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: >-
        A domain rule rejected the change (e.g. group_full, already processed,
        void)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: Invalid input; `errors` is keyed by attribute
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key from Developers → API Keys, sent as Authorization: Bearer <key>.'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.