---
title: "Update an invoice"
method: PUT
path: "/companies/{companyId}/invoices/{invoiceId}"
tags: ["invoices"]
---

# Update an invoice

`PUT /companies/{companyId}/invoices/{invoiceId}`

Update an existing invoice draft for the company.

This operation will update all fields of the invoice. It's recommended that you perform a GET request
to the invoice first to get the current state of the invoice and then update the fields you want to change.

**NOTE:** It's only possible to update invoices that are in draft status.

**Tax reduction:** Only the integration that created the invoice can modify tax reduction data. If a different integration includes `taxReduction` changes in the request, the changes will be silently ignored and the existing tax reduction data will be preserved.

**Scope:** `invoices:write`

## Request body

- Invoice
  - `id` string, uuid
  - `type` 'invoice' | 'cashInvoice' — The type of the invoice can be invoice or cashInvoice. Can only be set to invoice when creating a new invoice and will default to invoice if not set.
  - `customerRef` object
    - `id` string, uuid
    - `name` string
  - `contactDetailRef` object, nullable
    - `id` string, uuid, nullable
    - `email` string, nullable
    - `phone` string, nullable
  - `invoiceNumber` string, nullable — The invoice number will be generated at the time of publishing the invoice.
  - `paymentReference` string, nullable — The payment reference (OCR number) for the invoice. Populated when the invoice is published, null for drafts.
  - `orderNumberReference` string, nullable — The order number associated with the invoice.
  - `projectReference` string, nullable — The project reference associated with the invoice.
  - `buyerReference` string, nullable — The buyer reference associated with the invoice.
  - `contractReference` string, nullable — The contract reference associated with the invoice.
  - `currency` string — ISO 4217 currency code
  - `currencyRate` number, double
  - `totalAmount` number, double
  - `totalTax` number, double
  - `paidAmount` number, double
  - `status` 'draft' | 'published' | 'paid' | 'overPaid' | 'underPaid' | 'overdue' | 'credited' | 'credit'
  - `invoiceDate` string, date, required
  - `dueDate` string, date — The due date for the invoice. Optional — when omitted, it is automatically calculated using the fallback chain: customer payment terms → company payment terms → 30 days from the invoice date.
  - `publishedDateTime` string, date-time, nullable — The date when the credit note was published (null for draft)
  - `lineItems` InvoiceItem[], required
    - union
      - object
        - `id` integer, nullable — Should not be set for new items
        - `itemRef` object, nullable — Identifier of an existing salesItem to use as a template. Fields itemType and quantity are required. Values in other fields will be overridden by values from this referenced item
          - `id` string, uuid — Reference to existing salesItem id
          - `description` string, nullable
        - `description` string, required
        - `itemType` 'salesItem', required
        - `productType` 'goods' | 'services', required
        - `unitType` 'unspecified' | 'piece' | 'hour' | 'day' | 'month' | 'kilogram' | 'gram' | 'liter' | 'meter' | 'centimeter' | 'millimeter' | 'meterSquared' | 'meterCubic' | 'mile' | 'kilometer' | 'gigabyte' | 'hectar' | 'words' | 'year' | 'week' | 'minute' | 'megabyte' | 'ton'
        - `quantity` number, double, required
        - `unitPrice` number, double, required
        - `taxRate` number, double, required
        - `bookkeepingAccountNumber` integer, nullable — Use the `bookkeepingAccountNumber` field in the line items to specify an accounting account other than the account that would be automatically be selected based on the item productType, taxRate, customer and company settings. Accounts that would be automatically selected cannot be set on this field.
        - `taxReduction` LineItemTaxReduction, nullable — Tax reduction details for a line item. Only applicable to line items with productType `services` and unitType `hour` or `unspecified`.
          - `taxReductionType` 'rot' | 'rut', required — The tax reduction type for this line item. Must match the invoice-level taxReduction type.
          - `jobType` 'rotConstruction' | 'rotElectricity' | 'rotGlassPlate' | 'rotSoilWork' | 'rotSweeping' | 'rotPainting' | 'rotPlumbing' | 'rutChildServices' | 'rutDataITServices' | 'rutRemovalServices' | 'rutClothingCare' | 'rutPersonalHelpCare' | 'rutRepair' | 'rutSnow' | 'rutCleaning' | 'rutGardening' | 'rutWaterWashingOfTextiles' | 'rutFurnishing' | 'rutTransportOfHouseholdGoods' | 'rutHousingSupervision', required — The job type categorizing the work. The prefix must match the tax reduction type: - ROT types: rotConstruction, rotElectricity, rotGlassPlate, rotSoilWork, rotSweeping, rotPainting, rotPlumbing - RUT types: rutChildServices, rutDataITServices, rutRemovalServices, rutClothingCare, rutPersonalHelpCare, rutRepair, rutSnow, rutCleaning, rutGardening, rutWaterWashingOfTextiles, rutFurnishing, rutTransportOfHouseholdGoods, rutHousingSupervision
      - object
        - `id` integer, nullable — Should not be set for new items
        - `itemRef` object, nullable — Identifier of an existing descriptionOnlyItem to use as a template. The field itemType is required.
          - `id` string, uuid — Reference to existing descriptionOnlyItem id
          - `description` string, nullable
        - `description` string, required
        - `itemType` 'descriptionOnlyItem', required
  - `billingAddress` AddressWithCountrySubdivision
    - `line1` string, required
    - `line2` string, nullable
    - `city` string, required
    - `postalCode` string, required
    - `country` string, country, required — ISO 3166-1 alpha-2 country code
    - `countrySubdivision` string, nullable — ISO 3166-2 subdivision code (e.g. ENG, SCT, WLS, NIR for GB). Currently required for GB (United kingdom) country.
  - `deliveryAddress` Address
    - `line1` string
    - `line2` string, nullable
    - `city` string
    - `postalCode` string
    - `country` string, country — ISO 3166-1 alpha-2 country code
  - `taxReduction` InvoiceTaxReduction, nullable — Tax reduction details for the invoice. **Ownership restriction:** Only the integration that created the invoice can manage tax reduction data. Other integrations can read tax reduction data, but personal numbers will be masked (see `personalNumber`).
    - `type` 'rot' | 'rut', required — The tax reduction type.
    - `description` string, required — Description of the tax reduction work performed.
    - `propertyType` 'realEstate' | 'housingDesignation', nullable — Required when type is `rot`. The type of property where the work is performed.
    - `realEstateNumber` string, nullable — Required when propertyType is `realEstate`. The real estate designation number.
    - `tenantOrgNumber` string, nullable — Required when propertyType is `housingDesignation`. The organisational number of the housing association (BRF).
    - `apartmentNumber` string, nullable — Required when propertyType is `housingDesignation`. The apartment number within the housing association.
    - `deductionAmount` number, double — The total deduction amount calculated from all deduction people.
    - `status` 'draft' | 'awaitingPayment' | 'readyToSubmit' | 'submitted' | 'removed' | 'completed' — The current status of the tax reduction.
    - `deductionPeople` InvoiceTaxReductionDeductionPerson[], required — The people eligible for the tax deduction. At least one person is required.
      - `personalNumber` string, required — Swedish personal number in format YYYYMMDD-XXXX. When the invoice was created by a different integration, the value is fully masked and returned as `YYYYMMDD-XXXX`.
      - `deductionAmount` number, double, required — The deduction amount for this person. Must be zero or greater.
  - `attachmentRefs` object[]
    - `id` string, uuid
    - `name` string
  - `journalEntryRef` object, nullable
    - `id` string, uuid
  - `creditNoteRefs` object[], nullable
    - `id` string, uuid
  - `metadata` object — Metadata fields for the invoice as string key-value pairs. These fields can be used for filtering.All metadata keys must start with a letter or underscore and contain only alphanumeric characters and underscores.

