---
title: "List Platform Settlements"
method: GET
path: "/payables/platform_settlements"
tags: ["Platform Settlements"]
---

# List Platform Settlements

`GET /payables/platform_settlements`

## Request

- Base URL: `https://api.justifi.ai/v1`
- URL: `https://api.justifi.ai/v1/payables/platform_settlements`
- Auth: none declared. Required headers: `Authorization`
- TypeScript: <https://skmtc.dev/justifi/apis/justifi-api-documentation/docs/payables/platform_settlements/get.ts> (a function with typed inputs; its response is checked against the schema)

List the disbursements between JustiFi and your platform — when each happens, how much, which way
the money goes, and the reference to reconcile it against your bank statement. Read-only and
scoped to the platform your credentials belong to.

This answers "when were we paid" directly. The same facts are derivable from
`/v1/payables/platform_ledger` by filtering to `txn_type=settlement`, but a ledger entry is one
line: it carries neither the reference nor what the disbursement covered, and it does not exist
until after the money has moved. A settlement appears here while it is still `scheduled`.

Optionally narrow to a `status` or a window (`created_after`/`created_before`).

## Query parameters

- `after_cursor` string
- `before_cursor` string
- `limit` integer
- `created_after` string, date-time
- `created_before` string, date-time
- `status` 'scheduled' | 'in_transit' | 'paid' | 'failed' | 'canceled' | 'forwarded'

## Headers

- `Authorization` string, required

## Response `200`

Successfully listed platform settlements

- object: the standard JustiFi response envelope for a list of records
  - `id` unknown, required
  - `type` string, required: the object type
  - `data` object[], required: the list of objects
    - `id` string: unique settlement id
    - `type` string: the object type, matching the enclosing envelope's `type`
    - `platform_account_id` string: the platform this settlement is between JustiFi and
    - `status` 'scheduled' | 'in_transit' | 'paid' | 'failed' | 'canceled' | 'forwarded': where the disbursement is in its lifecycle. `scheduled` — the amount is frozen and the disbursement is queued to be paid; `in_transit` — instructed, with a reference attached, not yet confirmed; `paid` — the money moved; `failed` — it did not, and the balance it covered is owed again; `canceled` — withdrawn before it moved, same effect; `forwarded` — a later settlement took over what this one failed to pay.
    - `direction` 'paid_out' | 'charged': which way the money goes. `paid_out` — JustiFi pays your platform its accrued balance; `charged` — JustiFi collects, because the fees it levied over the period exceeded the ones your platform earned. Read this rather than a sign: `amount_cents` is always positive.
    - `amount_cents` integer: the amount of the disbursement, always positive — `direction` says which way it goes
    - `currency` 'usd'
    - `entries_count` integer: how many platform ledger entries this settlement covers, its own balancing entry included. To read the entries themselves, list `/v1/payables/platform_ledger` and match on `settlement_id`.
    - `ledger_entry_id` string: the `settlement` entry on your platform ledger that balances what this covers
    - `external_reference` string, nullable: the ACH, wire or manual reference for the money movement — what to match against your bank statement. Null until the disbursement is instructed.
    - `scheduled_at` string, date-time: when the amount was frozen and the disbursement was queued
    - `recorded_at` string, date-time, nullable: when the money moved; null until it has
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `page_info` object, required: cursor pagination info
    - `start_cursor` string: the encoded id of the first record in the current page
    - `end_cursor` string: the encoded id of the last record in the current page
    - `has_next` boolean: true if there are records following the current page
    - `has_previous` boolean: true if there are records ahead of the current page

## Other responses

- `400`: The request was malformed, failed validation, or referenced a resource that cannot be used in its current state — for example scheduling a payment to a payee that is not active, or creating anything under a payer account that is not active. When the failure is field-level, `error.details` carries one array of messages per rejected attribute.
- `401`: The access token is missing, expired, or invalid.
- `403`: The credentials are valid but not permitted to access this resource.
- `429`: The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header.

---

[API](https://skmtc.dev/justifi/apis/justifi-api-documentation.md) - [All operations](https://skmtc.dev/justifi/apis/justifi-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/justifi/apis/justifi-api-documentation/revisions/dd9f3fed7e46?raw)