# Create an invoice

> Creates a finalized invoice and queues its PDF. Fires the invoice.created webhook.

## POST /invoices

Creates a finalized invoice and queues its PDF. Fires the `invoice.created` webhook.

**Numbering.** Omit `invoice_number` to take the next number of the `series`: the series counter, otherwise
the highest existing number in that series plus one, otherwise `1`. An explicit number must be unique
within the series. Numbers are returned zero-padded to three digits.

**Amounts.** Each product line carries exactly one of `price` (unit price excluding VAT), `total` (line total
excluding VAT) or `total_incl_vat`; the other two are derived. `vat_percentage` is required on the VAT
invoice types (`vat_invoice`, `preliminary_vat_invoice`, `credit_vat_invoice`) and whenever the seller has a
`vat_code`; leave it out on non-VAT types.

**Seller.** Send `use_default_seller_info: true` to copy the seller block from the business profile (plus
the custom fields of the latest invoice); `seller` is then prohibited. Otherwise send `seller` with the fields
that match the business type: companies use `company_name` and `company_code`, individual activities use
`first_name`, `last_name` and `individual_activity_id` (`company_code` and `individual_activity_id` are
optional). VAT invoice types require `seller.vat_code` when `seller` is sent; with the default seller info the
profile's VAT code is copied as it is.

### Request and responses

```json
{
  "servers": [
    {
      "url": "https://app.fsaskaita.lt/api",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "operation": {
    "operationId": "createInvoice",
    "description": "Creates a finalized invoice and queues its PDF. Fires the `invoice.created` webhook.\n\n**Numbering.** Omit `invoice_number` to take the next number of the `series`: the series counter, otherwise\nthe highest existing number in that series plus one, otherwise `1`. An explicit number must be unique\nwithin the series. Numbers are returned zero-padded to three digits.\n\n**Amounts.** Each product line carries exactly one of `price` (unit price excluding VAT), `total` (line total\nexcluding VAT) or `total_incl_vat`; the other two are derived. `vat_percentage` is required on the VAT\ninvoice types (`vat_invoice`, `preliminary_vat_invoice`, `credit_vat_invoice`) and whenever the seller has a\n`vat_code`; leave it out on non-VAT types.\n\n**Seller.** Send `use_default_seller_info: true` to copy the seller block from the business profile (plus\nthe custom fields of the latest invoice); `seller` is then prohibited. Otherwise send `seller` with the fields\nthat match the business type: companies use `company_name` and `company_code`, individual activities use\n`first_name`, `last_name` and `individual_activity_id` (`company_code` and `individual_activity_id` are\noptional). VAT invoice types require `seller.vat_code` when `seller` is sent; with the default seller info the\nprofile's VAT code is copied as it is.",
    "summary": "Create an invoice",
    "tags": [
      "Invoices"
    ],
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/InvoiceInput"
          }
        }
      }
    },
    "responses": {
      "201": {
        "description": "`Invoice`",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "data": {
                  "$ref": "#/components/schemas/Invoice"
                }
              },
              "required": [
                "data"
              ]
            }
          }
        }
      },
      "401": {
        "$ref": "#/components/responses/AuthenticationException"
      },
      "403": {
        "$ref": "#/components/responses/AuthorizationException"
      },
      "422": {
        "$ref": "#/components/responses/ValidationException"
      },
      "429": {
        "description": "Rate limit exceeded. The limit is 60 requests per minute per business, shared across all of its tokens. Wait `Retry-After` seconds before retrying.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "message"
              ]
            }
          }
        },
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying.",
            "schema": {
              "type": "integer"
            }
          },
          "X-RateLimit-Limit": {
            "description": "Requests allowed per minute.",
            "schema": {
              "type": "integer"
            }
          },
          "X-RateLimit-Remaining": {
            "description": "Requests left in the current minute.",
            "schema": {
              "type": "integer"
            }
          },
          "X-RateLimit-Reset": {
            "description": "Unix timestamp at which the window resets.",
            "schema": {
              "type": "integer"
            }
          }
        }
      }
    }
  },
  "securitySchemes": {
    "bearerAuth": {
      "type": "http",
      "description": "Business token created in the app under Settings, Integrations, API. The token is scoped to exactly one business, has no expiry and is shown only once. Send it as `Authorization: Bearer <token>` together with `Accept: application/json`.",
      "scheme": "bearer"
    }
  }
}
```

### Referenced components

