English

Svenska

English

Svenska

Appearance

Invoice Flow Examples ​

This guide covers the key API actions for managing invoices and their associated cases.

All API requests require a valid authentication token in the X-API-Key header. For details about the authentication process and token management, see the Authentication documentation.

In this guide, we will use the AuthTokenProvider class (documented in the authentication guide) to handle token management.

Table of Contents

Invoice Registration ​

Register a new invoice using the Invoice Registration endpoint. The response returns both an invoice--registration ID and, most importantly, a case ID (_case). The case ID is used for all subsequent actions on this invoice.

The customer type is determined by setting one of is_person, is_company, or is_foreign to true. This affects how Amili handles the case — for example, company invoices can be distributed via e-invoicing (Peppol).

Person (Natural Person) ​

Register an invoice where the customer is a private individual (is_person: true). The id_number should be the customer's Swedish personal identity number (personnummer).

typescript
const invoiceData = {
  account: '674dbeaf08847b9501cc9132',
  creditor: '674dbeb208847b9501cc9138',
  invoice_number: 'INV-2026-001',
  invoice_date: new Date().toISOString(),
  invoice_due_date: '2026-04-30T00:00:00Z',
  currency: 'SEK',
  invoice_type: 'invoice',
  customer: {
    name: 'Anna Andersson',
    id_number: '19900101-1234',
    is_person: true,
    address: {
      address_line_1: 'Storgatan 12',
      zip_code: '11122',
      city: 'Stockholm',
      country: 'SE',
    },
    mobile_number: '+46701234567',
    email: 'anna.andersson@example.se',
  },
  matrix: [
    {
      article_description: 'Service fee',
      unit_price: 500.0,
      number_of_units: 1,
      total_price_excluding_vat: 500.0,
      unit_vat_percent: '25%',
    },
  ],
}

const token = await auth.getValidToken()
const response = await axios.post(
  'https://api-sandbox.amili.se/invoice--registrations',
  invoiceData,
  {
    headers: {
      'X-API-Key': token,
      'Content-Type': 'application/json',
    },
  }
)
python
from datetime import datetime

invoice_data = {
    "account": "674dbeaf08847b9501cc9132",
    "creditor": "674dbeb208847b9501cc9138",
    "invoice_number": "INV-2026-001",
    "invoice_date": datetime.utcnow().isoformat() + "Z",
    "invoice_due_date": "2026-04-30T00:00:00Z",
    "currency": "SEK",
    "invoice_type": "invoice",
    "customer": {
        "name": "Anna Andersson",
        "id_number": "19900101-1234",
        "is_person": True,
        "address": {
            "address_line_1": "Storgatan 12",
            "zip_code": "11122",
            "city": "Stockholm",
            "country": "SE"
        },
        "mobile_number": "+46701234567",
        "email": "anna.andersson@example.se"
    },
    "matrix": [{
        "article_description": "Service fee",
        "unit_price": 500.0,
        "number_of_units": 1,
        "total_price_excluding_vat": 500.0,
        "unit_vat_percent": "25%"
    }]
}

token = auth.get_valid_token()
response = requests.post(
    'https://api-sandbox.amili.se/invoice--registrations',
    json=invoice_data,
    headers={
        'X-API-Key': token,
        'Content-Type': 'application/json'
    }
)
response.raise_for_status()
result = response.json()

The response will be:

json
{
  "_updated": "Tue, 07 Oct 2025 07:41:01 GMT",
  "_created": "Tue, 07 Oct 2025 07:41:01 GMT",
  "_etag": "8bfdf8614dc48aa763568c6e6a914e3f0503e18e",
  "_id": "68e4c40d7fcb697a78cb1a32",
  "_status": "OK",
  "_invoice": "68e4c40d7fcb697a78cb1a32",
  "_case": "68e4c40d93ee14723d28fa95",
  "_ocr_number": "68e4c40e7fcb697a78cb1a36",
  "ocr_number_ocr": "20252806663259506081"
}

Key IDs in the response

  • _id — The invoice registration ID (the record of this request)
  • _case — The case ID — use this for all subsequent actions (crediting, cancellation, payment)
  • _invoice — The invoice ID
  • _ocr_number — The OCR number resource ID
  • ocr_number_ocr — The OCR number string for payment reference

Register an invoice where the customer is a company or organization (is_company: true). Company invoices support additional fields that enable e-invoicing and organizational identification.

Company-specific attributes

