Context

Modern Treasury is migrating from naming Ledger Account Payouts to Ledger Account Settlements.

The term "Settlements" more accurately encapsulates the comprehensive nature of the API, covering not just payouts but also encompassing a broader range of financial transactions and settlements within your ledger accounts.

Migrating will be primarily client driven.

The following changes will take effect on December 15th, 2023:

1. The Modern Treasury website will rename all Ledger Account Payout references to Ledger Account Settlements
   1. There is no change in experience beyond cosmetic changes.
2. Modern Treasury documentation will now mark payouts as deprecated, and link to a new set of documentation outlining the new settlements API.
   1. The Payouts API documentation will remain and be maintained until entirely deprecated.
3. The Ledger Account Settlements API and webhooks will be enabled and be supported publicly.
   1. Migration advice can be found here.

The following changes will take effect on March 15th, 2024:

1. The Ledger Account Payouts API will be marked deprecated, and begin returning 404 errors.
   1. Current Behaviour: with valid requests, successful responses as defined by our documentation
   2. New Behaviour: all requests to the /api/ledger_account_payouts API will return a ‘Resource Not Found’ error.

API Changes

All Ledger Account Payouts API /api/ledger_account_payouts

No changes (until complete deprecation).

Ledger Account Settlements API /api/ledger_account_settlements

All API’s are identical to the Ledger Account Payout’s API’s, except for the endpoint being renamed to /api/ledger_account_settlements as well as the following parameter name changes in the requests and responses.

LIST Ledger Entry and Ledger Transaction API

The Ledger Account Payout API parameter is supported until complete deprecation.

Examples

All objects may be fetched and mutated with either the new settlements API or the old payouts API. The returned object is dependent on the API used (not which endpoint the object was created on). For example, creating a settlement:

// POST /api/ledger_account_settlements

{
  "description": "Alice's January payout",
  "settled_ledger_account_id": "d44ad0d0-b3ea-4698-867d-09fe961e52a6",
  "contra_ledger_account_id": "3824af4d-4151-48f6-8e8b-bf859cbddbcd",
  "effective_at_upper_bound": "2023-01-01T00:00:00.000Z"
}

Would return:

{
    "id": "dbdbbfe5-da56-4aaf-be36-3fbc415622dd",
    "object": "ledger_account_settlement",
    "live_mode": true,
    "description": "Alice's January payout",
    "settled_ledger_account_id": "d44ad0d0-b3ea-4698-867d-09fe961e52a6",
    "contra_ledger_account_id": "3824af4d-4151-48f6-8e8b-bf859cbddbcd",
    "settlement_entry_direction": "debit",
    "effective_at_upper_bound": "2023-01-01T00:00:00.000Z",
    "status": "pending",
    "amount": 1000,
    "currency": "USD",
    "ledger_transaction_id": "b47ce462-806b-4d5d-9476-9add11a42529",
    "metadata": {
        "foo": "bar"
    },
    "created_at": "2023-01-11T20:35:36Z",
    "updated_at": "2023-01-11T20:36:02Z"
}

This same object may be fetched, and updated from the Payouts API (notice the original fields):

GET /api/ledger_account_payouts/53166a98-c8e6-453b-ab9a-b96686a8ca98

{
  "id": "dbdbbfe5-da56-4aaf-be36-3fbc415622dd",
  "object": "ledger_account_payout",
  "live_mode": true,
  "description": "Alice's January payout",
  "payout_ledger_account_id": "d44ad0d0-b3ea-4698-867d-09fe961e52a6",
  "funding_ledger_account_id": "3824af4d-4151-48f6-8e8b-bf859cbddbcd",
  "payout_entry_direction": "debit",
  "effective_at_upper_bound": "2023-01-01T00:00:00.000Z",
  "status": "pending",
  "amount": 1000,
  "currency": "USD",
  "ledger_transaction_id": "b47ce462-806b-4d5d-9476-9add11a42529",
  "metadata": {
      "foo": "bar"
  },
  "created_at": "2023-01-11T20:35:36Z",
  "updated_at": "2023-01-11T20:36:02Z"
}

The same call can be made to the settlements endpoint:

// GET /api/ledger_account_settlements/53166a98-c8e6-453b-ab9a-b96686a8ca98

{
  "id": "53166a98-c8e6-453b-ab9a-b96686a8ca98",
  "object": "ledger_account_settlement",
  "live_mode": true,
  "ledger_id": "07a4bd43-0025-4f9d-800d-19131a4a19c5",
  "description": null,
  "settled_ledger_account_id": "8a84bf57-00f0-4629-9f0e-af0271e6c3df",
  "contra_ledger_account_id": "1d5a748a-175e-443d-97a4-a3e75c7f262e",
  "effective_at_upper_bound": "2023-11-15T14:45:08.536Z",
  "status": "processing",
  "settlement_entry_direction": null,
  "amount": null,
  "currency": "USD",
  "currency_exponent": 2,
  "ledger_transaction_id": null,
  "metadata": {},
  "created_at": "2023-11-15T14:45:08Z",
  "updated_at": "2023-11-15T14:45:08Z"
}

Webhook Changes

Ledger Account Payout API’s will continue to produce payout webhooks.

Ledger Account Settlement webhooks will be a new webhook endpoint which clients would need to subscribe to explicitly if they want to receive them (in addition to Payout webhooks).

The webhook delivered will be dependent on the API used to instantiate it (same as for API responses).