```json
{
  "#/components/schemas/InvoiceInput": {
    "type": "object",
    "description": "Body of `POST /invoices` and `PUT /invoices/{invoice}`. On update every field is replaced with what you send;\nalways resend `invoice_number` or the invoice is renumbered.",
    "properties": {
      "type": {
        "type": "string",
        "description": "Invoice type. The `*vat_invoice` types require `seller.vat_code` and `vat_percentage` on every line.",
        "enum": [
          "regular_invoice",
          "vat_invoice",
          "preliminary_invoice",
          "preliminary_vat_invoice",
          "credit_invoice",
          "credit_vat_invoice"
        ],
        "examples": [
          "vat_invoice"
        ]
      },
      "invoice_date": {
        "type": "string",
        "format": "date",
        "description": "Issue date.",
        "examples": [
          "2026-09-12"
        ]
      },
      "pay_until_date": {
        "type": [
          "string",
          "null"
        ],
        "format": "date",
        "description": "Due date.",
        "examples": [
          "2026-09-26"
        ]
      },
      "series": {
        "type": "string",
        "description": "Series code the number belongs to. A new code starts its own counter.",
        "examples": [
          "SF"
        ],
        "maxLength": 255
      },
      "notes": {
        "type": [
          "string",
          "null"
        ],
        "description": "Free text printed under the lines.",
        "maxLength": 255
      },
      "currency": {
        "type": "string",
        "description": "One of the codes from `GET /currencies`.",
        "examples": [
          "EUR"
        ]
      },
      "payment_status": {
        "anyOf": [
          {
            "description": "Defaults to `not_paid` on create; when omitted on update the current status is kept.",
            "$ref": "#/components/schemas/PaymentStatus"
          },
          {
            "type": "null"
          }
        ]
      },
      "language": {
        "type": [
          "string",
          "null"
        ],
        "description": "Language of the PDF and the share page. Defaults to `lt`.",
        "enum": [
          "en",
          "lt",
          "es",
          "de",
          "fr",
          null
        ]
      },
      "invoice_number": {
        "type": [
          "string",
          "null"
        ],
        "description": "Number within the series; must be unique there. Omit on create to auto-number. **On update always\nresend the current number**, otherwise the invoice is renumbered from the series counter. Accepts the\npadded (`\"007\"`) or unpadded (`\"7\"`) form; numbers are compared exactly as sent, so use one form\nconsistently within a series.",
        "pattern": "^(.*)+$",
        "examples": [
          "7"
        ],
        "maxLength": 255
      },
      "buyer": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "`company` or `individual`. `person` is accepted as a legacy alias of `individual`; responses always\nreturn `individual`.",
            "enum": [
              "company",
              "person",
              "individual"
            ],
            "examples": [
              "company"
            ]
          },
          "company_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Required for companies, prohibited for individuals."
          },
          "company_code": {
            "type": [
              "string",
              "null"
            ],
            "description": "Prohibited for individuals.",
            "maxLength": 255
          },
          "first_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Required for individuals, prohibited for companies.",
            "maxLength": 255
          },
          "last_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Required for individuals, prohibited for companies.",
            "maxLength": 255
          },
          "individual_activity_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Individual activity certificate number; prohibited for companies.",
            "maxLength": 255
          },
          "address": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 255
          },
          "vat_code": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 255
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 255
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 255
          }
        },
        "required": [
          "type"
        ]
      },
      "use_default_seller_info": {
        "type": [
          "boolean",
          "null"
        ],
        "description": "When `true` the seller block is copied from the business profile (plus the custom fields of the latest\ninvoice) and `seller` must be omitted.",
        "examples": [
          true
        ]
      },
      "seller": {
        "type": "object",
        "description": "Required unless `use_default_seller_info` is `true`. Which fields are required depends on the business\ntype: companies send `company_name` (required) and `company_code` (optional); individual activities send\n`first_name` and `last_name` (required) and `individual_activity_id` (optional). Fields of the other kind\nare rejected.",
        "properties": {
          "address": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 255
          },
          "vat_code": {
            "type": [
              "string",
              "null"
            ],
            "description": "Required for the `*vat_invoice` types when `seller` is sent.",
            "maxLength": 255
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 255
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 255
          },
          "company_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Companies only.",
            "maxLength": 255
          },
          "company_code": {
            "type": [
              "string",
              "null"
            ],
            "description": "Companies only.",
            "maxLength": 255
          },
          "first_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Individual activities only.",
            "maxLength": 255
          },
          "last_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Individual activities only.",
            "maxLength": 255
          },
          "individual_activity_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Individual activities only.",
            "maxLength": 255
          },
          "custom_fields": {
            "type": [
              "array",
              "null"
            ],
            "description": "Extra label/value pairs printed in the seller block.",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string",
                  "maxLength": 255
                },
                "value": {
                  "type": "string",
                  "maxLength": 255
                }
              },
              "required": [
                "label",
                "value"
              ]
            }
          }
        }
      },
      "products": {
        "type": "array",
        "description": "Invoice lines. Each line carries exactly one of `price`, `total` or `total_incl_vat`.",
        "items": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "examples": [
                "Consulting"
              ],
              "maxLength": 255
            },
            "units": {
              "type": "string",
              "examples": [
                "h"
              ],
              "maxLength": 255
            },
            "quantity": {
              "type": "number",
              "examples": [
                2
              ]
            },
            "price": {
              "type": [
                "number",
                "null"
              ],
              "description": "Unit price excluding VAT. Mutually exclusive with `total` and `total_incl_vat`.",
              "examples": [
                50
              ]
            },
            "total": {
              "type": [
                "number",
                "null"
              ],
              "description": "Line total excluding VAT. Mutually exclusive with `price` and `total_incl_vat`."
            },
            "total_incl_vat": {
              "type": [
                "number",
                "null"
              ],
              "description": "Line total including VAT. Mutually exclusive with `price` and `total`."
            },
            "vat_percentage": {
              "type": [
                "number",
                "null"
              ],
              "description": "VAT rate, 0-100. Required whenever `seller.vat_code` is sent and, with `use_default_seller_info`, on the\n`*vat_invoice` types. On non-VAT types the value is ignored and stored as null.",
              "examples": [
                21
              ],
              "minimum": 0,
              "maximum": 100
            }
          },
          "required": [
            "name",
            "units",
            "quantity"
          ]
        },
        "minItems": 1
      },
      "payment_options": {
        "type": [
          "array",
          "null"
        ],
        "description": "Payment details printed on the invoice.",
        "items": {
          "type": "object",
          "properties": {
            "type": {
              "description": "`bank` takes the bank fields below; `other` takes free-form `fields`.",
              "$ref": "#/components/schemas/PaymentOptionType"
            },
            "bank_account": {
              "type": "string",
              "description": "IBAN. Required for `bank`, prohibited otherwise.",
              "examples": [
                "LT601010012345678901"
              ],
              "maxLength": 255
            },
            "bank_name": {
              "type": "string",
              "description": "Required for `bank`, prohibited otherwise.",
              "maxLength": 255
            },
            "routing_or_sort_number": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 255
            },
            "swift_bic_code": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 255
            },
            "fields": {
              "type": [
                "array",
                "null"
              ],
              "description": "Required for `other`.",
              "items": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string",
                    "maxLength": 255
                  },
                  "value": {
                    "type": "string",
                    "maxLength": 255
                  }
                },
                "required": [
                  "label",
                  "value"
                ]
              }
            }
          },
          "required": [
            "type"
          ]
        }
      }
    },
    "required": [
      "type",
      "invoice_date",
      "series",
      "currency",
      "buyer",
      "seller",
      "products"
    ],
    "title": "InvoiceInput"
  },
  "#/components/schemas/PaymentStatus": {
    "type": "string",
    "enum": [
      "not_paid",
      "paid"
    ],
    "title": "PaymentStatus"
  },
  "#/components/schemas/PaymentOptionType": {
    "type": "string",
    "description": "`bank` carries the bank account fields; `other` carries free-form label/value `fields`.\n",
    "enum": [
      "bank",
      "other"
    ],
    "title": "PaymentOptionType"
  },
  "#/components/schemas/Invoice": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      },
      "business_id": {
        "type": "string",
        "format": "uuid"
      },
      "invoice_type": {
        "$ref": "#/components/schemas/InvoiceType"
      },
      "series": {
        "type": "string"
      },
      "invoice_number": {
        "type": "string",
        "description": "Zero-padded to three digits, e.g. `\"007\"`. Send it back padded or unpadded on update; both are accepted."
      },
      "invoice_date": {
        "type": "string",
        "format": "date",
        "description": "Issue date, `Y-m-d`."
      },
      "pay_until_date": {
        "type": [
          "string",
          "null"
        ],
        "format": "date",
        "description": "Due date, `Y-m-d`."
      },
      "language": {
        "$ref": "#/components/schemas/InvoiceLanguage"
      },
      "subtotal": {
        "type": "number",
        "description": "Sum of the lines excluding VAT."
      },
      "vat": {
        "type": "number"
      },
      "total_incl_vat": {
        "type": "number"
      },
      "currency": {
        "type": "string"
      },
      "payment_status": {
        "$ref": "#/components/schemas/PaymentStatus"
      },
      "notes": {
        "type": [
          "string",
          "null"
        ]
      },
      "share_link": {
        "type": "string",
        "format": "uri",
        "description": "Public link to the invoice; anyone with the link can view it."
      },
      "seller": {
        "type": "object",
        "properties": {
          "business_type": {
            "$ref": "#/components/schemas/BusinessType"
          },
          "first_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "company_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "company_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "individual_activity_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "vat_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "address": {
            "type": [
              "string",
              "null"
            ]
          },
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "custom_fields": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              },
              "required": [
                "label",
                "value"
              ]
            }
          }
        },
        "required": [
          "business_type",
          "first_name",
          "last_name",
          "company_name",
          "company_code",
          "individual_activity_id",
          "vat_code",
          "address",
          "email",
          "phone",
          "custom_fields"
        ]
      },
      "buyer": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "`person` sent on input is returned as `individual`.",
            "enum": [
              "company",
              "individual"
            ]
          },
          "first_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "company_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "company_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "individual_activity_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "vat_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "address": {
            "type": [
              "string",
              "null"
            ]
          },
          "email": {
            "type": [
              "string",
              "null"
            ]
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "type",
          "first_name",
          "last_name",
          "company_name",
          "company_code",
          "individual_activity_id",
          "vat_code",
          "address",
          "email",
          "phone"
        ]
      },
      "items": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/InvoiceItem"
        }
      },
      "payment_options": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/PaymentOption"
        }
      },
      "created_at": {
        "type": "integer",
        "description": "Unix timestamp, seconds."
      },
      "updated_at": {
        "type": "integer",
        "description": "Unix timestamp, seconds."
      }
    },
    "required": [
      "id",
      "business_id",
      "invoice_type",
      "series",
      "invoice_number",
      "invoice_date",
      "pay_until_date",
      "language",
      "subtotal",
      "vat",
      "total_incl_vat",
      "currency",
      "payment_status",
      "notes",
      "share_link",
      "seller",
      "buyer",
      "items",
      "payment_options",
      "created_at",
      "updated_at"
    ],
    "title": "Invoice"
  },
  "#/components/schemas/InvoiceType": {
    "type": "string",
    "description": "The three `*vat_invoice` types require `vat_percentage` on every line and, when `seller` is sent, `seller.vat_code`.\n",
    "enum": [
      "regular_invoice",
      "vat_invoice",
      "preliminary_invoice",
      "preliminary_vat_invoice",
      "credit_invoice",
      "credit_vat_invoice"
    ],
    "title": "InvoiceType"
  },
  "#/components/schemas/InvoiceLanguage": {
    "type": "string",
    "description": "Language of the PDF and the public share page.\n",
    "enum": [
      "en",
      "lt",
      "es",
      "de",
      "fr"
    ],
    "title": "InvoiceLanguage"
  },
  "#/components/schemas/BusinessType": {
    "type": "string",
    "description": "Every type except `individual_activity` is a company.\n",
    "enum": [
      "small_partnership",
      "individual_activity",
      "private_limited_liability_company",
      "sole_proprietorship",
      "public_institution",
      "association",
      "joint_stock_company"
    ],
    "title": "BusinessType"
  },
  "#/components/schemas/InvoiceItem": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "format": "uuid"
      },
      "name": {
        "type": "string"
      },
      "price": {
        "type": "number"
      },
      "vat_percentage": {
        "type": [
          "number",
          "null"
        ]
      },
      "quantity": {
        "type": "number"
      },
      "units": {
        "type": "string"
      }
    },
    "required": [
      "id",
      "name",
      "price",
      "vat_percentage",
      "quantity",
      "units"
    ],
    "title": "InvoiceItem"
  },
  "#/components/schemas/PaymentOption": {
    "type": "object",
    "properties": {
      "type": {
        "$ref": "#/components/schemas/PaymentOptionType"
      },
      "bank_account": {
        "type": [
          "string",
          "null"
        ]
      },
      "bank_name": {
        "type": [
          "string",
          "null"
        ]
      },
      "routing_or_sort_number": {
        "type": [
          "string",
          "null"
        ]
      },
      "swift_bic_code": {
        "type": [
          "string",
          "null"
        ]
      },
      "fields": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/LabelValue"
        }
      }
    },
    "required": [
      "type",
      "fields"
    ],
    "title": "PaymentOption"
  },
  "#/components/schemas/LabelValue": {
    "type": "object",
    "properties": {
      "label": {
        "type": "string"
      },
      "value": {
        "type": "string"
      }
    },
    "required": [
      "label",
      "value"
    ],
    "title": "LabelValue"
  },
  "#/components/responses/AuthenticationException": {
    "description": "Unauthenticated",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "Error overview."
            }
          },
          "required": [
            "message"
          ]
        }
      }
    }
  },
  "#/components/responses/AuthorizationException": {
    "description": "Authorization error",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "Error overview."
            }
          },
          "required": [
            "message"
          ]
        }
      }
    }
  },
  "#/components/responses/ValidationException": {
    "description": "Validation error",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "message": {
              "type": "string",
              "description": "Errors overview."
            },
            "errors": {
              "type": "object",
              "description": "A detailed description of each field that failed validation.",
              "additionalProperties": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "required": [
            "message",
            "errors"
          ]
        }
      }
    }
  }
}
```