---
title: "Record credit note"
method: POST
path: "/companies/{companyId}/credit-notes/{creditNoteId}/record"
tags: ["credit-notes"]
---

# Record credit note

`POST /companies/{companyId}/credit-notes/{creditNoteId}/record`

## Request

- Base URL: `https://api.bokio.se/v1`
- URL: `https://api.bokio.se/v1/companies/{companyId}/credit-notes/{creditNoteId}/record`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `/authorize`
    - Client credentials
    - Token URL: `/token` scopes: `credit-notes:write`

Record a credit note.

**Scope:** `credit-notes:write`

## Response `200`

Credit note recorded successfully

- CreditNote
  - `id` string, uuid, required: The unique identifier of the credit note
  - `invoiceRef` object: Reference to the original invoice being credited
    - `id` string, uuid: The unique identifier of the original invoice
    - `invoiceNumber` string: The invoice number of the original invoice
  - `customerRef` CustomerRef, nullable: Reference to a customer
    - `id` string, uuid: Unique identifier of the customer
    - `name` string: Name of the customer
    - `customerNumber` string: Customer number of the referenced customer
  - `contactDetailRef` object, nullable
    - `id` string, uuid, nullable
    - `email` string, nullable
    - `phone` string, nullable
  - `invoiceNumber` string, nullable: The credit note number
  - `orderNumberReference` string, nullable: The order number associated with the invoice.
  - `projectReference` string, nullable: The project reference associated with the credit note.
  - `buyerReference` string, nullable: The buyer reference associated with the credit note.
  - `contractReference` string, nullable: The contract reference associated with the credit note.
  - `currency` string, required: ISO 4217 currency code
  - `currencyRate` number, double
  - `totalAmount` number, double: Total amount of the credit note including VAT.
  - `totalTax` number, double
  - `paidAmount` number, double
  - `status` 'draft' | 'published': The status of the credit note
  - `creditDate` string, date, required
  - `dueDate` string, date, required
  - `publishedDateTime` string, date-time, nullable: The date when the credit note was published (null for draft)
  - `lineItems` InvoiceItem[], required: Line items for the credit note. The `discount` field on a line item is read-only for credit notes that are connected to an original invoice: the discount is taken from the original invoice.
    - 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. `unitPrice` and `quantity` can be overridden on this line item; `description`, `productType`, `unitType`, `customUnitType`, `taxRate`, `bookkeepingAccountNumber` (and `unitPrice` when not set) come from the 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' | 'custom': When set to `custom`, `customUnitType` is required; otherwise `customUnitType` must be omitted or null.
        - `customUnitType` string, nullable: Custom sales unit text. Required when `unitType` is `custom`; must be omitted or null otherwise.
        - `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.
        - `discount` Discount, nullable: A per-line discount. Either a percentage of the line total or a fixed amount in the invoice currency.
          - `type` 'percentage' | 'amount', required: `percentage` applies `value` as a percentage of the line total; `amount` subtracts `value` as a fixed amount in the invoice currency.
          - `value` number, double, required: For `percentage`, a value that must be greater than 0 and must not exceed 100. For `amount`, a value in the invoice currency that must be greater than 0 and must not exceed the line total (`quantity` × `unitPrice`).
        - `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
        - `reverseChargeType` 'construction' | 'null', nullable: The reverse charge type applied to this line item. Omit or set to null when reverse charge does not apply. - `construction`: Applies construction reverse charge. Only valid for service line items and cannot be combined with tax reduction.
        - `projectRef` ProjectRef, nullable: Reference to a project. **Preview:** This field is in preview and may change or be removed before general availability. [Read the full preview policy](/reference/versioning#preview)
          - `id` string, uuid, nullable
          - `projectName` string
          - `projectNumber` string
        - `costCenterRef` CostCenterRef, nullable: Reference to a cost center tag value. Should be a valid dimension 1 tag value. **Preview:** This field is in preview and may change or be removed before general availability. [Read the full preview policy](/reference/versioning#preview)
          - `tagId` string, uuid, nullable
          - `tagName` string
      - 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
        - `projectRef` ProjectRef, nullable: Reference to a project. **Preview:** This field is in preview and may change or be removed before general availability. [Read the full preview policy](/reference/versioning#preview)
          - `id` string, uuid, nullable
          - `projectName` string
          - `projectNumber` string
        - `costCenterRef` CostCenterRef, nullable: Reference to a cost center tag value. Should be a valid dimension 1 tag value. **Preview:** This field is in preview and may change or be removed before general availability. [Read the full preview policy](/reference/versioning#preview)
          - `tagId` string, uuid, nullable
          - `tagName` string
  - `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[], nullable
    - `id` string, uuid
    - `name` string
  - `journalEntryRef` object, nullable
    - `id` string, uuid
  - `metadata` object, nullable: 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`: Invalid request or invoice payment cannot be recorded
- `404`: Credit note not found

## Changes

- **2026-11-03** `9395020f3da2`: 3 warning, 9 info
  - removed the optional property `customerRef/id` from the response with the `200` status
  - removed the optional property `customerRef/name` from the response with the `200` status
  - added the new `custom` enum value to the `lineItems/items/oneOf[subschema #1: lineItem]/oneOf[subschema #1: salesItem]/unitType` response property for the response status `200`
  - added the optional property `lineItems/items/oneOf[subschema #1: lineItem]/oneOf[subschema #1: salesItem]/costCenterRef` to the response with the `200` status
  - …8 more

[Operation history](https://skmtc.dev/bokio/apis/company-api/changes/companies/:companyId/credit-notes/:creditNoteId/record/post.md)

---

[API](https://skmtc.dev/bokio/apis/company-api.md) - [All operations](https://skmtc.dev/bokio/apis/company-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bokio/apis/company-api/revisions/9395020f3da2?raw)