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

# Raises a manual invoice against a client, with line items.

> <b>Required:</b>
`ClientId`, and at least one line item with `ItemId` and
            `Quantity`.
            
<b>Optional:</b>`StatusId` (defaults to Draft), `InvoiceDate` (defaults to
            today), `DueDate` (defaults to `InvoiceDate`), `Reference`,
            `RecipientEmails`. Per line: `UnitPrice`, `UnitCost`, `TaxId`,
            `CoaCode`, `Description`, `BillableStatusId` and `DiscountPercent` each
            fall back to the referenced item's own value when omitted.
            
`StatusId` is `1` (Draft) or `5` (Approved). Approving on create also pushes
            the invoice to the connected accounting system. An Approved invoice whose total comes to
            exactly `0` is created as Paid instead - check `Status` on the response rather
            than assuming it matches what you sent.
            
The response is just the created invoice's `Id` - the same shape Create Ticket
            and Create Time Entry return.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/invoices
openapi: 3.0.4
info:
  title: Public API
  description: Gorelo Public API documentation.
  version: 1.0.0
servers:
  - url: https://api.usw.gorelo.io
    description: US
  - url: https://api.aue.gorelo.io
    description: Australia
security:
  - ApiKeyAuth: []
tags:
  - name: Attachments
    description: "Uploading a file, for anything that can carry one. One endpoint rather than one per record\r\ntype, because the upload itself is identical - only the record it is checked against differs."
  - name: Alerts
    description: Alerts management operations
  - name: Assets
    description: Assets management operations
  - name: Billing
    description: Billing management operations
  - name: Tickets
    description: Tickets management operations
  - name: Clients
    description: Clients management operations
  - name: Contacts
    description: Contacts management operations
  - name: Deletions
    description: Deletions management operations
  - name: Documents
    description: Documents management operations
  - name: Forms
    description: Forms management operations
  - name: Organization
    description: Organization management operations
  - name: Projects
    description: Projects management operations
paths:
  /v1/invoices:
    post:
      tags:
        - Billing
      summary: Raises a manual invoice against a client, with line items.
      description: "<b>Required:</b>\r\n`ClientId`, and at least one line item with `ItemId` and\r\n            `Quantity`.\r\n            \n<b>Optional:</b>`StatusId` (defaults to Draft), `InvoiceDate` (defaults to\r\n            today), `DueDate` (defaults to `InvoiceDate`), `Reference`,\r\n            `RecipientEmails`. Per line: `UnitPrice`, `UnitCost`, `TaxId`,\r\n            `CoaCode`, `Description`, `BillableStatusId` and `DiscountPercent` each\r\n            fall back to the referenced item's own value when omitted.\r\n            \n`StatusId` is `1` (Draft) or `5` (Approved). Approving on create also pushes\r\n            the invoice to the connected accounting system. An Approved invoice whose total comes to\r\n            exactly `0` is created as Paid instead - check `Status` on the response rather\r\n            than assuming it matches what you sent.\r\n            \nThe response is just the created invoice's `Id` - the same shape Create Ticket\r\n            and Create Time Entry return."
      operationId: post_v1_invoices
      requestBody:
        description: The invoice to create.
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/CreateInvoiceCommand'
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInvoiceCommand'
          text/json:
            schema:
              $ref: '#/components/schemas/CreateInvoiceCommand'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CreateInvoiceCommand'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/CreateInvoiceResultBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/CreateInvoiceResultBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/CreateInvoiceResultBaseResponse'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
        '401':
          description: Unauthorized
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
        '409':
          description: Conflict
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
        '500':
          description: Internal Server Error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
