# Ledger

The Ledger resource is used to track the balance of a given amount by inserting LedgerTransactions to it.

A Ledger can represent a bank account, a digital wallet, an inventory product, or any other entity whose balance you need to keep track of.

You can attach rules to a Ledger to limit its balance, such as a minimum or maximum balance, which are validated whenever a LedgerTransaction is created.

### The Ledger object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Ledger. |
| `externalId` | STRING | Unique external id to prevent duplicates. |
| `rules` | LIST OF OBJECTS | List of rule objects applied to the Ledger. |
| `tags` | LIST OF STRINGS | Tags associated with the Ledger. |
| `metadata` | OBJECT | Dictionary of additional information about the Ledger. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Create Ledgers

`POST /v2/ledger`

Use this route to create up to 100 new ledgers at a time.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `externalId` | REQUIRED | Unique string to prevent duplicates. Repeated externalIds will cause failures. |
| `rules` | OPTIONAL | List of rule objects to apply to the Ledger. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. |
| `metadata` | OPTIONAL | Dictionary of additional information about the Ledger. |

**Request**

```python
import starkinfra

ledgers = starkinfra.ledger.create([
    starkinfra.Ledger(
        external_id="my-internal-id-123456",
        rules=[
            starkinfra.ledger.Rule(
                key="minimumBalance",
                value=0
            )
        ],
        tags=["account/123", "savings"],
        metadata={"accountId": "123", "accountType": "savings"}
    )
])

for ledger in ledgers:
    print(ledger)
```

**Response**

```python
[
    Ledger(
        id=5656565656565656,
        external_id=my-internal-id-123456,
        rules=[
            Rule(
                key=minimumBalance,
                value=0
            )
        ],
        tags=['account/123', 'savings'],
        metadata={'accountId': '123', 'accountType': 'savings'},
        created=2022-01-01 00:00:00,
        updated=2022-01-01 00:00:00
    )
]
```

### List Ledgers

`GET /v2/ledger`

Get a list of ledgers in chunks of at most 100.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `externalIds` | OPTIONAL | Filter by external IDs. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkinfra

ledgers = starkinfra.ledger.query(
    limit=10,
    tags=["savings"]
)

for ledger in ledgers:
    print(ledger)
```

**Response**

```python
Ledger(
    id=5656565656565656,
    external_id=my-internal-id-123456,
    rules=[
        Rule(
            key=minimumBalance,
            value=0
        )
    ],
    tags=['account/123', 'savings'],
    metadata={'accountId': '123', 'accountType': 'savings'},
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Get a Ledger

`GET /v2/ledger/:id`

Get a single ledger by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the ledger entity. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkinfra

ledger = starkinfra.ledger.get("5656565656565656")

print(ledger)
```

**Response**

```python
Ledger(
    id=5656565656565656,
    external_id=my-internal-id-123456,
    rules=[
        Rule(
            key=minimumBalance,
            value=0
        )
    ],
    tags=['account/123', 'savings'],
    metadata={'accountId': '123', 'accountType': 'savings'},
    created=2022-01-01 00:00:00,
    updated=2022-01-01 00:00:00
)
```

### Update a Ledger

`PATCH /v2/ledger/:id`

Update the rules, tags or metadata of an existing ledger.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the ledger entity. |
| `rules` | OPTIONAL | New list of rule objects to apply to the Ledger. |
| `tags` | OPTIONAL | New array of strings to tag the Ledger. |
| `metadata` | OPTIONAL | New dictionary of additional information about the Ledger. |

**Request**

```python
import starkinfra

ledger = starkinfra.ledger.update(
    "5656565656565656",
    tags=["account/123", "closed"]
)

print(ledger)
```

**Response**

```python
Ledger(
    id=5656565656565656,
    external_id=my-internal-id-123456,
    rules=[
        Rule(
            key=minimumBalance,
            value=0
        )
    ],
    tags=['account/123', 'closed'],
    metadata={'accountId': '123', 'accountType': 'savings'},
    created=2022-01-01 00:00:00,
    updated=2022-06-01 00:00:00
)
```

### List Ledger Logs

`GET /v2/ledger/log`

Get a paged list of ledger logs.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `ledgerId` | OPTIONAL | Filter logs by ledger id. Only a single ledger id can be informed per query. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkinfra

logs = starkinfra.ledger.log.query(
    limit=10,
    ledger_id="5656565656565656"
)

for log in logs:
    print(log)
```

**Response**

```python
Log(
    id=5656565656565656,
    type=created,
    ledger=Ledger(id=5656565656565656, external_id=my-internal-id-123456),
    created=2022-01-01 00:00:00
)
```

### Get a Ledger Log

`GET /v2/ledger/log/:id`

Get a single ledger log by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the log entity. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkinfra

log = starkinfra.ledger.log.get("5656565656565656")

print(log)
```

**Response**

```python
Log(
    id=5656565656565656,
    type=created,
    ledger=Ledger(id=5656565656565656, external_id=my-internal-id-123456),
    created=2022-01-01 00:00:00
)
```

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

- [Python](https://docs.starkinfra.com/api/v2/ledger-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/ledger-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/ledger-php.md)
- [Java](https://docs.starkinfra.com/api/v2/ledger-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/ledger-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/ledger-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/ledger-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/ledger-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/ledger-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/ledger-curl.md)