# Merchant Installment

Merchant Installments are created for every installment in a purchase.

These resources will track its own due payment date and settlement lifecycle.

Once an installment is credited to your account, you receive a "credited" log with the transaction ID that appears on your statement.

### The Merchant Installment object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the merchant installment. |
| `amount` | INTEGER | Installment amount in cents. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `due` | STRING | Expected settlement date. Example: "2020-04-23T23:00:00.000000+00:00". |
| `fee` | INTEGER | Total fee charged in cents, including the anticipation fee when there is one. |
| `fundingType` | STRING | Funding type. Options: "credit", "debit". |
| `isProtected` | BOOLEAN | Whether the installment is reserved to cover a reversal of its purchase. |
| `network` | STRING | Card network. |
| `nominalDue` | STRING | Originally scheduled settlement date. Example: "2020-04-23T23:00:00.000000+00:00". |
| `purchaseId` | STRING | ID of the Merchant Purchase linked to the installment. |
| `status` | STRING | Current installment status. Options: "created", "paid", "voided". |
| `tags` | LIST OF STRINGS | Tags associated with the installment. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the installment. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### List Merchant Installments

`GET /v2/merchant-installment`

Get a list of merchant installments in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `due` | OPTIONAL | Filter installments by their expected settlement date. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `fundingType` | OPTIONAL | Filter installments by funding type, such as: credit, debit. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `network` | OPTIONAL | Filter installments by card network. |
| `purchaseIds` | OPTIONAL | Filter installments by the ids of their Merchant Purchases. |
| `status` | OPTIONAL | Filter installments by the specified status, such as: created, paid, voided. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

**Request**

```python
import starkbank

merchant_installments = starkbank.merchantinstallment.query(limit=1)

for merchant_installment in merchant_installments:
    print(merchant_installment)
```

**Response**

```python
MerchantInstallment(
    amount=1000,
    created=2025-02-20 20:01:58.529828,
    due=2025-05-21 03:00:00.529828,
    fee=16,
    funding_type=credit,
    id=4848075206033408,
    network=mastercard,
    purchase_id=5559970598748160,
    status=paid,
    tags=[],
    transaction_ids=["38502321313064121177062848528552"],
    updated=2025-02-20 20:02:02.185613
)
```

### Get a Merchant Installment

`GET /v2/merchant-installment/:id`

Retrieve detailed information about a specific installment by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | The unique identifier for the merchant installment that needs to be retrieved. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

merchant_installment = starkbank.merchantinstallment.get('4848075206033408')

print(merchant_installment)
```

**Response**

```python
MerchantInstallment(
        amount=1000,
        created=2025-02-20 20:01:58.529828,
        due=2025-05-21 03:00:00.529828,
        fee=16,
        funding_type=credit,
        id=4848075206033408,
        network=mastercard,
        purchase_id=5559970598748160,
        status=paid,
        tags=[],
        transaction_ids=["38502321313064121177062848528552"],
        updated=2025-02-20 20:02:02.185613
)
```

### List Merchant Installment Logs

`GET /v2/merchant-installment/log`

Get a paged list of merchant installment logs.

A log tracks a change in the installment entity according to its life cycle.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `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. |
| `installmentIds` | OPTIONAL | Filter the merchant installment ids to only include their corresponding logs |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `types` | OPTIONAL | Filters logs by log types. |

**Request**

```python
import starkbank

merchant_installment_logs = starkbank.merchantinstallment.log.query(limit=1)

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

**Response**

```python
Log(
    created=2025-02-20 21:05:03.520701,
    errors=[],
    id=6218715502739456,
    installment=MerchantInstallment(
        amount=5000,
        created=2025-02-20 21:05:03.515855,
        due=2025-03-21 03:00:00,
        fee=60,
        funding_type=credit,
        id=5092815595896832,
        network=mastercard,
        purchase_id=6332003586670592,
        status=created,
        tags=[],
        transaction_ids=[],
        updated=2025-02-20 21:05:04.705022
    ),
    type=created,
    updated=2025-02-20 21:05:04.720418
)
```

### Get a Merchant Installment Log

`GET /v2/merchant-installment/log/:id`

Get a single merchant installment log by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | The unique identifier for the merchant installment that needs to be retrieved. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

log = starkbank.merchantinstallment.log.get('6218715502739456')

print(log)
```

**Response**

```python
Log(
    created=2025-02-20 21:05:03.520701,
    errors=[],
    id=6218715502739456,
    installment=MerchantInstallment(
        amount=5000,
        created=2025-02-20 21:05:03.515855,
        due=2025-03-21 03:00:00,
        fee=60,
        funding_type=credit,
        id=5092815595896832,
        network=mastercard,
        purchase_id=6332003586670592,
        status=created,
        tags=[],
        transaction_ids=[],
        updated=2025-02-20 21:05:04.705022
    ),
    type=created,
    updated=2025-02-20 21:05:04.720418
)
```

## Available Languages

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

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