Finance Payout Examples

This guide demonstrates how to work with finance payouts and payout specifications in the Amili API. Finance data is organized in a parent-child relationship:

Finance Payouts - Aggregated payout summaries to creditors
Finance Payout Specifications - Detailed transaction-level data linked to individual 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.

Finance Categories

The finance_category field determines what type of financial data is represented:

Category	Description	Common Articles
`capital`	Principal debt amount being collected	`capital`
`interest`	Interest charged on overdue payments	`interest`
`creditor_commission`	Commission earned by the creditor from collection	`reminder`, `debt_collection`
`creditor_outlay`	Fees/costs added by creditor before case registration	`reminder`, `invoice_fee`, `late_payment_fee`, `verdict_fee`, `enforcement`

Article Types for creditor_outlay

reminder - Reminder fees charged before sending to Amili
invoice_fee - Invoice fees included in capital
late_payment_fee - Late payment fee (B2B only, typically 450 SEK)
verdict_fee - Court verdict fee (paid quarterly when received)
enforcement - Enforcement fee (paid when Kronofogden confirms payment)

Choosing the Right Endpoint

The level of detail and use case determines which endpoint to use:

Use Case	Endpoint	Finance Categories
Revenue tracking	GET /finance--payouts	`interest`, `creditor_commission`
Case/invoice tracking	GET /finance--payout-specifications	`capital`, `creditor_outlay`
Aggregated payout totals	GET /finance--payouts	Any category
Invoice-level reconciliation	GET /finance--payout-specifications	Any category

Scenario 1: Revenue Tracking - Interest & Commissions

Track earnings from debt collection by retrieving payouts for interest charged on overdue payments and commissions earned. This is useful for revenue reporting and measuring collection performance.

TypeScriptPython

typescript

const token = await auth.getValidToken()

const query = encodeURIComponent(
  JSON.stringify({
    creditor: '686e6ed854377058c2dd10bd',
    finance_category: { $in: ['interest', 'creditor_commission'] },
  })
)

const response = await axios.get(
  `https://api-sandbox.amili.se/finance--payouts?where=${query}&sort=-_created&max_results=10`,
  {
    headers: {
      'X-API-Key': token,
    },
  }
)

const payouts = response.data._items

python

import json

token = auth.get_valid_token()

query = json.dumps({
  "creditor": "686e6ed854377058c2dd10bd",
  "finance_category": {"$in": ["interest", "creditor_commission"]}
})

response = requests.get(
  'https://api-sandbox.amili.se/finance--payouts',
  params={
    'where': query,
    'sort': '-_created',
    'max_results': 10
  },
  headers={'X-API-Key': token}
)
response.raise_for_status()
payouts = response.json()['_items']

Response:

json

{
  "_items": [
    {
      "_id": "507f1f77bcf86cd799439098",
      "_created": "Fri, 13 Jun 2025 08:00:00 GMT",
      "_updated": "Fri, 13 Jun 2025 08:00:00 GMT",
      "_etag": "b2c3d4e5f67890123456789012345678",
      "creditor": "686e6ed854377058c2dd10bd",
      "currency": "SEK",
      "payout_reference": "65432",
      "ready_for_payout": true,
      "payout_date": "Fri, 13 Jun 2025 00:00:00 GMT",
      "amount": 3000.0,
      "vat_amount": 0.0,
      "total_amount": 3000.0,
      "summary": {
        "interest": {
          "count": 8,
          "amount": 3000.0,
          "vat_amount": 0.0,
          "total_amount": 3000.0
        }
      },
      "finance_category": "interest",
      "finance_interval": "daily",
      "finance_period_start_date": "Thu, 12 Jun 2025 00:00:00 GMT",
      "finance_period_end_date": "Thu, 12 Jun 2025 23:59:59 GMT",
      "finance_period_day": 163
    },
    {
      "_id": "507f1f77bcf86cd799439099",
      "_created": "Fri, 13 Jun 2025 08:00:00 GMT",
      "_updated": "Fri, 13 Jun 2025 08:00:00 GMT",
      "_etag": "a1b2c3d4e5f678901234567890123456",
      "creditor": "686e6ed854377058c2dd10bd",
      "currency": "SEK",
      "payout_reference": "65432",
      "ready_for_payout": true,
      "payout_date": "Fri, 13 Jun 2025 00:00:00 GMT",
      "amount": 450.0,
      "vat_amount": 112.5,
      "total_amount": 562.5,
      "summary": {
        "reminder": {
          "count": 5,
          "amount": 450.0,
          "vat_amount": 112.5,
          "total_amount": 562.5
        }
      },
      "finance_category": "creditor_commission",
      "finance_interval": "daily",
      "finance_period_start_date": "Thu, 12 Jun 2025 00:00:00 GMT",
      "finance_period_end_date": "Thu, 12 Jun 2025 23:59:59 GMT",
      "finance_period_day": 163
    }
  ]
}