## Response `200`

Invoice updated

- Invoice
  - `id` string, uuid
  - `type` 'invoice' | 'cashInvoice' — The type of the invoice can be invoice or cashInvoice. Can only be set to invoice when creating a new invoice and will default to invoice if not set.
  - `customerRef` object
    - `id` string, uuid
    - `name` string
  - `contactDetailRef` object, nullable
    - `id` string, uuid, nullable
    - `email` string, nullable
    - `phone` string, nullable
  - `invoiceNumber` string, nullable — The invoice number will be generated at the time of publishing the invoice.
  - `paymentReference` string, nullable — The payment reference (OCR number) for the invoice. Populated when the invoice is published, null for drafts.
  - `orderNumberReference` string, nullable — The order number associated with the invoice.
  - `projectReference` string, nullable — The project reference associated with the invoice.
  - `buyerReference` string, nullable — The buyer reference associated with the invoice.
  - `contractReference` string, nullable — The contract reference associated with the invoice.
  - `currency` string — ISO 4217 currency code
  - `currencyRate` number, double
  - `totalAmount` number, double
  - `totalTax` number, double
  - `paidAmount` number, double
  - `status` 'draft' | 'published' | 'paid' | 'overPaid' | 'underPaid' | 'overdue' | 'credited' | 'credit'
  - `invoiceDate` string, date, required
  - `dueDate` string, date — The due date for the invoice. Optional — when omitted, it is automatically calculated using the fallback chain: customer payment terms → company payment terms → 30 days from the invoice date.
  - `publishedDateTime` string, date-time, nullable — The date when the credit note was published (null for draft)
  - `lineItems` InvoiceItem[], required
    - union
      - object
        - `id` integer, nullable — Should not be set for new items
        - `itemRef` object, nullable — Identifier of an existing salesItem to use as a template. Fields itemType and quantity are required. Values in other fields will be overridden by values from this referenced item
          - `id` string, uuid — Reference to existing salesItem id
          - `description` string, nullable
        - `description` string, required
        - `itemType` 'salesItem', required
        - `productType` 'goods' | 'services', required
        - `unitType` 'unspecified' | 'piece' | 'hour' | 'day' | 'month' | 'kilogram' | 'gram' | 'liter' | 'meter' | 'centimeter' | 'millimeter' | 'meterSquared' | 'meterCubic' | 'mile' | 'kilometer' | 'gigabyte' | 'hectar' | 'words' | 'year' | 'week' | 'minute' | 'megabyte' | 'ton'
        - `quantity` number, double, required
        - `unitPrice` number, double, required
        - `taxRate` number, double, required
        - `bookkeepingAccountNumber` integer, nullable — Use the `bookkeepingAccountNumber` field in the line items to specify an accounting account other than the account that would be automatically be selected based on the item productType, taxRate, customer and company settings. Accounts that would be automatically selected cannot be set on this field.
        - `taxReduction` LineItemTaxReduction, nullable — Tax reduction details for a line item. Only applicable to line items with productType `services` and unitType `hour` or `unspecified`.
          - `taxReductionType` 'rot' | 'rut', required — The tax reduction type for this line item. Must match the invoice-level taxReduction type.
          - `jobType` 'rotConstruction' | 'rotElectricity' | 'rotGlassPlate' | 'rotSoilWork' | 'rotSweeping' | 'rotPainting' | 'rotPlumbing' | 'rutChildServices' | 'rutDataITServices' | 'rutRemovalServices' | 'rutClothingCare' | 'rutPersonalHelpCare' | 'rutRepair' | 'rutSnow' | 'rutCleaning' | 'rutGardening' | 'rutWaterWashingOfTextiles' | 'rutFurnishing' | 'rutTransportOfHouseholdGoods' | 'rutHousingSupervision', required — The job type categorizing the work. The prefix must match the tax reduction type: - ROT types: rotConstruction, rotElectricity, rotGlassPlate, rotSoilWork, rotSweeping, rotPainting, rotPlumbing - RUT types: rutChildServices, rutDataITServices, rutRemovalServices, rutClothingCare, rutPersonalHelpCare, rutRepair, rutSnow, rutCleaning, rutGardening, rutWaterWashingOfTextiles, rutFurnishing, rutTransportOfHouseholdGoods, rutHousingSupervision
      - object
        - `id` integer, nullable — Should not be set for new items
        - `itemRef` object, nullable — Identifier of an existing descriptionOnlyItem to use as a template. The field itemType is required.
          - `id` string, uuid — Reference to existing descriptionOnlyItem id
          - `description` string, nullable
        - `description` string, required
        - `itemType` 'descriptionOnlyItem', required
  - `billingAddress` AddressWithCountrySubdivision
    - `line1` string, required
    - `line2` string, nullable
    - `city` string, required
    - `postalCode` string, required
    - `country` string, country, required — ISO 3166-1 alpha-2 country code
    - `countrySubdivision` string, nullable — ISO 3166-2 subdivision code (e.g. ENG, SCT, WLS, NIR for GB). Currently required for GB (United kingdom) country.
  - `deliveryAddress` Address
    - `line1` string
    - `line2` string, nullable
    - `city` string
    - `postalCode` string
    - `country` string, country — ISO 3166-1 alpha-2 country code
  - `taxReduction` InvoiceTaxReduction, nullable — Tax reduction details for the invoice. **Ownership restriction:** Only the integration that created the invoice can manage tax reduction data. Other integrations can read tax reduction data, but personal numbers will be masked (see `personalNumber`).
    - `type` 'rot' | 'rut', required — The tax reduction type.
    - `description` string, required — Description of the tax reduction work performed.
    - `propertyType` 'realEstate' | 'housingDesignation', nullable — Required when type is `rot`. The type of property where the work is performed.
    - `realEstateNumber` string, nullable — Required when propertyType is `realEstate`. The real estate designation number.
    - `tenantOrgNumber` string, nullable — Required when propertyType is `housingDesignation`. The organisational number of the housing association (BRF).
    - `apartmentNumber` string, nullable — Required when propertyType is `housingDesignation`. The apartment number within the housing association.
    - `deductionAmount` number, double — The total deduction amount calculated from all deduction people.
    - `status` 'draft' | 'awaitingPayment' | 'readyToSubmit' | 'submitted' | 'removed' | 'completed' — The current status of the tax reduction.
    - `deductionPeople` InvoiceTaxReductionDeductionPerson[], required — The people eligible for the tax deduction. At least one person is required.
      - `personalNumber` string, required — Swedish personal number in format YYYYMMDD-XXXX. When the invoice was created by a different integration, the value is fully masked and returned as `YYYYMMDD-XXXX`.
      - `deductionAmount` number, double, required — The deduction amount for this person. Must be zero or greater.
  - `attachmentRefs` object[]
    - `id` string, uuid
    - `name` string
  - `journalEntryRef` object, nullable
    - `id` string, uuid
  - `creditNoteRefs` object[], nullable
    - `id` string, uuid
  - `metadata` object — Metadata fields for the invoice as string key-value pairs. These fields can be used for filtering.All metadata keys must start with a letter or underscore and contain only alphanumeric characters and underscores.

## Other responses

- `400` — Missing required information

---

[API](https://skmtc.net/bokio/apis/company-api.md) · [All operations](https://skmtc.net/bokio/apis/company-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bokio/company-api/revisions/1bb5d09ce15e/schema)