The following fields are specific to or particularly relevant for company customers:

  • is_company: true — Identifies the customer as a Swedish legal entity
  • id_number — The organization number (organisationsnummer), e.g. "556123-4567"
  • customer_number — Your internal customer reference for this company
  • address.gln — Global Location Number, used for Peppol e-invoicing routing
  • preferred_invoice_distribution — Set to "electronic_invoicing_company" for e-invoicing via Peppol
  • your_reference — Contact person or reference at the company
  • contract_reference — Contract or agreement reference number
typescript
const invoiceData = {
  account: '674dbeaf08847b9501cc9132',
  creditor: '674dbeb208847b9501cc9138',
  invoice_number: 'INV-2026-002',
  invoice_date: new Date().toISOString(),
  invoice_due_date: '2026-04-30T00:00:00Z',
  currency: 'SEK',
  invoice_type: 'invoice',
  preferred_invoice_distribution: 'electronic_invoicing_company', // e-invoicing via Peppol
  your_reference: 'Maria Johansson', // contact at the company
  contract_reference: 'AVT-2026-100', // contract reference
  customer: {
    name: 'Exempel Bygg AB',
    customer_number: 'CUST-10042',
    id_number: '556123-4567', // organization number
    is_company: true,
    address: {
      gln: '7350000000001', // GLN for e-invoicing
      address_line_1: 'Industrivägen 8',
      zip_code: '41505',
      city: 'Göteborg',
      country: 'SE',
    },
    email: 'faktura@exempelbygg.se',
  },
  matrix: [
    {
      article_description: 'Service fee',
      unit_price: 1200.0,
      number_of_units: 1,
      total_price_excluding_vat: 1200.0,
      unit_vat_percent: '25%',
    },
  ],
}

const token = await auth.getValidToken()
const response = await axios.post(
  'https://api-sandbox.amili.se/invoice--registrations',
  invoiceData,
  {
    headers: {
      'X-API-Key': token,
      'Content-Type': 'application/json',
    },
  }
)
python
from datetime import datetime

invoice_data = {
    "account": "674dbeaf08847b9501cc9132",
    "creditor": "674dbeb208847b9501cc9138",
    "invoice_number": "INV-2026-002",
    "invoice_date": datetime.utcnow().isoformat() + "Z",
    "invoice_due_date": "2026-04-30T00:00:00Z",
    "currency": "SEK",
    "invoice_type": "invoice",
    "preferred_invoice_distribution": "electronic_invoicing_company",  # e-invoicing via Peppol
    "your_reference": "Maria Johansson",  # contact at the company
    "contract_reference": "AVT-2026-100",  # contract reference
    "customer": {
        "name": "Exempel Bygg AB",
        "customer_number": "CUST-10042",
        "id_number": "556123-4567",  # organization number
        "is_company": True,
        "address": {
            "gln": "7350000000001",  # GLN for e-invoicing
            "address_line_1": "Industrivägen 8",
            "zip_code": "41505",
            "city": "Göteborg",
            "country": "SE"
        },
        "email": "faktura@exempelbygg.se"
    },
    "matrix": [{
        "article_description": "Service fee",
        "unit_price": 1200.0,
        "number_of_units": 1,
        "total_price_excluding_vat": 1200.0,
        "unit_vat_percent": "25%"
    }]
}

token = auth.get_valid_token()
response = requests.post(
    'https://api-sandbox.amili.se/invoice--registrations',
    json=invoice_data,
    headers={
        'X-API-Key': token,
        'Content-Type': 'application/json'
    }
)
response.raise_for_status()
result = response.json()

The response follows the same structure as for a person invoice:

json
{
  "_updated": "Mon, 10 Nov 2025 09:22:15 GMT",
  "_created": "Mon, 10 Nov 2025 09:22:15 GMT",
  "_etag": "c4a7e82f1b3d6e9a0f5c8d2b7e4a1f6c3d9b0e5a",
  "_id": "69a1b2c3d4e5f6a7b8c9d0e1",
  "_status": "OK",
  "_invoice": "69a1b2c3d4e5f6a7b8c9d0e1",
  "_case": "69a1b2c3d4e5f6a7b8c9d0e2",
  "_ocr_number": "69a1b2c3d4e5f6a7b8c9d0e3",
  "ocr_number_ocr": "20261504827391640052"
}

To retrieve the current status of a case at any time, see the Case Status Retrieval Example.

Next Steps ​

Once a case has been created from an invoice registration, you can perform actions such as registering payments, crediting amounts, or cancelling the case. These actions are common to all cases regardless of how they were created.

See the Creditor Case Actions guide for detailed examples of:

  • Creditor Payment — Register a payment received directly from the debtor
  • Creditor Crediting — Credit part of the capital on a case
  • Creditor Cancellation — Cancel a case entirely

You can also track the lifecycle and financial outcome of your cases: