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

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.

Choosing the Right Endpoint

The level of detail you need determines which endpoint to use:

Need	Endpoint	Use Case
Total amounts only	GET /finance--payouts	View payout totals and status
Breakdown by article	GET /finance--payouts (use `summary` field)	See how much capital, interest, fees, etc.
Individual transactions	GET /finance--payout-specifications	Trace back to specific cases and invoices
Complete audit trail	Both endpoints	Get payout → then get specifications

TIP

You don't need to use both endpoints for every query. Choose based on the level of detail required for your use case.

Scenario 1: View Payout Overview

Retrieve aggregated payout information for a creditor.

TypeScriptPython

typescript

const token = await auth.getValidToken()

const query = encodeURIComponent(
  JSON.stringify({
    creditor: '686e6ed854377058c2dd10bd',
  })
)

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

console.log('Payouts:', response.data._items)

python

import json

token = auth.get_valid_token()

query = json.dumps({
  "creditor": "686e6ed854377058c2dd10bd"
})

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']
print(f"Found {len(payouts)} payouts")

Response:

json

{
  "_items": [
    {
      "_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": 12000.0,
      "vat_amount": 0.0,
      "total_amount": 12000.0,
      "summary": {
        "capital": {
          "count": 12,
          "amount": 12000.0,
          "vat_amount": 0.0,
          "total_amount": 12000.0
        }
      },
      "finance_category": "capital",
      "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": "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
    }
  ]
}

The summary field shows the breakdown by article type. Note that each payout contains only one finance category (capital, interest, fees, etc.) - payouts are always separated by category.

Scenario 2: View Payout Details

Retrieve the individual transaction specifications for a specific payout.

TypeScriptPython

typescript

const token = await auth.getValidToken()

// Step 1: Get the payout
const payoutId = '507f1f77bcf86cd799439099'
const payoutResponse = await axios.get(
  `https://api-sandbox.amili.se/finance--payouts/${payoutId}`,
  {
    headers: {
      'X-API-Key': token,
    },
  }
)

console.log('Payout total:', payoutResponse.data.total_amount)
console.log('Breakdown:', payoutResponse.data.summary)

// Step 2: Get all specifications for this payout
const query = encodeURIComponent(
  JSON.stringify({
    payout: payoutId,
  })
)

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

console.log('Specifications:', specsResponse.data._items)

python

import json

token = auth.get_valid_token()

# Step 1: Get the payout
payout_id = '507f1f77bcf86cd799439099'
payout_response = requests.get(
  f'https://api-sandbox.amili.se/finance--payouts/{payout_id}',
  headers={'X-API-Key': token}
)
payout_response.raise_for_status()
payout = payout_response.json()

print(f"Payout total: {payout['total_amount']}")
print(f"Breakdown: {payout['summary']}")

# Step 2: Get all specifications for this payout
query = json.dumps({
  "payout": payout_id
})

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

print(f"Found {len(specifications)} transaction specifications")

Payout Response:

json

{
  "_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": "123456",
  "ready_for_payout": true,
  "payout_date": "Fri, 13 Jun 2025 00:00:00 GMT",
  "amount": 12000.0,
  "vat_amount": 0.0,
  "total_amount": 12000.0,
  "summary": {
    "capital": {
      "count": 12,
      "amount": 12000.0,
      "vat_amount": 0.0,
      "total_amount": 12000.0
    }
  },
  "finance_category": "capital",
  "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
}

Specifications Response:

json

{
  "_items": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "_created": "Wed, 11 Jun 2025 12:00:00 GMT",
      "_updated": "Fri, 13 Jun 2025 08:00:00 GMT",
      "_etag": "c1d2e3f4567890123456789012345678",
      "payout": "507f1f77bcf86cd799439099",
      "payout_reference": "123456",
      "payout_date": "Fri, 13 Jun 2025 00:00:00 GMT",
      "amount": 1064.0,
      "vat_amount": 0.0,
      "total_amount": 1064.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": "Tue, 10 Jun 2025 14:00:00 GMT",
      "_updated": "Fri, 13 Jun 2025 08:00:00 GMT",
      "_etag": "d2e3f45678901234567890123456789a",
      "payout": "507f1f77bcf86cd799439099",
      "payout_reference": "123456",
      "payout_date": "Fri, 13 Jun 2025 00:00:00 GMT",
      "amount": 500.0,
      "vat_amount": 0.0,
      "total_amount": 500.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": 12
  }
}

Each specification includes:

references.case - Link back to the case
invoice_number - Original invoice number
booking_date - When the transaction was booked
state - Case state when the specification was created
article - Type of transaction (capital, interest, reminder, etc.)
finance_category - Finance category matching the parent payout

Note that all specifications in this response have finance_category: "capital" because they belong to a capital payout. Payouts are always separated by category.

Scenario 3: Query Specifications Directly