The response shows payouts separated by finance_category. The summary field breaks down amounts by article type within that category.

Scenario 2: Case Tracking - Capital & Creditor Outlays

Track the capital amounts and fees/costs that were included in the capital claim upon case registration. This enables invoice-level reconciliation and tracking of original claim economics.

The capital category represents the principal debt amount, while creditor_outlay represents fees the creditor already charged before sending the case to Amili (such as reminder fees or invoice fees). These fees are specified at case registration using fees_included_in_capital_to_claim and fees_already_claimed - see the Case Flow Example for details.

Data Availability

Payout specifications are created immediately when payments are settled. All case-related data (invoice_number, reference_number, references.case, amounts) is available right after settlement.

Some fields are added later in the payout lifecycle:

payout - Set when the specification is linked to a payout during scheduling
payout_reference - Cascaded from the linked payout
payout_date - Set when the payout is exported to the bank

For case tracking purposes, you don't need to wait for these fields.

TypeScriptPython

typescript

const token = await auth.getValidToken()

const query = encodeURIComponent(
  JSON.stringify({
    creditor: '686e6ed854377058c2dd10bd',
    finance_category: { $in: ['capital', 'creditor_outlay'] },
  })
)

const response = await axios.get(
  `https://api-sandbox.amili.se/finance--payout-specifications?where=${query}&sort=-_created&max_results=100`,
  {
    headers: {
      'X-API-Key': token,
    },
  }
)

const specifications = response.data._items

python

import json

token = auth.get_valid_token()

query = json.dumps({
  "creditor": "686e6ed854377058c2dd10bd",
  "finance_category": {"$in": ["capital", "creditor_outlay"]}
})

response = requests.get(
  'https://api-sandbox.amili.se/finance--payout-specifications',
  params={
    'where': query,
    'sort': '-_created',
    'max_results': 100
  },
  headers={'X-API-Key': token}
)
response.raise_for_status()
specifications = response.json()['_items']

Response:

json

{
  "_items": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "_created": "Wed, 11 Jun 2025 12:00:00 GMT",
      "_updated": "Wed, 11 Jun 2025 12:00:00 GMT",
      "_etag": "c1d2e3f4567890123456789012345678",
      "creditor": "686e6ed854377058c2dd10bd",
      "currency": "SEK",
      "amount": 2050.0,
      "vat_amount": 0.0,
      "total_amount": 2050.0,
      "article": "capital",
      "state": "reminder",
      "booking_date": "Wed, 11 Jun 2025 00:00:00 GMT",
      "finance_category": "capital",
      "invoice_number": "INV-2025-020",
      "reference_number": "25020",
      "references": {
        "case": "507f1f77bcf86cd799439050"
      }
    },
    {
      "_id": "507f1f77bcf86cd799439012",
      "_created": "Wed, 11 Jun 2025 12:00:00 GMT",
      "_updated": "Wed, 11 Jun 2025 12:00:00 GMT",
      "_etag": "d2e3f45678901234567890123456789a",
      "creditor": "686e6ed854377058c2dd10bd",
      "currency": "SEK",
      "amount": 60.0,
      "vat_amount": 0.0,
      "total_amount": 60.0,
      "article": "reminder",
      "state": "reminder",
      "booking_date": "Wed, 11 Jun 2025 00:00:00 GMT",
      "finance_category": "creditor_outlay",
      "invoice_number": "INV-2025-020",
      "reference_number": "25020",
      "references": {
        "case": "507f1f77bcf86cd799439050"
      }
    },
    {
      "_id": "507f1f77bcf86cd799439013",
      "_created": "Tue, 10 Jun 2025 14:00:00 GMT",
      "_updated": "Tue, 10 Jun 2025 14:00:00 GMT",
      "_etag": "e3f456789012345678901234567890ab",
      "creditor": "686e6ed854377058c2dd10bd",
      "currency": "SEK",
      "amount": 1500.0,
      "vat_amount": 0.0,
      "total_amount": 1500.0,
      "article": "capital",
      "state": "reminder",
      "booking_date": "Tue, 10 Jun 2025 00:00:00 GMT",
      "finance_category": "capital",
      "invoice_number": "INV-2025-019",
      "reference_number": "25019",
      "references": {
        "case": "507f1f77bcf86cd799439051"
      }
    }
  ],
  "_meta": {
    "page": 1,
    "max_results": 100,
    "total": 3
  }
}

