# Settlements

> Retrieve and list settlements that group batched payments into a payout.

A settlement groups payments that were batched together and paid out in a single transfer. VINR
creates a settlement automatically when a payout is initiated; you cannot create them manually.

> **Illustrative content.** Hand-authored to demonstrate the Standard/Advanced pattern; the production
> page will be generated from the VINR OpenAPI spec (roadmap item #1). Field names are representative.

## The settlement object

- **id** `string` — Unique identifier for the settlement, e.g. `stl_5Rw9nCpT`.
- **payout** `string` (expandable) — The payout (`po_`) this settlement was included in. Expand to retrieve the full payout object.
- **amount** `integer` — Gross amount of the batched payments, in the smallest currency unit (e.g. cents).
- **currency** `string` — Three-letter ISO currency code, e.g. `EUR`.
- **net** `integer` — Net amount after fees, in the smallest currency unit.
- **transaction\_count** `integer` — Number of individual payment transactions included in this settlement.
- **created** `timestamp` — Unix timestamp of when the settlement was created.

## Retrieve a settlement

`GET /v1/settlements/{id}`

```bash
curl https://api.vinr.com/v1/settlements/stl_5Rw9nCpT \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const settlement = await vinr.settlements.retrieve('stl_5Rw9nCpT');
```

```python
import vinr

settlement = vinr.Settlement.retrieve("stl_5Rw9nCpT")
```

```ruby
settlement = Vinr::Settlement.retrieve("stl_5Rw9nCpT")
```

```json
{
"id": "stl_5Rw9nCpT",
"payout": "po_7Kx3mBqR",
"amount": 320000,
"currency": "EUR",
"net": 317600,
"transaction_count": 14,
"created": 1716300000
}
```

## List settlements

Returns a list of settlements, optionally filtered by the associated payout. Results are sorted by
creation date, newest first.

`GET /v1/settlements`

```bash
curl "https://api.vinr.com/v1/settlements?payout=po_7Kx3mBqR&limit=5" \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const settlements = await vinr.settlements.list({
payout: 'po_7Kx3mBqR',
limit: 5,
});
```

```python
import vinr

settlements = vinr.Settlement.list(
  payout="po_7Kx3mBqR",
  limit=5,
)
```

```ruby
settlements = Vinr::Settlement.list(
payout: 'po_7Kx3mBqR',
limit: 5,
)
```

```json
{
"object": "list",
"data": [
  {
    "id": "stl_5Rw9nCpT",
    "payout": "po_7Kx3mBqR",
    "amount": 320000,
    "currency": "EUR",
    "net": 317600,
    "transaction_count": 14,
    "created": 1716300000
  }
],
"has_more": false
}
```

## Related events

`settlement.created`. See [Events](/docs/api-reference/events).