Invoice Model

This document describes the Invoice model, as defined in the Go codebase. The Invoice model represents invoice data, including its unique identifier, status, type, price details, and relevant timestamps. It is primarily used for sending invoice information via webhooks.

Structure

type Invoice struct {
    ID              uuid.UUID     `json:"id"`
    CreatedAt       time.Time     `json:"created_at"`
    UpdatedAt       time.Time     `json:"updated_at"`
    DeletedAt       *time.Time    `json:"deleted_at"`
    InvoiceNumber   string        `json:"invoice_number"`
    InvoiceType     InvoiceType   `json:"invoice_type"`
    Status          InvoiceStatus `json:"status"`
    TotalPrice      Price         `json:"total_price"`
    From            *time.Time    `json:"from"`
    TillIncl        *time.Time    `json:"till_incl"`
    UserID          uuid.UUID     `json:"user_id"`
    InvoiceCreditID *uuid.UUID    `json:"invoice_credit_id"`
}

Field Descriptions

Field	Type	Description
`ID`	`uuid.UUID`	Unique identifier of the invoice.
`CreatedAt`	`time.Time`	Date and time when the invoice was created.
`UpdatedAt`	`time.Time`	Date and time when the invoice was last updated.
`DeletedAt`	`*time.Time`	Date and time when the invoice was deleted (optional).
`InvoiceNumber`	`string`	The number of the invoice.
`InvoiceType`	`InvoiceType`	The type of the invoice (see InvoiceType).
`Status`	`InvoiceStatus`	The status of the invoice (see InvoiceStatus).
`TotalPrice`	`Price`	The total price of the invoice, including VAT breakdown (see Price).
`From`	`*time.Time`	The starting date of the invoice period.
`TillIncl`	`*time.Time`	The ending date of the invoice period (inclusive).
`UserID`	`uuid.UUID`	The ID of the user associated with the invoice.
`InvoiceCreditID`	`*uuid.UUID`	The ID of the credit invoice, if applicable (optional).

Price Structure

The Price struct represents the price breakdown of the invoice.

type Price struct {
    Excl decimal.Decimal `json:"total_excl"`
    Incl decimal.Decimal `json:"total_incl"`
    VAT  decimal.Decimal `json:"vat"`
}

Field	Type	Description
`Excl`	`decimal.Decimal`	Total price excluding VAT.
`Incl`	`decimal.Decimal`	Total price including VAT.
`VAT`	`decimal.Decimal`	VAT amount.

InvoiceStatus Enum

The InvoiceStatus enum indicates the current state of the invoice.

Value	Description
`InvoiceStatusUndefined`	Undefined status (should be considered as an error).
`InvoiceStatusCreated`	Invoice has been created.
`InvoiceStatusDraft`	Invoice is still in draft.
`InvoiceStatusExpired`	Invoice has expired. Deprecated
`InvoiceStatusPaid`	Invoice has been paid by the customer.
`InvoiceStatusCredited`	Invoice has been credited (cancelled by a credit invoice).
`InvoiceStatusToBundle`	No longer supported. Deprecated
`InvoiceStatusBundled`	No longer supported. Deprecated
`InvoiceStatusInvalid`	Invoice in a bundle is invalidated. Deprecated
`InvoiceStatusBundledPaid`	No longer supported. Deprecated
`InvoiceStatusPaymentExpected`	Transaction created, payment not yet received.
`InvoiceStatusSettled`	Invoice has been settled with another invoice.
`InvoiceStatusPayout`	Invoice is ready for payout/excasso.
`InvoiceStatusPartiallyPaid`	Partial payment received for the invoice.

Status String Representation

When serialized to JSON, the status is represented as a string, e.g., "Paid", "Draft", etc.

InvoiceType Enum

The InvoiceType enum indicates the type of invoice.

Value	Description
`InvoiceTypeUndefined`	Undefined type (should be considered as an error).
`InvoiceTypeUpfront`	Upfront invoice.
`InvoiceTypeOneOff`	One-off invoice.
`InvoiceTypeYear`	Yearly invoice.
`InvoiceTypeEnd`	End invoice.
`InvoiceTypeSmartMeter`	Smart meter invoice.
`InvoiceTypeMonthly`	Monthly invoice.
`InvoiceTypeCredit`	Credit invoice.
`InvoiceTypeCollection`	Collection invoice.
`InvoiceTypeMonthlySettle`	Monthly settlement invoice.

Type String Representation

When serialized to JSON, the type is represented as a string, e.g., "Upfront", "Monthly", etc.

Example JSON

{
  "id": "b6e5c8f3-7d4b-4b5a-9e6a-2b8e7c0f3e4c",
  "created_at": "2025-05-20T12:00:00Z",
  "updated_at": "2025-05-20T12:30:00Z",
  "deleted_at": null,
  "invoice_number": "INV-2025-0001",
  "invoice_type": "Monthly",
  "status": "Paid",
  "total_price": {
    "total_excl": "100.00",
    "total_incl": "121.00",
    "vat": "21.00"
  },
  "from": "2025-05-01T00:00:00Z",
  "till_incl": "2025-05-31T23:59:59Z",
  "user_id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
  "invoice_credit_id": null
}

Notes

Deprecated Statuses: Some statuses and types are marked as deprecated and should not be used in new implementations.
Optional Fields: DeletedAt, From, TillIncl, and InvoiceCreditID can be null in JSON.
Enumerations: Both InvoiceStatus and InvoiceType are serialized as human-readable strings.

Structure​

Field Descriptions​

Price Structure​

InvoiceStatus Enum​

Status String Representation​

InvoiceType Enum​

Type String Representation​

Example JSON​

Notes​

See Also​