Each specification includes:

Field	Description
`invoice_number`	Original invoice number from case registration
`reference_number`	Case reference number for tracking
`references.case`	Link to the case document
`booking_date`	Customer payment date - when the end customer's payment was registered/settled
`finance_category`	`capital` for principal amounts, `creditor_outlay` for fees/costs
`article`	Specific transaction type (capital, reminder, invoice_fee, etc.)
`amount`	Amount excluding VAT
`total_amount`	Amount including VAT

The creditor_outlay entries correspond to fees that were specified at case registration in fees_already_claimed (e.g., reminder fees charged before the case was sent to Amili).

Grouping by Customer Payment

Use banking_transaction._id to identify all specification items that originated from the same customer payment. This is useful when you need to reconcile payments in your system and want to group items (capital, fees) that were paid together by the customer.

Note: A single banking_transaction can span multiple cases if the customer paid multiple invoices in one payment (e.g., bundled Kronofogden payments).

About payout_reference

The payout_reference field is the reference Amili uses when paying out to the creditor - not the customer's payment reference. Examples include "Utbetalning kapital från Amili" or "Utbetalning provision på inkassoavgifter". This field is set when the specification is linked to a payout.

Tip: Incremental Data Fetching

When building scheduled jobs (e.g., daily cron jobs) to fetch finance data, use the _created field for incremental fetching:

TypeScriptPython

typescript

// Store the last successful fetch timestamp
let lastFetchTimestamp = loadLastTimestamp() // e.g., "Wed, 11 Jun 2025 00:00:00 GMT"

const query = encodeURIComponent(
  JSON.stringify({
    creditor: '686e6ed854377058c2dd10bd',
    finance_category: { $in: ['capital', 'creditor_outlay'] },
    _created: { $gte: lastFetchTimestamp },
  })
)

const response = await axios.get(
  `https://api-sandbox.amili.se/finance--payout-specifications?where=${query}&sort=_created&max_results=100`,
  { headers: { 'X-API-Key': token } }
)

// Process and deduplicate by _id (in case of job reruns)
const newRecords = deduplicateById(response.data._items)

// Update timestamp only after successful processing
saveLastTimestamp(new Date().toUTCString())

python

# Store the last successful fetch timestamp
last_fetch_timestamp = load_last_timestamp()  # e.g., "Wed, 11 Jun 2025 00:00:00 GMT"

query = json.dumps({
    "creditor": "686e6ed854377058c2dd10bd",
    "finance_category": {"$in": ["capital", "creditor_outlay"]},
    "_created": {"$gte": last_fetch_timestamp}
})

response = requests.get(
    'https://api-sandbox.amili.se/finance--payout-specifications',
    params={'where': query, 'sort': '_created', 'max_results': 100},
    headers={'X-API-Key': token}
)
response.raise_for_status()

# Process and deduplicate by _id (in case of job reruns)
new_records = deduplicate_by_id(response.json()['_items'])

# Update timestamp only after successful processing
save_last_timestamp(datetime.utcnow().strftime("%a, %d %b %Y %H:%M:%S GMT"))

Why use `_created` instead of other date fields?

Field	Recommended	Reason
`_created`	✅ Yes	Immutable, set when record is created, never changes
`booking_date`	⚠️ Possible	Set at settlement, but represents business date not creation time
`payout_date`	❌ No	Remains `null` until bank export - records would be missed during the scheduling phase
`_updated`	❌ No	Changes on any update - could cause records to be fetched multiple times

Idempotency Pattern

Always deduplicate fetched records by _id to handle scenarios where:

The job runs multiple times in the same period
The job failed mid-process and needs to re-run
Network issues caused partial processing

Finance Payout Endpoint
Finance Payout Specification Endpoint
Case Flow Example - How fees are added at case registration

Finance Payout Examples ​

Finance Categories ​

Choosing the Right Endpoint ​

Scenario 1: Revenue Tracking - Interest & Commissions ​

Scenario 2: Case Tracking - Capital & Creditor Outlays ​

Tip: Incremental Data Fetching ​

Why use _created instead of other date fields? ​

Related Documentation ​

Finance Payout Examples

Finance Categories

Choosing the Right Endpoint

Scenario 1: Revenue Tracking - Interest & Commissions

Scenario 2: Case Tracking - Capital & Creditor Outlays

Tip: Incremental Data Fetching

Why use `_created` instead of other date fields?

Related Documentation