# Ledger Transaction

The LedgerTransaction resource is used to move balance in or out of a Ledger.

Each transaction carries an amount that is added to (or subtracted from) the Ledger balance, producing a new running balance that is returned in the response.

Transactions are validated against the rules of their Ledger, so a transaction that would push the balance beyond a configured minimum or maximum balance is rejected.

### The LedgerTransaction object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Ledger Transaction. |
| `ledgerId` | STRING | Id of the Ledger associated with this transaction. |
| `externalId` | STRING | Unique external id to prevent duplicates. |
| `source` | STRING | Source of the Ledger Transaction. Example: "bank-transfer/123". |
| `amount` | INTEGER | Amount in cents of the Ledger Transaction. Example: 100 (R$1.00). |
| `fee` | INTEGER | Fee charged in cents for this Ledger Transaction. |
| `balance` | INTEGER | Balance in cents of the Ledger after this transaction. Example: 100 (R$1.00). |
| `rules` | LIST OF OBJECTS | List of rule objects applied to the Ledger Transaction. |
| `tags` | LIST OF STRINGS | Tags associated with the Ledger Transaction. |
| `metadata` | OBJECT | Dictionary of additional information about the Ledger Transaction. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Create Ledger Transactions

`POST /v2/ledger-transaction`

Use this route to create up to 500 new ledger transactions at a time.

A single request may contain transactions targeting different ledgers. Each transaction is applied to its Ledger in the order it is sent and the resulting balance is returned for each one.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `amount` | REQUIRED | Amount in cents of the Ledger Transaction. Example: 100 (R$1.00). |
| `ledgerId` | REQUIRED | Id of the Ledger associated with this transaction. |
| `externalId` | REQUIRED | Unique string to prevent duplicates. Repeated externalIds within the same ledger will cause failures. |
| `source` | REQUIRED | Source of the Ledger Transaction. Example: "bank-transfer/123". |
| `fee` | OPTIONAL | Fee charged in cents for this Ledger Transaction. |
| `created` | OPTIONAL | Datetime of the Ledger Transaction, used to import an existing transaction history. Must be in ISO format (Example: "2022-01-01T00:00:00.000000+00:00") and cannot be in the future. When creating multiple transactions in a single request, their created datetimes must be informed in chronological order. If omitted, the current datetime is used. |
| `rules` | OPTIONAL | List of rule objects that momentarily overwrite the Ledger's rules for this transaction. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. |
| `metadata` | OPTIONAL | Dictionary of additional information about the Ledger Transaction. |

**Request**

```python
import starkinfra

transactions = starkinfra.ledgertransaction.create([
    starkinfra.LedgerTransaction(
        amount=11234,
        ledger_id="5656565656565656",
        external_id="my-internal-id-123456",
        source="bank-transfer/123",
        fee=100,
        created="2022-01-01T03:00:00.000000+00:00",
        tags=["transfer/123", "savings"],
        metadata={"orderId": "123", "orderType": "purchase"}
    )
])

for transaction in transactions:
    print(transaction)
```

**Response**

```python
[
    LedgerTransaction(
        id=5656565656565656,
        ledger_id=5656565656565656,
        external_id=my-internal-id-123456,
        source=bank-transfer/123,
        amount=11234,
        fee=100,
        balance=11134,
        tags=['transfer/123', 'savings'],
        metadata={'orderId': '123', 'orderType': 'purchase'},
        created=2022-01-01 03:00:00
    )
]
```

### List Ledger Transactions

`GET /v2/ledger-transaction`

Get a list of ledger transactions in chunks of at most 1000.

Either "ledgerId" or "ids" must be provided. If both are sent, results are filtered by both. When filtering by "ids", the informed ids may reference transactions across different ledgers.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `ledgerId` | CONDITIONALLY REQUIRED | Id of the Ledger associated with the transactions. Either "ledgerId" or "ids" must be provided. |
| `ids` | CONDITIONALLY REQUIRED | List of strings to get specific entities by ids. The informed ids may belong to transactions in different ledgers. Either "ledgerId" or "ids" must be provided. |
| `flow` | OPTIONAL | Direction of the Ledger Transaction. Options: "in" (credit), "out" (debit). |
| `externalIds` | OPTIONAL | Filter by external IDs. |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 1000. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkinfra

transactions = starkinfra.ledgertransaction.query(
    ledger_id="5656565656565656",
    limit=10
)

for transaction in transactions:
    print(transaction)
```

**Response**

```python
LedgerTransaction(
    id=5656565656565656,
    ledger_id=5656565656565656,
    external_id=my-internal-id-123456,
    source=bank-transfer/123,
    amount=11234,
    fee=100,
    balance=11134,
    tags=['transfer/123', 'savings'],
    metadata={'orderId': '123', 'orderType': 'purchase'},
    created=2022-01-01 00:00:00
)
```

### Get a Ledger Transaction

`GET /v2/ledger-transaction/:id`

Get a single ledger transaction by its id.

**Parameters**

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

**Request**

```python
import starkinfra

transaction = starkinfra.ledgertransaction.get("5656565656565656")

print(transaction)
```

**Response**

```python
LedgerTransaction(
    id=5656565656565656,
    ledger_id=5656565656565656,
    external_id=my-internal-id-123456,
    source=bank-transfer/123,
    amount=11234,
    fee=100,
    balance=11134,
    tags=['transfer/123', 'savings'],
    metadata={'orderId': '123', 'orderType': 'purchase'},
    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-transaction-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/ledger-transaction-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/ledger-transaction-php.md)
- [Java](https://docs.starkinfra.com/api/v2/ledger-transaction-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/ledger-transaction-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/ledger-transaction-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/ledger-transaction-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/ledger-transaction-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/ledger-transaction-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/ledger-transaction-curl.md)