OpenAPI Specification
openapi: 3.0.3
info:
version: '1.0'
title: Company authorization credit-notes API
description: The Bokio Company API containing all resources for company tenant.
termsOfService: https://docs.bokio.se/page/terms/
contact:
name: Bokio
url: https://docs.bokio.se
email: support@bokio.se
servers:
- url: https://api.bokio.se/v1
description: Bokio API
x-bokio-api: true
security:
- tokenAuth: []
tags:
- name: credit-notes
description: Operations for managing credit notes
paths:
/companies/{companyId}/credit-notes:
parameters:
- name: companyId
in: path
required: true
description: Unique identifier of the company
schema:
type: string
format: uuid
example: ea9ee4dd-fae3-4aec-a7db-6fc9cc1f8135
get:
tags:
- credit-notes
summary: List credit notes
description: 'Returns a list of credit notes for the company.
**Scope:** `credit-notes:read`
'
operationId: list-credit-notes-v1
parameters:
- name: page
in: query
description: Page number for pagination
schema:
type: integer
format: int32
minimum: 1
default: 1
- name: pageSize
in: query
description: Number of items per page
schema:
type: integer
format: int32
minimum: 1
maximum: 100
default: 20
- name: query
in: query
required: false
description: 'Optional query to filter the data set with supported fields listed below and [available operations](filtering).
View documentation for filtering on metatdata [here](metadata).
| Field | Type |
| -------------------- | ----------- |
| type | string |
| customerRef | string |
| orderNumberReference | string |
| projectReference | string |
| buyerReference | string |
| contractReference | string |
| currency | string |
| totalAmount | number |
| status | string |
| invoiceDate | date |
| dueDate | date |
| metadata | string |
'
schema:
type: string
example: dueDate==2024-10-10&¤cy==SEK
responses:
'200':
description: List of credit notes
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/pagedResponse'
- type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/creditNote'
security:
- tokenAuth: []
- access_token:
- credit-notes:read
/companies/{companyId}/credit-notes/{creditNoteId}:
parameters:
- name: companyId
in: path
required: true
description: Unique identifier of the company
schema:
type: string
format: uuid
example: ea9ee4dd-fae3-4aec-a7db-6fc9cc1f8135
- name: creditNoteId
in: path
required: true
description: Unique identifier of the credit note
schema:
type: string
format: uuid
example: b529df79-eb7f-5ef0-a8dc-c2b71f953554
get:
tags:
- credit-notes
summary: Get a credit note
description: 'Retrieves a specific credit note by its ID.
**Scope:** `credit-notes:read`
'
operationId: get-credit-note-v1
responses:
'200':
description: Credit note found
content:
application/json:
schema:
$ref: '#/components/schemas/creditNote'
'404':
description: Credit note not found
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
notFound:
summary: Credit note not found
value:
code: not-found
message: Credit note not found
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
security:
- tokenAuth: []
- access_token:
- credit-notes:read
put:
tags:
- credit-notes
summary: Update a credit note
description: 'Updates an existing credit note. Only draft credit notes can be updated.
**Scope:** `credit-notes:write`
'
operationId: update-credit-note-v1
requestBody:
description: Updated credit note information
content:
application/json:
schema:
$ref: '#/components/schemas/creditNote'
examples:
creditNote:
summary: Example credit note update
value:
id: b529df79-eb7f-5ef0-a8dc-c2b71f953554
orderNumberReference: ORD-5678
projectReference: PROJ-001
buyerReference: BUYER-123
contractReference: CONTRACT-456
currency: SEK
currencyRate: 1
creditDate: 2024-10-15
dueDate: 2024-11-15
lineItems:
- id: 1
itemRef:
id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
description: Product 1
description: Product 1 (Updated)
itemType: salesItem
productType: goods
quantity: 3
unitPrice: 100
taxRate: 25
deliveryAddress:
line1: Delivery Street 15
line2: Floor 2
city: Stockholm
postalCode: 111 11
country: SE
responses:
'200':
description: Credit note updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/creditNote'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
validationError:
summary: Validation error
value:
code: validation-error
message: One or more validation errors occurred
errors:
- field: '#/creditDate'
message: The credit date field is required
'404':
description: Credit note not found
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
security:
- tokenAuth: []
- access_token:
- credit-notes:write
delete:
tags:
- credit-notes
summary: Delete a credit note
description: 'Deletes a draft credit note. Only draft credit notes can be deleted.
**Scope:** `credit-notes:write`
'
operationId: delete-credit-note-with-id
security:
- tokenAuth: []
- access_token:
- credit-notes:write
responses:
'204':
description: Credit note deleted successfully
'400':
description: Credit note cannot be deleted
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
CreditNoteCannotBeDeleted:
value:
code: operation-not-allowed
message: Credit note with value b529df79-eb7f-5ef0-a8dc-c2b71f953554 cannot be deleted as it is not in draft status
bokioErrorId: 4d408943-7a1e-47ac-85a7-ac52b2c210d3
/companies/{companyId}/credit-notes/{creditNoteId}/publish:
parameters:
- name: companyId
in: path
required: true
description: Unique identifier of the company
schema:
type: string
format: uuid
example: ea9ee4dd-fae3-4aec-a7db-6fc9cc1f8135
- name: creditNoteId
in: path
required: true
description: Unique identifier of the credit note
schema:
type: string
format: uuid
example: b529df79-eb7f-5ef0-a8dc-c2b71f953554
post:
tags:
- credit-notes
summary: Publish a credit note
description: 'Publishes a draft credit note, making it official and immutable.
**Scope:** `credit-notes:write`
'
operationId: publish-credit-note-v1
responses:
'200':
description: Credit note published successfully
content:
application/json:
schema:
$ref: '#/components/schemas/creditNote'
'400':
description: Credit note cannot be published
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
'404':
description: Credit note not found
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
security:
- tokenAuth: []
- access_token:
- credit-notes:write
/companies/{companyId}/credit-notes/{creditNoteId}/record:
parameters:
- name: companyId
in: path
required: true
description: Unique identifier of the company
schema:
type: string
format: uuid
example: ea9ee4dd-fae3-4aec-a7db-6fc9cc1f8135
- name: creditNoteId
in: path
required: true
description: Unique identifier of the credit note
schema:
type: string
format: uuid
example: b529df79-eb7f-5ef0-a8dc-c2b71f953554
post:
tags:
- credit-notes
summary: Record credit note
description: 'Record a credit note.
**Scope:** `credit-notes:write`
'
operationId: record-credit-note-with-id
security:
- tokenAuth: []
- access_token:
- credit-notes:write
responses:
'200':
description: Credit note recorded successfully
content:
application/json:
schema:
$ref: '#/components/schemas/creditNote'
examples:
creditNoteRecorded:
summary: Credit note recorded successfully
value:
id: b529df79-eb7f-5ef0-a8dc-c2b71f953554
status: published
invoiceNumber: CN-2024-001
invoiceRef:
id: a419cf69-db6f-4de9-992c-b1a60942a443
invoiceNumber: IN-2024-001
customerRef:
id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
name: customer 1
contactDetailRef:
id: d3b07384-d9a0-4c9b-8b3a-6e1f2a5c8d4e
email: contact@customer1.com
phone: '+46701234567'
currency: SEK
currencyRate: 1
totalAmount: 200
totalTax: 50
paidAmount: 0
creditDate: 2024-10-15
dueDate: 2024-11-15
publishedDateTime: 2024-10-15 12:00:00+00:00
projectReference: PROJ-001
buyerReference: BUYER-123
contractReference: CONTRACT-456
lineItems:
- id: 1
itemRef:
id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
description: Product 1
description: Product 1
itemType: salesItem
productType: goods
quantity: 2
unitPrice: 100
taxRate: 25
billingAddress:
line1: Älvsborgsvägen 10
line2: null
city: Göteborg
postalCode: 123 45
country: SE
deliveryAddress:
line1: Delivery Street 15
line2: Floor 2
city: Stockholm
postalCode: 111 11
country: SE
attachmentRefs:
- id: 240a4af0-edfd-47b1-b4ab-f30450eaac19
fileName: myfile.pdf
- id: 94a8f806-8493-40f6-9d5b-0495c84f8ab9
fileName: myfile2.pdf
journalEntryRef:
id: 89c9566a-9f7a-4894-aedd-4f382006f687
metadata:
project: Website Redesign
department: IT
externalId: EXT-INV-2024-001
'400':
description: Invalid request or invoice payment cannot be recorded
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
InvalidRequest:
value:
code: validation-error
message: Action cannot be performed on credit note with value b529df79-eb7f-5ef0-a8dc-c2b71f953554
bokioErrorId: 4d408943-7a1e-47ac-85a7-ac52b2c210d3
'404':
description: Credit note not found
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
CreditNoteNotFound:
value:
code: not-found
message: The requested resource credit note with value b529df79-eb7f-5ef0-a8dc-c2b71f953554 was not found
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
/companies/{companyId}/credit-notes/{creditNoteId}/download:
parameters:
- name: companyId
in: path
required: true
description: Unique identifier of the company
schema:
type: string
format: uuid
example: ea9ee4dd-fae3-4aec-a7db-6fc9cc1f8135
- name: creditNoteId
in: path
required: true
description: Unique identifier of the credit note
schema:
type: string
format: uuid
example: b529df79-eb7f-5ef0-a8dc-c2b71f953554
get:
tags:
- credit-notes
summary: Download a credit note
description: 'Download the credit note PDF with the matching creditNoteId.
**NOTE:** The credit note must be in published status.
**Scope:** `credit-notes:read`
'
operationId: download-credit-note
responses:
'200':
description: Credit note found and downloaded successfully.
content:
application/pdf:
schema:
type: string
format: binary
examples:
Credit note found and downloaded successfully.:
value: credit-note.pdf
'400':
description: Credit note is not in published status
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
CreditNoteNotPublished:
value:
code: operation-not-allowed
message: The credit note must be in published status to download
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
'404':
description: Credit note not found
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
CreditNoteNotFound:
value:
code: not-found
message: The requested resource credit note with value b529df79-eb7f-5ef0-a8dc-c2b71f953554 was not found
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
security:
- tokenAuth: []
- access_token:
- credit-notes:read
components:
schemas:
apiError:
type: object
title: apiError
properties:
code:
type: string
message:
type: string
bokioErrorId:
type: string
format: uuid
errors:
type: array
items:
type: object
properties:
field:
type: string
message:
type: string
addressWithCountrySubdivision:
type: object
title: addressWithCountrySubdivision
required:
- line1
- city
- postalCode
- country
properties:
line1:
type: string
line2:
type: string
nullable: true
city:
type: string
postalCode:
type: string
country:
description: ISO 3166-1 alpha-2 country code
type: string
format: country
countrySubdivision:
description: ISO 3166-2 subdivision code (e.g. ENG, SCT, WLS, NIR for GB). Currently required for GB (United kingdom) country.
type: string
nullable: true
example:
line1: 10 Downing Street
line2: null
city: London
postalCode: SW1A 2AA
country: GB
countrySubdivision: ENG
pagedResponse:
type: object
title: pagedResponse
properties:
totalItems:
type: integer
format: int32
example: 1
totalPages:
type: integer
format: int32
example: 1
currentPage:
type: integer
format: int32
example: 1
salesInvoiceItem:
type: object
title: salesItem
required:
- description
- itemType
- productType
- quantity
- unitPrice
- taxRate
properties:
id:
type: integer
format: int64
nullable: true
description: Should not be set for new items
itemRef:
type: object
title: itemRef
nullable: true
description: '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
'
properties:
id:
type: string
format: uuid
description: Reference to existing salesItem id
example: 869a69a3-632b-4a09-899e-9dc03342b5dc
description:
type: string
nullable: true
readOnly: true
description:
type: string
itemType:
type: string
enum:
- salesItem
productType:
type: string
enum:
- goods
- services
unitType:
type: string
default: unspecified
enum:
- unspecified
- piece
- hour
- day
- month
- kilogram
- gram
- liter
- meter
- centimeter
- millimeter
- meterSquared
- meterCubic
- mile
- kilometer
- gigabyte
- hectar
- words
- year
- week
- minute
- megabyte
- ton
quantity:
type: number
format: double
default: 1
unitPrice:
type: number
format: double
taxRate:
type: number
format: double
bookkeepingAccountNumber:
type: integer
nullable: true
format: int32
description: 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:
type: object
nullable: true
allOf:
- $ref: '#/components/schemas/lineItemTaxReduction'
description: tax reduction categorization for this line item. When the invoice has a taxReduction, each service line item should specify its job type. The type must match the invoice-level taxReduction type.
example:
id: 1
itemRef:
id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
description: Installation work
description: Installation work
itemType: salesItem
productType: services
unitType: hour
quantity: 10
unitPrice: 500
taxRate: 25
bookkeepingAccountNumber: 3389
taxReduction:
taxReductionType: rot
jobType: rotConstruction
creditNote:
type: object
required:
- id
- currency
- creditDate
- dueDate
- lineItems
properties:
id:
type: string
format: uuid
description: The unique identifier of the credit note
invoiceRef:
type: object
readOnly: true
properties:
id:
type: string
format: uuid
description: The unique identifier of the original invoice
invoiceNumber:
type: string
readOnly: true
description: The invoice number of the original invoice
description: Reference to the original invoice being credited
customerRef:
type: object
readOnly: true
properties:
id:
type: string
format: uuid
readOnly: true
name:
type: string
readOnly: true
contactDetailRef:
type: object
nullable: true
readOnly: true
properties:
id:
type: string
format: uuid
readOnly: true
nullable: true
email:
type: string
readOnly: true
nullable: true
phone:
type: string
readOnly: true
nullable: true
invoiceNumber:
type: string
readOnly: true
nullable: true
description: The credit note number
orderNumberReference:
type: string
nullable: true
description: The order number associated with the invoice.
projectReference:
type: string
nullable: true
description: The project reference associated with the credit note.
buyerReference:
type: string
nullable: true
description: The buyer reference associated with the credit note.
contractReference:
type: string
nullable: true
description: The contract reference associated with the credit note.
currency:
description: ISO 4217 currency code
type: string
default: SEK
currencyRate:
type: number
format: double
default: 1
totalAmount:
type: number
format: double
readOnly: true
totalTax:
type: number
format: double
readOnly: true
paidAmount:
type: number
format: double
readOnly: true
status:
type: string
enum:
- draft
- published
description: The status of the credit note
readOnly: true
creditDate:
type: string
format: date
dueDate:
type: string
format: date
publishedDateTime:
type: string
nullable: true
format: date-time
description: The date when the credit note was published (null for draft)
readOnly: true
lineItems:
type: array
items:
oneOf:
- $ref: '#/components/schemas/invoiceItem'
billingAddress:
readOnly: true
oneOf:
- $ref: '#/components/schemas/addressWithCountrySubdivision'
deliveryAddress:
oneOf:
- $ref: '#/components/schemas/address'
attachmentRefs:
type: array
readOnly: true
nullable: true
items:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
name:
type: string
readOnly: true
journalEntryRef:
type: object
readOnly: true
nullable: true
properties:
id:
type: string
format: uuid
readOnly: true
metadata:
type: object
nullable: true
description: '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.
'
maxProperties: 10
additionalProperties:
type: string
example:
project: Website Redesign
department: IT
externalId: EXT-INV-2024-001
example:
id: b529df79-eb7f-5ef0-a8dc-c2b71f953554
status: published
invoiceNumber: CN-2024-001
invoiceRef:
id: a419cf69-db6f-4de9-992c-b1a60942a443
invoiceNumber: IN-2024-001
customerRef:
id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
name: customer 1
contactDetailRef:
id: d3b07384-d9a0-4c9b-8b3a-6e1f2a5c8d4e
email: contact@customer1.com
phone: '+46701234567'
currency: SEK
currencyRate: 1
totalAmount: 200
totalTax: 50
paidAmount: 0
creditDate: 2024-10-15
dueDate: 2024-11-15
publishedDateTime: 2024-10-15 12:00:00
projectReference: PROJ-001
buyerReference: BUYER-123
contractReference: CONTRACT-456
lineItems:
- id: 1
itemRef:
id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
description: Product 1
description: Product 1
itemType: salesItem
productType: goods
quantity: 2
unitPrice: 100
taxRate: 25
billingAddress:
line1: Älvsborgsvägen 10
line2: null
city: Göteborg
postalCode: 123 45
country: SE
deliveryAddress:
line1: Delivery Street 15
line2: Floor 2
city: Stockholm
postalCode: 111 11
country: SE
attachmentRefs:
- id: 240a4af0-edfd-47b1-b4ab-f30450eaac19
fileName: myfile.pdf
- id: 94a8f806-8493-40f6-9d5b-0495c84f8ab9
fileName: myfile2.pdf
journalEntryRef:
id: 340a4af0-edfd-47b1-b4ab-f30450eaac19
metadata:
project: Website Redesign
department: IT
externalId: EXT-INV-2024-001
lineItemTaxReduction:
type: object
nullable: true
title: lineItemTaxReduction
description: 'Tax reduction details for a line item. Only applicable to line items with productType `services` and unitType `hour` or `unspecified`.
'
required:
- taxReductionType
- jobType
properties:
taxReductionType:
type: string
enum:
- rot
- rut
description: The tax reduction type for this line item. Must match the invoice-level taxReduction type.
jobType:
type: string
enum:
- rotConstruction
- rotElectricity
- rotGlassPlate
- rotSoilWork
- rotSweeping
- rotPainting
- rotPlumbing
- rutChildServices
- rutDataITServices
- rutRemovalServices
- rutClothingCare
- rutPersonalHelpCare
- rutRepair
- rutSnow
- rutCleaning
- rutGardening
- rutWaterWashingOfTextiles
- rutFurnishing
- rutTransportOfHouseholdGoods
- rutHousingSupervision
description: '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
'
example:
taxReductionType: rot
jobType: rotConstruction
descriptionOnlyInvoiceItem:
type: object
title: descriptionOnlyItem
required:
- description
- itemType
properties:
id:
type: integer
format: int64
nullable: true
description: Should not be set for new items
itemRef:
type: object
nullable: true
description: 'Identifier of an existing descriptionOnlyItem to use as a template. The field itemType is required.
'
properties:
id:
type: string
format: uuid
description: Reference to existing descriptionOnlyItem id
example: 55c899c5-82b2-47fa-9c51-e35fc9b26443
description:
type: string
nullable: true
readOnly: true
description:
type: string
itemType:
type: string
enum:
- descriptionOnlyItem
example:
id: 2
itemRef:
id: e964435e-50ef-4524-a439-05ff87794952
description: Custom description line
description: Custom description line
itemType: descriptionOnlyItem
address:
type: object
title: address
properties:
line1:
type: string
line2:
type: string
nullable: true
city:
type: string
postalCode:
type: string
country:
description: ISO 3166-1 alpha-2 country code
type: string
format: country
example:
line1: Delivery Street 15
line2: Floor 2
city: Stockholm
postalCode: 123 45
country: SE
invoiceItem:
type: object
title: lineItem
oneOf:
- $ref: '#/components/schemas/salesInvoiceItem'
- $ref: '#/components/schemas/descriptionOnlyInvoiceItem'
securitySchemes:
tokenAuth:
type: http
scheme: bearer
access_token:
type: oauth2
flows:
clientCredentials:
tokenUrl: /token
scopes: {}
authorizationCode:
authorizationUrl: /authorize
tokenUrl: /token
scopes:
bank-payments:read-limited: Read access to bank payments created by the integration
bank-payments:write: Write access to bank payments
chart-of-accounts:read: Read access to chart of accounts
company-information:read: Read access to company information
credit-notes:read: Read access to credit notes
credit-notes:write: Write access to credit notes
customers:read: Read access to customers
customers:write: Write access to customers
fiscal-years:read: Read access to fiscal years
invoices:read: Read access to invoices
invoices:write: Write access to invoices
items:read: Read access to items
items:write: Write access to items
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bokio/refs/heads/main/openapi/bokio-credit-notes-api-openapi.yml