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

# Invoice

Invoice represents a payment claim for goods or services supplied under conditions agreed between the supplier and the customer.

## Schema ID

`https://gobl.org/draft-0/bill/invoice`

## Properties

| Title             | Property         | Type                                                              | Description                                                                                                                                                                                                                                                                                                                                            |
| ----------------- | ---------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Tax Regime        | `$regime`        | [tax.RegimeCode](/draft-0/tax/regime_code)                        | Country code that identifies the tax regime applicable to the document. It determines which country-specific tax rules, normalizations, and validations are applied. It may be determined automatically via normalization of a supplier or issuer tax identity country code.                                                                           |
| Addons            | `$addons`        | [tax.AddonList](/draft-0/tax/addon_list)                          | Addons defines a list of keys used to identify tax addons that apply special normalization, scenarios, and validation rules to a document.                                                                                                                                                                                                             |
| Tags              | `$tags`          | array of [cbc.Key](/draft-0/cbc/key)                              | Tags are used to help identify specific tax scenarios or requirements that may apply changes to the contents of the document or imply a specific meaning. Converters may use tags to help identify specific situations that do not have a specific extension, for example; self-billed or partial invoices may be identified by their respective tags. |
| UUID              | `uuid`           | string                                                            | Universally Unique Identifier.                                                                                                                                                                                                                                                                                                                         |
| Type              | `type`           | [cbc.Key](/draft-0/cbc/key)                                       | Type of invoice document. May be restricted by local tax regime requirements.                                                                                                                                                                                                                                                                          |
| Series            | `series`         | [cbc.Code](/draft-0/cbc/code)                                     | Series is used to identify groups of invoices by date, business area, project, type of document, customer type, a combination of any or other company specific data. If the output format does not support the series as a separate field, it will be prepended to the code for presentation with a dash (`-`) for separation.                         |
| Code              | `code`           | [cbc.Code](/draft-0/cbc/code)                                     | Code is a sequential identifier that uniquely identifies the invoice. The code can be left empty initially, but is **required** to **sign** the invoice.                                                                                                                                                                                               |
| Issue Date        | `issue_date`     | [cal.Date](/draft-0/cal/date)                                     | Issue date for when the invoice was created and issued. Todays date is used if none is set. There are often legal restrictions on how far back or in the future an invoice can be issued.                                                                                                                                                              |
| Issue Time        | `issue_time`     | [cal.Time](/draft-0/cal/time)                                     | IssueTime is an optional field that may be useful to indicate the time of day when the invoice was issued. Some regions and formats may require this field to be set. An empty string will be automatically updated to reflect the current time, otherwise the field can be left with a nil value.                                                     |
| Operation Date    | `op_date`        | [cal.Date](/draft-0/cal/date)                                     | Date when the operation defined by the invoice became effective.                                                                                                                                                                                                                                                                                       |
| Value Date        | `value_date`     | [cal.Date](/draft-0/cal/date)                                     | When the taxes of this invoice become accountable, if none set, the issue date is used.                                                                                                                                                                                                                                                                |
| Currency          | `currency`       | [currency.Code](/draft-0/currency/code)                           | Currency for all invoice amounts and totals, unless explicitly stated otherwise.                                                                                                                                                                                                                                                                       |
| Exchange Rates    | `exchange_rates` | array of [currency.ExchangeRate](/draft-0/currency/exchange_rate) | Exchange rates to be used when converting the invoices monetary values into other currencies.                                                                                                                                                                                                                                                          |
| Preceding Details | `preceding`      | array of [org.DocumentRef](/draft-0/org/document_ref)             | Document references for previous invoices that this document replaces or extends.                                                                                                                                                                                                                                                                      |
| Tax               | `tax`            | [bill.Tax](/draft-0/bill/tax)                                     | Special billing tax configuration options.                                                                                                                                                                                                                                                                                                             |
| Supplier          | `supplier`       | [org.Party](/draft-0/org/party)                                   | The entity supplying the goods or services and usually responsible for paying taxes.                                                                                                                                                                                                                                                                   |
| Customer          | `customer`       | [org.Party](/draft-0/org/party)                                   | Legal entity receiving the goods or services, may be nil in certain circumstances such as simplified invoices.                                                                                                                                                                                                                                         |
| Lines             | `lines`          | array of [bill.Line](/draft-0/bill/line)                          | List of invoice lines representing each of the items sold to the customer.                                                                                                                                                                                                                                                                             |
| Discounts         | `discounts`      | array of [bill.Discount](/draft-0/bill/discount)                  | Discounts or allowances applied to the complete invoice                                                                                                                                                                                                                                                                                                |
| Charges           | `charges`        | array of [bill.Charge](/draft-0/bill/charge)                      | Charges or surcharges applied to the complete invoice                                                                                                                                                                                                                                                                                                  |
| Ordering Details  | `ordering`       | [bill.Ordering](/draft-0/bill/ordering)                           | Ordering details including document references and buyer or seller parties.                                                                                                                                                                                                                                                                            |
| Payment Details   | `payment`        | [bill.PaymentDetails](/draft-0/bill/payment_details)              | Information on when, how, and to whom the invoice should be paid.                                                                                                                                                                                                                                                                                      |
| Delivery Details  | `delivery`       | [bill.DeliveryDetails](/draft-0/bill/delivery_details)            | Specific details on delivery of the goods referenced in the invoice.                                                                                                                                                                                                                                                                                   |
| Totals            | `totals`         | [bill.Totals](/draft-0/bill/totals)                               | Summary of all the invoice totals, including taxes (calculated).                                                                                                                                                                                                                                                                                       |
| Notes             | `notes`          | array of [org.Note](/draft-0/org/note)                            | Unstructured information that is relevant to the invoice, such as correction or additional legal details.                                                                                                                                                                                                                                              |
| Complements       | `complements`    | array of [schema.Object](/draft-0/schema/object)                  | Additional complementary objects that add relevant information to the invoice.                                                                                                                                                                                                                                                                         |
| Meta              | `meta`           | [cbc.Meta](/draft-0/cbc/meta)                                     | Additional semi-structured data that doesn't fit into the body of the invoice.                                                                                                                                                                                                                                                                         |
| Attachments       | `attachments`    | array of [org.Attachment](/draft-0/org/attachment)                | Attachments provide additional information or supporting documents that are not included in the main document. It is important that attachments are not used for alternative versions of the PDF, for that, see "links" inside the envelope headers.                                                                                                   |

