Overview

This guide will explain how to use the Ledgers API for a marketplace. In this example, we will assume you are running a marketplace like Airbnb where a guest can rent a property from a property owner. We will demonstrate a simple flow here with 3 events:

The guest books a stay
The guest pays for the stay
The marketplace pays out the property owner

Additionally, there are some questions the marketplace might ask, such as:

What are the outstanding liabilities on my platform?
How much cash is in my bank account?

In order to facilitate these payment flows and be able to answer these questions, we will set up a ledger that has 3 ledger accounts.

Cash in the marketplace's bank account
The balance owed by a given guest, George
The balance owed to a given property owner, Olivia

Setup

First, we will make a ledger to represent the marketplace.

curl --request POST \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/ledgers \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Marketplace Ledger",
    "description": "Represents our USD funds and user balances"
  }'

This will return a ledger object with an ID to be used in the following step.

{
    "id": "ad2c1f72-9945-41ee-8cda-c33b33697872",
    "object": "ledger",
    "name": "Marketplace Ledger",
    "description": "Represents our USD funds and user balances",
    "active": true,
    "metadata": {},
    "live_mode": true,
    "created_at": "2021-11-09T14:59:54Z",
    "updated_at": "2021-11-09T14:59:54Z"
}

Next, we will create the 3 ledger accounts described above. Note that the bank account is normal_balance=debit, as is the guest account (because it represents a balance owed to us). The owner account is normal_balance=credit (because it represents a balance owed from us).

curl --request POST \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/ledger_accounts \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Cash Account",
    "description": "Tracks our cash",
    "normal_balance": "debit",
    "currency": "USD",
    "ledger_id": "ad2c1f72-9945-41ee-8cda-c33b33697872"
  }'
  
curl --request POST \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/ledger_accounts \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Guest George",
    "description": "Tracks amount owed by George",
    "normal_balance": "debit",
    "currency": "USD",
    "ledger_id": "ad2c1f72-9945-41ee-8cda-c33b33697872"
  }'
  
  curl --request POST \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/ledger_accounts \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Owner Olivia",
    "description": "Tracks amount owed to Olivia",
    "normal_balance": "credit",
    "currency": "USD",
    "ledger_id": "ad2c1f72-9945-41ee-8cda-c33b33697872"
  }'

This will return the 3 ledger accounts you've created.

{
    "id": "e240d17b-6dbe-4c8d-a152-4da7cc496ff0",
    "object": "ledger_account",
    "name": "Cash Account",
    "ledger_id": "ad2c1f72-9945-41ee-8cda-c33b33697872",
    "description": "Tracks our cash",
    "normal_balance": "debit",
    "currency": "USD",
    "currency_exponent": 2,
    "active": true,
    "metadata": {},
    "live_mode": true,
    "created_at": "2021-11-09T15:02:23Z",
    "updated_at": "2021-11-09T15:02:23Z"
}

{
    "id": "d62a028c-4a1c-41f8-b8c7-3c690d22e2f4",
    "object": "ledger_account",
    "name": "Guest George",
    "ledger_id": "ad2c1f72-9945-41ee-8cda-c33b33697872",
    "description": "Tracks amount owed by George",
    "normal_balance": "debit",
    "currency": "USD",
    "currency_exponent": 2,
    "active": true,
    "metadata": {},
    "live_mode": true,
    "created_at": "2021-11-09T15:02:23Z",
    "updated_at": "2021-11-09T15:02:23Z"
}

{
    "id": "463237a4-a93d-4396-9be8-5bacb8ceead1",
    "object": "ledger_account",
    "name": "Owner Olivia",
    "ledger_id": "ad2c1f72-9945-41ee-8cda-c33b33697872",
    "description": "Tracks amount owed to Olivia",
    "normal_balance": "credit",
    "currency": "USD",
    "currency_exponent": 2,
    "active": true,
    "metadata": {},
    "live_mode": true,
    "created_at": "2021-11-09T15:02:23Z",
    "updated_at": "2021-11-09T15:02:23Z"
}

Using the ledger

Now that the setup is done, you can write to the ledger to record what happens in your business.

First, we can create a ledger transaction to record that the George has booked a stay at Olivia's property. This will recognize that George will owe us $200, and we will owe Olivia $200.

curl --request POST \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/ledger_transactions \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Reservation A43E22",
    "effective_date": "2021-11-10",
    "status": "pending",
    "external_id": "97dbb8b1-e6f2-485e-a0ec-6267e3c60718",
    "ledger_entries": [
      {
        "ledger_account_id": "d62a028c-4a1c-41f8-b8c7-3c690d22e2f4",
        "direction": "debit",
        "amount": 20000
      },
      {
        "ledger_account_id": "463237a4-a93d-4396-9be8-5bacb8ceead1",
        "direction": "credit",
        "amount": 20000
      }
    ]  
  }'

Note that the transaction is created in a pending state. When the stay actually occurs, we can update the transaction status to posted.

Next, we can create the ledger transaction to record the payment from the guest George.

curl --request POST \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/ledger_transactions \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Payment from George",
    "effective_date": "2021-11-15",
    "status": "posted",
    "external_id": "c006a6df-72ff-4cbf-aa4a-c18dde4b05c5",
    "ledger_entries": [
      {
        "ledger_account_id": "d62a028c-4a1c-41f8-b8c7-3c690d22e2f4",
        "direction": "credit",
        "amount": 20000
      },
      {
        "ledger_account_id": "e240d17b-6dbe-4c8d-a152-4da7cc496ff0",
        "direction": "debit",
        "amount": 20000
      }
    ]
  }'

Finally, we can create the ledger transaction to record the payment to the property owner Olivia. This transaction zeros out the Olivia's balance with us and records funds leaving our operating account.

curl --request POST \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/ledger_transactions \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Payment to Olivia",
    "effective_date": "2021-11-15",
    "status": "posted",
    "external_id": "14a7fd22-8922-498a-b8b3-def4df72d5e4",
    "ledger_entries": [
      {
         "ledger_account_id": "463237a4-a93d-4396-9be8-5bacb8ceead1",
         "direction": "debit",
         "amount": 20000
      },
      {
        "ledger_account_id": "e240d17b-6dbe-4c8d-a152-4da7cc496ff0",
        "direction": "credit",
        "amount": 20000
      }
    ]
  }'