components:
  schemas:
    CreateInvoiceCommand:
      type: object
      properties:
        ClientId:
          type: integer
          description: >-
            Client to bill. Validated against the service provider - an unknown
            client is a 404.
          format: int64
          example: 88
        StatusId:
          type: integer
          description: "Status to create the invoice in: 1 = Draft (default) or 5 = Approved. Any other value is\r\nrejected. Approving on create pushes the invoice to the connected accounting system, the\r\nsame as approving it in the app. An Approved invoice whose computed total is\r\nexactly 0 is recorded as Paid instead."
          format: int32
          nullable: true
          example: 1
        InvoiceDate:
          type: string
          description: >-
            Date the invoice is raised, a calendar date. Defaults to today
            (service provider's local date) when omitted.
          format: date-time
          nullable: true
          example: '2026-09-15T00:00:00.0000000+00:00'
        DueDate:
          type: string
          description: "Date payment is due, a calendar date. Defaults to InvoiceDate when omitted. Must not be\r\nearlier than InvoiceDate."
          format: date-time
          nullable: true
          example: '2026-10-15T00:00:00.0000000+00:00'
        Reference:
          type: string
          description: Free-text reference for the invoice, or omit for none.
          nullable: true
          example: PO-4471
        RecipientEmails:
          type: array
          items:
            type: string
          description: Email addresses to send the invoice to. Optional.
          nullable: true
        LineItems:
          type: array
          items:
            $ref: '#/components/schemas/CreateInvoiceLineItem'
          description: "Line items for this invoice. At least one is required. Lines carry no task/ticket/time-entry\r\nlinkage - that belongs to contract-generated invoices, out of scope for a manual one. A line\r\nwhose ItemId is a bundle is billed as one line and stored as the bundle's parts, the same\r\nway the app stores it; the caller never sends the parts."
      additionalProperties: false
      description: Raises a manual invoice against a client, with line items.
    CreateInvoiceResultBaseResponse:
      type: object
      properties:
        StatusCode:
          $ref: '#/components/schemas/HttpStatusCode'
        IsSuccess:
          type: boolean
        Data:
          $ref: '#/components/schemas/CreateInvoiceResult'
        DataContext:
          type: object
          additionalProperties: false
          nullable: true
          example: null
        Notifications:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      additionalProperties: false
    ObjectBaseResponse:
      type: object
      properties:
        StatusCode:
          $ref: '#/components/schemas/HttpStatusCode'
        IsSuccess:
          type: boolean
        Data:
          nullable: true
        DataContext:
          $ref: '#/components/schemas/ErrorDataContext'
        Notifications:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      additionalProperties: false
    CreateInvoiceLineItem:
      type: object
      properties:
        ItemId:
          type: string
          description: "Catalog item this line bills. Required. Validated for existence and tenant ownership against\r\nGET /v1/items."
          format: uuid
          example: '9214'
        Description:
          type: string
          description: >-
            Description shown on the invoice for this line. Falls back to the
            item's own name when omitted.
          nullable: true
        Quantity:
          type: number
          description: Quantity billed. Required, must be greater than 0.
          format: double
          example: 2
        UnitPrice:
          type: number
          description: Unit price. Falls back to the item's own price when omitted.
          format: double
          nullable: true
          example: 150
        UnitCost:
          type: number
          description: Unit cost. Falls back to the item's own cost when omitted.
          format: double
          nullable: true
          example: 90
        DiscountPercent:
          type: number
          description: >-
            Discount percentage for this line, 0-100. Defaults to 0 when
            omitted.
          format: double
          nullable: true
          example: 10
        TaxId:
          type: integer
          description: >-
            Tax to apply to this line. Falls back to the item's own tax when
            omitted; send explicit null to force no tax regardless of the item's
            own tax.
          format: int64
          nullable: true
        CoaCode:
          type: string
          description: >-
            Chart-of-accounts code for this line. Falls back to the item's own
            COA code when omitted.
          nullable: true
        BillableStatusId:
          type: integer
          description: >-
            Billable status for this line: 1 = Billable, 2 = No charge, 3 =
            Non-billable. Defaults to Billable when omitted.
          format: int32
          nullable: true
      additionalProperties: false
    HttpStatusCode:
      enum:
        - 100
        - 101
        - 102
        - 103
        - 200
        - 201
        - 202
        - 203
        - 204
        - 205
        - 206
        - 207
        - 208
        - 226
        - 300
        - 301
        - 302
        - 303
        - 304
        - 305
        - 306
        - 307
        - 308
        - 400
        - 401
        - 402
        - 403
        - 404
        - 405
        - 406
        - 407
        - 408
        - 409
        - 410
        - 411
        - 412
        - 413
        - 414
        - 415
        - 416
        - 417
        - 421
        - 422
        - 423
        - 424
        - 426
        - 428
        - 429
        - 431
        - 451
        - 500
        - 501
        - 502
        - 503
        - 504
        - 505
        - 506
        - 507
        - 508
        - 510
        - 511
      type: integer
      format: int32
    CreateInvoiceResult:
      type: object
      properties:
        Id:
          type: string
          description: Identifier of the newly created invoice.
          format: uuid
      additionalProperties: false
      description: "Result of a create-invoice request. Matches Create Ticket/Create Time Entry's minimal shape:\r\njust the new record's `Id`. Fetch the invoice back through\r\n`GET /v1/invoices/{invoiceId}` for the full record."
    Error:
      type: object
      properties:
        Code:
          pattern: ^[0-9]{6}$
          type: string
          description: 6-digit MMTTNN error code. See the Public API error-code registry.
          example: '070101'
        Message:
          type: string
        PropertyName:
          type: string
          nullable: true
        ActionHint:
          type: string
          nullable: true
        DocUrl:
          type: string
          nullable: true
      additionalProperties: false
    ErrorDataContext:
      type: object
      properties:
        TraceId:
          type: string
          description: Request correlation id. Quote this when reporting a problem.
          nullable: true
      additionalProperties: false
      description: "The `DataContext` of an error response: carries the correlation id for the failed\r\nrequest."
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: >-
        Your Gorelo API key. See [Generate API key](/generate-api-key). If your
        data is hosted in Australia, click the base URL at the top of this page
        and select `https://api.aue.gorelo.io`.
      name: X-API-Key
      in: header

````

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