## Type Values

| Value         | Description                                                                                                                                                                                                                                                                           |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `standard`    | A regular commercial invoice document between a supplier and customer.                                                                                                                                                                                                                |
| `proforma`    | For a clients validation before sending a final invoice.                                                                                                                                                                                                                              |
| `corrective`  | Corrected invoice that completely *replaces* the preceding document.                                                                                                                                                                                                                  |
| `credit-note` | Reflects a refund either partial or complete of the preceding document. A credit note effectively *extends* the previous document.                                                                                                                                                    |
| `debit-note`  | An additional set of charges to be added to the preceding document.                                                                                                                                                                                                                   |
| `other`       | Any other type of invoice that does not fit into the standard categories and implies that any scenarios defined in tax regimes or addons will not be applied. This is useful for being able to create invoices with custom types in extensions, but is not recommend for general use. |

## Validation Rules

| Field                                                                     | Test                                                                                                         | Validation Code / Message                                                           |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `type`<br /><small class="gobl-field-calculated">Calculated</small>       | <ul class="gobl-test"><li>Present</li></ul>                                                                  | `GOBL-BILL-INVOICE-01`<br />Invoice type is required                                |
| `type`<br /><small class="gobl-field-calculated">Calculated</small>       | <ul class="gobl-test"><li>One of \[standard, proforma, corrective, credit-note, debit-note, other]</li></ul> | `GOBL-BILL-INVOICE-02`<br />Invoice type is not valid                               |
| `issue_date`<br /><small class="gobl-field-calculated">Calculated</small> | <ul class="gobl-test"><li>Not zero</li></ul>                                                                 | `GOBL-BILL-INVOICE-03`<br />Invoice issue date is required                          |
| `currency`<br /><small class="gobl-field-calculated">Calculated</small>   | <ul class="gobl-test"><li>Present</li></ul>                                                                  | `GOBL-BILL-INVOICE-04`<br />Invoice currency is required                            |
| `supplier`                                                                | <ul class="gobl-test"><li class="gobl-test-present">Present</li></ul>                                        | `GOBL-BILL-INVOICE-05`<br />Invoice supplier is required                            |
| `supplier.name`                                                           | <ul class="gobl-test"><li class="gobl-test-present">Present</li></ul>                                        | `GOBL-BILL-INVOICE-06`<br />Invoice supplier name is required                       |
| `value_date`                                                              | <ul class="gobl-test"><li>Has tax point</li><li>Empty</li></ul>                                              | `GOBL-BILL-INVOICE-11`<br />Value date cannot be set when tax point is set          |
| `customer.name`                                                           | <ul class="gobl-test"><li>Has tax ID code</li><li class="gobl-test-present">Present</li></ul>                | `GOBL-BILL-INVOICE-07`<br />Invoice customer name required when tax ID is set       |
| `lines[*].item.price`                                                     | <ul class="gobl-test"><li class="gobl-test-present">Present</li></ul>                                        | `GOBL-BILL-INVOICE-08`<br />Invoice line item price is required                     |
| `totals`<br /><small class="gobl-field-calculated">Calculated</small>     | <ul class="gobl-test"><li>Present</li></ul>                                                                  | `GOBL-BILL-INVOICE-09`<br />Invoice totals are required                             |
| `lines`                                                                   | <ul class="gobl-test"><li>No discounts or charges</li><li class="gobl-test-present">Present</li></ul>        | `GOBL-BILL-INVOICE-10`<br />Invoice lines are required without discounts or charges |