Getting Started with the Invoice API

Bokio API Workflow: Creating and Managing an Invoice

This guide outlines a practical workflow using Bokio’s API for creating, publishing, and bookkeeping an invoice, including handling discounts, payments, and bank fee settlements.

The workflow covers:

Create or ensure the customer exists
Create an invoice
Add a discount via a line item
Publish the invoice
Bookkeep the invoice
Create bank fees write off (settlement)
Bookkeep bank fees write off (settlement)
Create payment of the invoice
Bookkeep the payment

1. Create or Ensure Customer Exists

Before an invoice is created, a customer record must exist. If the customer does not exist, create a new one; otherwise, retrieve an existing customer.

Endpoint: POST Customer

{
  "type": "company",
  "address": {
    "line1": "Älvsborgsvägen 10",
    "city": "Göteborg",
    "postalCode": "123 45",
    "country": "SE"
  },
  "name": "John Doe",
  "vatNumber": "SE1234567890",
  "orgNumber": "123456-7890",
  "paymentTerms": "30"
}

{
  "id": "1e087e2f-0d8a-4f0f-8af3-870c1735e269",
  "name": "John Doe",
  "type": "company",
  "vatNumber": "SE1234567890",
  "orgNumber": "123456-7890",
  "paymentTerms": "30",
  "contactsDetails": [],
  "address": {
    "line1": "Älvsborgsvägen 10",
    "line2": null,
    "city": "Göteborg",
    "postalCode": "123 45",
    "country": "SE"
  },
  "language": "sv"
}

The response includes the customer ID, which is required for creating invoices. If the customer already exists, perform a GET Customer and search by name or email (e.g., name==John Doe) to retrieve the corresponding ID.

2. Create the invoice with items

Endpoint: POST invoice

In this step, an invoice is created for the customer, referencing their customer ID from the previous step. The example below shows Aurora Works invoicing John Doe for consultancy services.

{
  "type": "invoice",
  "customerRef": { "id": "1e087e2f-0d8a-4f0f-8af3-870c1735e269" },
  "currency": "SEK",
  "currencyRate": 1,
  "lineItems": [
    {
      "itemType": "salesItem",
      "productType": "goods",
      "unitType": "hour",
      "quantity": 180,
      "description": "Consultancy services",
      "unitPrice": 290,
      "taxRate": 25
    }
  ],
  "invoiceDate": "2024-10-10",
  "dueDate": "2024-10-10"
}

{
  "id": "5ce81018-2e14-4688-8de8-bfca14d8014e",
  "type": "invoice",
  "customerRef": {
    "id": "1e087e2f-0d8a-4f0f-8af3-870c1735e269",
    "name": "John Doe"
  },
  "invoiceNumber": null,
  "currency": "SEK",
  "currencyRate": 1,
  "totalAmount": 65250,
  "totalTax": 13050,
  "paidAmount": 0,
  "status": "draft",
  "invoiceDate": "2024-10-10",
  "dueDate": "2024-10-10",
  "lineItems": [
    {
      "id": 18320626,
      "description": "Consultancy services",
      "quantity": 180,
      "unitPrice": 290,
      "taxRate": 25
    }
  ]
}

The response returns the invoice ID, which is required for the following steps.

3. Add Discount

Bokio does not currently support per-item discounts directly. To apply a discount, add a new line item with a negative unit price.

Endpoint: POST Add line item to invoice

{
  "itemType": "salesItem",
  "productType": "goods",
  "unitType": "hour",
  "quantity": 1,
  "description": "New User Discount",
  "unitPrice": -500,
  "taxRate": 25,
  "bookkeepingAccountNumber": 3730
}

This negative line represents a discount of 500 SEK. The account 3730 is commonly used for discounts but can be adjusted according to internal bookkeeping policies.

4. Publish the Invoice

After all details have been reviewed, the invoice can be published. This action issues the invoice and makes it visible to the customer.

Endpoint: POST Publish invoice

{
  "id": "5ce81018-2e14-4688-8de8-bfca14d8014e",
  "status": "published",
  "invoiceNumber": "2024-1001",
  "publishedDateTime": "2024-10-10T10:30:00Z"
}

5. Bookkeep the invoice

To record (bookkeep) the invoice, use the invoiceId and companyId from previous steps. Bokio automatically handles bookkeeping accounts based on the line item setup. The discount line (500 SEK, account 3730) is included during posting.

Endpoint: POST Bookkeep invoice

6. Create bank fees write off (settlement)

Bank fees or currency adjustments can be added by creating a settlement of type bankFee.

Endpoint: POST Create settlement

{
  "type": "bankFee",
  "invoiceSettlementDetails": {
    "reason": "bankFee",
    "date": "2024-10-15",
    "sumBaseCurrency": 15.5
  }
}

{
  "id": "56ff70d2-6e32-4f14-acf9-4288efc44952",
  "type": "bankFee",
  "invoiceId": "5ce81018-2e14-4688-8de8-bfca14d8014e",
  "invoiceSettlementDetails": {
    "date": "2024-10-15",
    "sumBaseCurrency": 15.5
  },
  "journalEntryRef": null
}

At this stage, the settlement is created but not yet recorded in bookkeeping.

7. Record bank fees write off (settlement)

Once the settlement is created, it must be bookkept to adjust the accounts receivable. For bank fees, the system currently uses account 6570 (Bank charges). This can be customized in future implementations.

Endpoint: POST Record settlement

{
  "id": "56ff70d2-6e32-4f14-acf9-4288efc44952",
  "type": "bankFee",
  "invoiceId": "5ce81018-2e14-4688-8de8-bfca14d8014e",
  "invoiceSettlementDetails": {
    "date": "2024-10-15",
    "sumBaseCurrency": 15.5
  },
  "journalEntryRef": {
    "id": "2d0e6bf9-31e0-4884-ae6b-9b35cff1ef49"
  }
}

8. Create payment of the invoice

Once payment is received, it can be registered using the payment endpoint. In this example, payment was received on 1 November for the total amount, deposited into an additional business account (1940).

Endpoint: POST Create payment

{
  "date": "2024-11-01",
  "sumBaseCurrency": 64609.5,
  "bookkeepingAccountNumber": 1940
}

{
  "id": "6c76d197-77a0-424e-88e6-df56de576da1",
  "invoiceId": "5ce81018-2e14-4688-8de8-bfca14d8014e",
  "date": "2024-11-01",
  "sumBaseCurrency": 64609.5,
  "bookkeepingAccountNumber": 1940,
  "journalEntryRef": null
}

At this stage, the payment is recorded but not yet bookkept.

9. Bookkeep payment of the invoice

To finalize bookkeeping, use the payment ID from the previous response. This ensures that the accounts receivable are cleared and the payment is properly reflected in the bank account (1940).

Endpoint: POST Record payment

{
  "id": "6c76d197-77a0-424e-88e6-df56de576da1",
  "invoiceId": "5ce81018-2e14-4688-8de8-bfca14d8014e",
  "date": "2024-11-01",
  "sumBaseCurrency": 64609.5,
  "bookkeepingAccountNumber": 1940,
  "journalEntryRef": {
    "id": "1f899268-5be1-45f0-8179-944f3adf892a"
  }
}

After this step, the payment is fully recorded and linked to its corresponding journal entry in the bookkeeping system.