Invoice Flow Example
The diagram below shows the basic sequence of API calls for managing an invoice, with each step described in the following sections.
An invoice is registered with all the required debtor and invoice details needed to start the invoice process. After this point, you can at any time get the current status of the invoice, including detailed information about its state in the process. Two optional paths are then described: first, where part of the invoice amount is credited by the creditor, and second, where the invoice is cancelled completely.
Step-by-Step Guide
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.
1. Register an Invoice
Register a new invoice using the Invoice Registration endpoint:
typescript
const invoiceData = {
account: '674dbeaf08847b9501cc9132',
creditor: '674dbeb208847b9501cc9138',
invoice_number: 'INV-2025-015',
invoice_date: new Date().toISOString(),
invoice_due_date: '2025-10-17T00:00:00Z',
currency: 'SEK',
invoice_type: 'invoice',
invoice_headline: 'Consulting Services',
invoice_body_text: 'Thank you for your business',
customer: {
name: 'Jane Smith',
id_number: '556789-1234',
is_person: true,
address: {
address_line_1: 'Business Street 456',
zip_code: '54321',
city: 'Gothenburg',
},
mobile_number: '+46709876543',
email: 'jane.smith@domain.se',
},
matrix: [
{
article_description: 'Consulting hours',
unit_price: 500.0,
total_price_excluding_vat: 500.0,
unit_vat_percent: '0%',
},
],
}
const token = await auth.getValidToken()
const response = await axios.post(
'https://api-sandbox.amili.se/invoice-registration',
invoiceData,
{
headers: {
'X-API-Key': token,
'Content-Type': 'application/json',
},
}
)python
invoice_data = {
"account": "674dbeaf08847b9501cc9132",
"creditor": "674dbeb208847b9501cc9138",
"invoice_number": "INV-2025-015",
"invoice_date": datetime.utcnow().isoformat() + "Z",
"invoice_due_date": "2025-10-17T00:00:00Z",
"currency": "SEK",
"invoice_type": "invoice",
"invoice_headline": "Consulting Services",
"invoice_body_text": "Thank you for your business",
"customer": {
"name": "Jane Smith",
"id_number": "556789-1234",
"is_person": True,
"address": {
"address_line_1": "Business Street 456",
"zip_code": "54321",
"city": "Gothenburg"
},
"mobile_number": "+46709876543",
"email": "jane.smith@domain.se"
},
"matrix": [{
"article_description": "Consulting hours",
"unit_price": 500.0,
"total_price_excluding_vat": 500.0,
"unit_vat_percent": "0%"
}]
}
token = auth.get_valid_token()
response = requests.post(
'https://api-sandbox.amili.se/invoice-registration',
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"
}2. Get Case Status
Find your case based on Creditor invoice number and get the current status using the Case endpoint with Query parameter to find the invoice using creditor invoice number:
typescript
const token = await auth.getValidToken()
const query = encodeURIComponent(
JSON.stringify({ debt.invoice_number: 'INV-2025-015' })
)
const response = await axios.get(
`https://api-sandbox.amili.se/cases?where=${query}`,
{
headers: {
'X-API-Key': token,
},
}
)python
import json
token = auth.get_valid_token()
query = json.dumps({'debt.invoice_number': 'INV-2025-015'})
response = requests.get(
'https://api-sandbox.amili.se/cases',
params={'where': query},
headers={'X-API-Key': token}
)
response.raise_for_status()
result = response.json()The response will be:
json
{
"_items": [
{
"_id": "68e4c40d93ee14723d28fa95",
"invoice": "68e4c40d7fcb697a78cb1a32",
"_created": "Tue, 07 Oct 2025 07:41:01 GMT",
"_etag": "808c0829161342bc8566b14cf4547dfb",
"_updated": "Tue, 07 Oct 2025 07:41:01 GMT",
"account": "674dbeaf08847b9501cc9132",
"agreement_version": "6790c2ec38ebf4814061f0b5",
"case_settings": {
"interest_rate": {
"reference_rate": true
}
},
"creditor": "674dbeb208847b9501cc9138",
"creditor_name": "Amili Integration Team",
"currency": "SEK",
"customer": "68678ed98d8dc95ece127941",
"customer_id_number": "556789-1234",
"customer_name": "Jane Smith",
"customer_number": "12345",
"customer_status": "initialized",
"debt": {
"invoice_number": "INV-2025-015",
"invoice_date": "Tue, 07 Oct 2025 10:11:22 GMT",
"invoice_due_days_after_invoice_date": 8,
"interest_days_after_invoice_date": 8,
"initial_capital": 500,
"capital_to_claim": 500,
"debt_description": "Professional consulting services",
"payout_reference": "INV-2025-015"
},
"invoice_registration": "68e4c40d7fcb697a78cb1a32",
"latest_state_date": "Tue, 07 Oct 2025 07:41:01 GMT",
"local_added_capital_amount": 500,
"local_added_costs_amount": 0,
"local_added_interest_amount": 0,
"local_added_transaction_amount": 500,
"local_remaining_capital_amount": 500,
"local_remaining_costs_amount": 0,
"local_remaining_interest_amount": 0,
"local_remaining_transaction_amount": 500,
"state": "initializing",
"state_history": [
{
"state": "initializing",
"state_date": "Tue, 07 Oct 2025 07:41:01 GMT"
}
],
"status": "initializing",
"status_history": [
{
"status": "initializing",
"status_date": "Tue, 07 Oct 2025 07:41:01 GMT"
}
],
"total_added_capital_amount": 500,
"total_added_costs_amount": 0,
"total_added_interest_amount": 0,
"total_added_transaction_amount": 500,
"total_remaining_capital_amount": 500,
"total_remaining_costs_amount": 0,
"total_remaining_interest_amount": 0,
"total_remaining_transaction_amount": 500,
"transactions": [
{
"bank_transaction_date": "Tue, 07 Oct 2025 00:00:00 GMT",
"registration_date": "Tue, 07 Oct 2025 00:27:01 GMT",
"origin": "creditor_system",
"type": "capital",
"description_locale_tag": "api.transaction.case_registration",
"amount": 500
}
],
"reference_number": "49477"
}
],
"_meta": {
"page": 1,
"max_results": 25,
"total": 1
}
}3. Credit Part of Invoice
Credit part of the invoice amount using the Creditor Crediting endpoint:
typescript
const creditData = {
account: '674dbeaf08847b9501cc9132',
creditor: '674dbeb208847b9501cc9138',
case: '68e4c40d93ee14723d28fa95',
currency: 'SEK',
amount: 100.0,
origin: 'creditor_system',
}
const token = await auth.getValidToken()
const response = await axios.post(
'https://api-sandbox.amili.se/creditor-crediting',
creditData,
{
headers: {
'X-API-Key': token,
'Content-Type': 'application/json',
},
}
)python
credit_data = {
"account": "674dbeaf08847b9501cc9132",
"creditor": "674dbeb208847b9501cc9138",
"case": "68e4c40d93ee14723d28fa95",
"currency": "SEK",
"amount": 100.0,
"origin": "creditor_system"
}
token = auth.get_valid_token()
response = requests.post(
'https://api-sandbox.amili.se/creditor-crediting',
json=credit_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:51:56 GMT",
"_created": "Tue, 07 Oct 2025 07:51:56 GMT",
"_etag": "820ce3cd3b676e48d1ec0cc0b5cb46811ea2763e",
"_id": "68e4c69c0da90297b3be0dfd",
"_status": "OK",
"_crediting_status": "completed"
}4. Cancel an Invoice
Cancel the invoice using the Creditor Cancellation endpoint:
typescript
const cancellationData = {
creditor: '674dbeb208847b9501cc9138',
case: '68e4c40d93ee14723d28fa95',
origin: 'creditor_system',
}
const token = await auth.getValidToken()
const response = await axios.post(
'https://api-sandbox.amili.se/creditor-cancellation',
cancellationData,
{
headers: {
'X-API-Key': token,
'Content-Type': 'application/json',
},
}
)python
cancellation_data = {
"creditor": "674dbeb208847b9501cc9138",
"case": "68e4c40d93ee14723d28fa95",
"origin": "creditor_system"
}
token = auth.get_valid_token()
response = requests.post(
'https://api-sandbox.amili.se/creditor-cancellation',
json=cancellation_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:53:04 GMT",
"_created": "Tue, 07 Oct 2025 07:53:04 GMT",
"_etag": "d708022fbf6594c332235d07e952423b41dbdbcc",
"_id": "68e4c6e07fcb697a78cb1a37",
"_status": "OK",
"_cancellation_status": "completed"
}