---
title: "Settlements"
description: "A **Settlement** is a periodic accounting record that summarizes payments, refunds, and fees for a given settlement period."
url: "https://docs.komoju.com/en/api-reference#2025-01-28/tag/settlements"
source_url: "https://docs.komoju.com/en/api-reference/2025-01-28/resources/settlements.md"
language: en
api_version: "2025-01-28"
---

# Settlements

A **Settlement** is a periodic accounting record that summarizes payments, refunds, and fees for a given settlement period. Settlements are what KOMOJU uses to compute the amount of a Disbursement, and provide the line-level detail your finance team needs for reconciliation.

## The Settlement object

A **Settlement** is a periodic accounting record summarizing payments,
refunds, and fees for a given settlement period. Settlements are what
KOMOJU uses to compute the amount of a `Disbursement`, and provide the
line-level detail your finance team needs for reconciliation.

### Attributes

- **`id`** *string (UUID)* *required*

  A unique 25-character alphanumeric resource identifier.

- **`resource`** *string enum* *required*

  Resource type name, always "settlement".

- **`reference`** *string* *required*

  Human-readable reference code for this settlement.

- **`status`** *string (Status)* *required*

- **`merchant_name`** *string* *required*

  Name of the merchant associated with this settlement.

- **`company_name`** *string or null* *required*

  Legal company name of the merchant, or null if not set.

- **`cycle`** *string* *required*

  Settlement cycle identifier (e.g. the week or month period covered).

- **`transaction_amount_cents`** *integer (Cents)* *required*

  Amount in the lowest denomination of the currency (e.g. cents for USD).

- **`currency`** *string (Currency)* *required*

  3-letter ISO currency code.

- **`fee_amount_cents`** *integer (Cents)* *required*

  Amount in the lowest denomination of the currency (e.g. cents for USD).

- **`fee_tax_amount_cents`** *integer (Cents)* *required*

  Amount in the lowest denomination of the currency (e.g. cents for USD).

- **`settlement_amount_cents`** *integer (Cents)* *required*

  Amount in the lowest denomination of the currency (e.g. cents for USD).

- **`fx_currency`** *string (Currency)* *required*

  3-letter ISO currency code.

- **`fx_conversion_rate`** *string* *required*

  Exchange rate applied for FX conversion.

- **`fx_conversion_amount_cents`** *integer (Cents)* *required*

  Amount in the lowest denomination of the currency (e.g. cents for USD).

- **`bank_transfer_fee_amount_cents`** *integer (Cents)* *required*

  Amount in the lowest denomination of the currency (e.g. cents for USD).

- **`remittance_amount_cents`** *integer (Cents)* *required*

  Amount in the lowest denomination of the currency (e.g. cents for USD).

- **`cutoff_time`** *string* *required*

  Cutoff timestamp for transactions included in this settlement.

- **`created_at`** *string* *required*

  Timestamp when this settlement record was created.

- **`download`** *object* *required*

### Example

```json
{
  "id": "string",
  "resource": "settlement",
  "reference": "STLM-2025-01",
  "status": "pending",
  "merchant_name": "Acme Inc.",
  "company_name": "string",
  "cycle": "string",
  "transaction_amount_cents": 0,
  "currency": "JPY",
  "fee_amount_cents": 0,
  "fee_tax_amount_cents": 0,
  "settlement_amount_cents": 0,
  "fx_currency": "JPY",
  "fx_conversion_rate": "string",
  "fx_conversion_amount_cents": 0,
  "bank_transfer_fee_amount_cents": 0,
  "remittance_amount_cents": 0,
  "cutoff_time": "2024-01-01T00:00:00Z",
  "created_at": "2024-01-01T00:00:00Z",
  "download": {
    "csv": "string",
    "xls": "string"
  }
}
```

## Endpoints

### Balance: Show

- [GET /balances/{currency}](https://docs.komoju.com/en/api-reference/2025-01-28/show-balance.md)

### Balance: Transactions

- [GET /balances/{currency}/transactions](https://docs.komoju.com/en/api-reference/2025-01-28/balance-transactions.md)

### Balance: Transaction

- [GET /balances/{currency}/transactions/{transaction_uuid}](https://docs.komoju.com/en/api-reference/2025-01-28/show-transaction.md)

### Settlement: Index

- [GET /settlements](https://docs.komoju.com/en/api-reference/2025-01-28/list-settlements.md)

### Settlement: Show

- [GET /settlements/{id}](https://docs.komoju.com/en/api-reference/2025-01-28/show-settlement.md)

### Settlement: CSV

- [GET /settlements/{id}/csv](https://docs.komoju.com/en/api-reference/2025-01-28/show-settlement-csv.md)

### Settlement: XLS

- [GET /settlements/{id}/xls](https://docs.komoju.com/en/api-reference/2025-01-28/show-settlement-xls.md)

### Settlement: PDF

- [GET /settlements/{id}/pdf](https://docs.komoju.com/en/api-reference/2025-01-28/show-settlement-pdf.md)