If you need transaction-level data without first querying payouts, you can query specifications directly. This is useful for financial reports, audits, or when searching for specific transactions.

Example: Get all specifications for a creditor in a date range

TypeScriptPython

typescript

const token = await auth.getValidToken()

const query = encodeURIComponent(
  JSON.stringify({
    creditor: '686e6ed854377058c2dd10bd',
    booking_date: {
      $gte: 'Mon, 01 Jun 2025 00:00:00 GMT',
      $lte: 'Mon, 30 Jun 2025 23:59:59 GMT',
    },
  })
)

const projection = encodeURIComponent(
  JSON.stringify({
    booking_date: 1,
    article: 1,
    state: 1,
    total_amount: 1,
    amount: 1,
    vat_amount: 1,
    finance_category: 1,
    payout_reference: 1,
    reference_number: 1,
    invoice_number: 1,
  })
)

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

console.log('Specifications:', response.data._items)

python

import json

token = auth.get_valid_token()

query = json.dumps({
  "creditor": "686e6ed854377058c2dd10bd",
  "booking_date": {
    "$gte": "Mon, 01 Jun 2025 00:00:00 GMT",
    "$lte": "Mon, 30 Jun 2025 23:59:59 GMT"
  }
})

projection = json.dumps({
  "booking_date": 1,
  "article": 1,
  "state": 1,
  "total_amount": 1,
  "amount": 1,
  "vat_amount": 1,
  "finance_category": 1,
  "payout_reference": 1,
  "reference_number": 1,
  "invoice_number": 1
})

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

print(f"Found {len(specifications)} specifications")

Response:

json

{
  "_items": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "_created": "Wed, 11 Jun 2025 12:00:00 GMT",
      "_updated": "Wed, 11 Jun 2025 12:00:00 GMT",
      "_etag": "e3f456789012345678901234567890ab",
      "amount": 60.0,
      "vat_amount": 15.0,
      "total_amount": 75.0,
      "article": "reminder",
      "state": "reminder",
      "booking_date": "Wed, 11 Jun 2025 00:00:00 GMT",
      "finance_category": "creditor_commission",
      "payout_reference": "112233",
      "invoice_number": "INV-2025-020",
      "reference_number": "25020"
    },
    {
      "_id": "507f1f77bcf86cd799439012",
      "_created": "Wed, 11 Jun 2025 12:00:00 GMT",
      "_updated": "Wed, 11 Jun 2025 12:00:00 GMT",
      "_etag": "f4567890123456789012345678901abc",
      "amount": 1064.0,
      "vat_amount": 0.0,
      "total_amount": 1064.0,
      "article": "capital",
      "state": "reminder",
      "booking_date": "Wed, 11 Jun 2025 00:00:00 GMT",
      "finance_category": "capital",
      "payout_reference": "65432",
      "invoice_number": "INV-2025-020",
      "reference_number": "25020"
    },
    {
      "_id": "507f1f77bcf86cd799439013",
      "_created": "Thu, 05 Jun 2025 10:00:00 GMT",
      "_updated": "Thu, 05 Jun 2025 10:00:00 GMT",
      "_etag": "56789012345678901234567890abcdef",
      "amount": 10000.0,
      "vat_amount": 0.0,
      "total_amount": 10000.0,
      "article": "capital",
      "state": "reminder",
      "booking_date": "Thu, 05 Jun 2025 00:00:00 GMT",
      "finance_category": "capital",
      "payout_reference": "65432",
      "invoice_number": "INV-2025-019",
      "reference_number": "25019"
    }
  ],
  "_meta": {
    "page": 1,
    "max_results": 100,
    "total": 45
  }
}

This approach is useful when you need to:

Generate financial reports for a specific period
Audit transactions without needing payout aggregation
Search for specific invoice numbers or reference numbers
Filter by article type, state, or finance category

Summary

The finance payout system provides flexibility in how you access financial data:

Use GET /finance--payouts when:

You need aggregated totals for payouts
You want to see the breakdown by article type (using summary)
You're checking payout status or export dates
You're building a payout overview dashboard

Use GET /finance--payout-specifications when:

You need transaction-level detail
You want to trace back to specific cases
You're generating detailed financial reports
You need to audit individual transactions

Use both endpoints when:

You need a complete audit trail (payout → specifications)
You're reconciling payments with bank exports
You need both summary and detail views

For complete endpoint documentation, see:

Finance Payout Examples ​

Choosing the Right Endpoint ​

Scenario 1: View Payout Overview ​

Scenario 2: View Payout Details ​

Scenario 3: Query Specifications Directly ​

Example: Get all specifications for a creditor in a date range ​

Summary ​

Finance Payout Examples

Choosing the Right Endpoint

Scenario 1: View Payout Overview

Scenario 2: View Payout Details

Scenario 3: Query Specifications Directly

Example: Get all specifications for a creditor in a date range

Summary