> For the complete documentation index, see [llms.txt](https://docs.cubicl.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cubicl.io/api-integration/bookkeeping.md).

# Bookkeeping

Definitions of the types and formats of the data used in the endpoints can be found at the bottom of the page.

## Endpoints

## Get Page

<mark style="color:blue;">`GET`</mark> `https://cubicl.io/api/v1/bookkeeping/page`

Fetches current account, activities and statistics required for bookkeeping.

{% tabs %}
{% tab title="200: OK Page data. It contains activities, entries, payables and receivables." %}

```typescript
{
    activities : BookkeepingActivity[],
    entries : BookkeepingEntry[],
    payables : {
        total : number,
        outstanding : number,
        overdue : number,
        currency : string
    },
    receivables : {
        total : number,
        outstanding : number,
        overdue : number,
        currency : string
    }
}
```

{% endtab %}

{% tab title="403: Forbidden You don't have the permission." %}

```javascript
{ code : 4 }
```

{% endtab %}
{% endtabs %}

## Fetch Entry Activities

<mark style="color:blue;">`GET`</mark> `https://cubicl.io/api/v1/bookkeeping/activities`

#### Query Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| entry<mark style="color:red;">\*</mark> | String | Entry id    |

{% tabs %}
{% tab title="200: OK Entry's activities" %}

```javascript
BookkeepingActivity[]
```

{% endtab %}

{% tab title="403: Forbidden You don't have the permission." %}

```javascript
{ code : 4 }
```

{% endtab %}

{% tab title="404: Not Found Entry not found" %}

```javascript
{ code : 1501 }
```

{% endtab %}
{% endtabs %}

## Fetch Entry Details

<mark style="color:blue;">`GET`</mark> `https://cubicl.io/api/v1/bookkeeping/entries/{entry}`

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| entry<mark style="color:red;">\*</mark> | String | Entry id    |

{% tabs %}
{% tab title="200: OK Entry's detail" %}

```javascript
BookkeepingEntry
```

{% endtab %}

{% tab title="403: Forbidden You don't have the permission." %}

```javascript
{ code : 4 }
```

{% endtab %}

{% tab title="404: Not Found Entry not found" %}

```javascript
{ code : 1501 }
```

{% endtab %}
{% endtabs %}

## Add Entry

<mark style="color:green;">`POST`</mark> `https://cubicl.io/api/v1/bookkeeping/entries`

Adds a receivable or payable entry for a client.

#### Request Body

| Name                                       | Type   | Description                                                                                                                                                                                                                                         |   |                                                                                                                                          |
| ------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | ---------------------------------------------------------------------------------------------------------------------------------------- |
| customer<mark style="color:red;">\*</mark> | String | Client id                                                                                                                                                                                                                                           |   |                                                                                                                                          |
| dueAt                                      | Number | Due date. Payment is expected to be made before this date.                                                                                                                                                                                          |   |                                                                                                                                          |
| paidAmount                                 | Number | How much of the total is paid? It must be greater than 0 and less than the total amount.                                                                                                                                                            |   |                                                                                                                                          |
| desc                                       | String | Receivable or payable entry description.                                                                                                                                                                                                            |   |                                                                                                                                          |
| name<mark style="color:red;">\*</mark>     | String | Receivable or payable entry name.                                                                                                                                                                                                                   |   |                                                                                                                                          |
| currency<mark style="color:red;">\*</mark> | String | <p>Currency. It must contain one of the following values:</p><p></p><p>TRY, USD, EUR, GBP, AUD, CAD, CHF, CNY, HKD, NZD, SEK, KRW, SGD, NOK, MXN, INR, ZAR, RUB, BRL, JPY, TWD, DKK, PLN, THB, IDR, HUF, CZK, ILS, PHP, AED, COP, SAR, MYR, RON</p> |   |                                                                                                                                          |
| amount<mark style="color:red;">\*</mark>   | Number | Current account balance. It must be greater than 0.                                                                                                                                                                                                 |   |                                                                                                                                          |
| type<mark style="color:red;">\*</mark>     | String | <p>receivable                                                                                                                                                                                                                                       |   | payable<br><br>receivable: The payment you will receive from your clients.<br><br>payable: The payment you will pay to your clients.</p> |

{% tabs %}
{% tab title="200: OK New entry with activity, payment and payment activity" %}

```javascript
{
    entry : BookkeepingEntry
    entryActivity : BookkeepingActivity,
    payment? : BookkeepingPayment // Exists if paidAmount is given
    paymentActivity? : BookkeepingActivity // Exists if paidAmount is given
}
```

{% endtab %}

{% tab title="403: Forbidden You don't have the permission." %}

```javascript
{ code : 4 }
```

{% endtab %}

{% tab title="404: Not Found Client not found" %}

```javascript
{ code : 303 }
```

{% endtab %}

{% tab title="422: Unprocessable Entity Your organization's current plan has insufficient. You can upgrade it." %}

```javascript
{ code : 1201 }
```

{% endtab %}

{% tab title="422: Unprocessable Entity Currency not supported" %}

```javascript
{ code : 1504 }
```

{% endtab %}
{% endtabs %}

## Update Entry Details

<mark style="color:orange;">`PUT`</mark> `https://cubicl.io/api/v1/bookkeeping/entries/{entry}`

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| entry<mark style="color:red;">\*</mark> | String | Entry id    |

#### Request Body

| Name                                       | Type   | Description                                                                                                                                                                                                                                         |   |                                                                                                                                          |
| ------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | ---------------------------------------------------------------------------------------------------------------------------------------- |
| type<mark style="color:red;">\*</mark>     | String | <p>receivable                                                                                                                                                                                                                                       |   | payable<br><br>receivable: The payment you will receive from your clients.<br><br>payable: The payment you will pay to your clients.</p> |
| currency<mark style="color:red;">\*</mark> | String | <p>Currency. It must contain one of the following values:</p><p></p><p>TRY, USD, EUR, GBP, AUD, CAD, CHF, CNY, HKD, NZD, SEK, KRW, SGD, NOK, MXN, INR, ZAR, RUB, BRL, JPY, TWD, DKK, PLN, THB, IDR, HUF, CZK, ILS, PHP, AED, COP, SAR, MYR, RON</p> |   |                                                                                                                                          |
| name<mark style="color:red;">\*</mark>     | String | Receivable or payable entry name.                                                                                                                                                                                                                   |   |                                                                                                                                          |
| desc                                       | String | Receivable or payable entry description.                                                                                                                                                                                                            |   |                                                                                                                                          |
| dueAt                                      | Number | Due date. Payment is expected to be made before this date.                                                                                                                                                                                          |   |                                                                                                                                          |

{% tabs %}
{% tab title="200: OK Updated entry" %}

```javascript
BookkeepingEntry
```

{% endtab %}

{% tab title="403: Forbidden You don't have the permission." %}

```javascript
{ code : 4 }
```

{% endtab %}

{% tab title="422: Unprocessable Entity Paid amount cannot be greater than entry amount" %}

```javascript
{ code : 1503 }
```

{% endtab %}

{% tab title="422: Unprocessable Entity Your organization's current plan has insufficient. You can upgrade it." %}

```javascript
{ code : 1201 }
```

{% endtab %}

{% tab title="422: Unprocessable Entity Currency not supported" %}

```javascript
{ code: 1504 }
```

{% endtab %}

{% tab title="404: Not Found Entry not found" %}

```javascript
{ code: 1501 }
```

{% endtab %}
{% endtabs %}

## Delete Entry

<mark style="color:red;">`DELETE`</mark> `https://cubicl.io/api/v1/bookkeeping/entries/{entry}`

All activity and payment records related to this entry is deleted.

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| entry<mark style="color:red;">\*</mark> | String | Entry id    |

{% tabs %}
{% tab title="200: OK Empty response" %}

```javascript
```

{% endtab %}

{% tab title="403: Forbidden You don't have the permission." %}

```javascript
{ code : 4 }
```

{% endtab %}

{% tab title="422: Unprocessable Entity Your organization's current plan has insufficient. You can upgrade it." %}

```javascript
{ code : 1201 }
```

{% endtab %}

{% tab title="404: Not Found Entry not found" %}

```javascript
{ code: 1501 }
```

{% endtab %}
{% endtabs %}

## Add Payment

<mark style="color:green;">`POST`</mark> `https://cubicl.io/api/v1/bookkeeping/payment/{entry}`

#### Path Parameters

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| entry<mark style="color:red;">\*</mark> | String | Entry id    |

#### Request Body

| Name                                         | Type   | Description                                                                              |
| -------------------------------------------- | ------ | ---------------------------------------------------------------------------------------- |
| paidAmount<mark style="color:red;">\*</mark> | Number | How much of the total is paid? It must be greater than 0 and less than the total amount. |
| note                                         | String |                                                                                          |

{% tabs %}
{% tab title="200: OK New payment and activity" %}

```javascript
{
    payment : BookkeepingPayment,
    activity : BookkeepingActivity
}
```

{% endtab %}

{% tab title="403: Forbidden You don't have the permission." %}

```javascript
{ code : 4 }
```

{% endtab %}

{% tab title="404: Not Found Entry not found" %}

```javascript
{ code : 1501 }
```

{% endtab %}

{% tab title="422: Unprocessable Entity Paid amount cannot be greater than entry amount" %}

```javascript
{ code: 1503 }
```

{% endtab %}

{% tab title="422: Unprocessable Entity Your organization's current plan has insufficient. You can upgrade it." %}

```javascript
{ code : 1201 }
```

{% endtab %}
{% endtabs %}

## Delete Payment

<mark style="color:red;">`DELETE`</mark> `https://cubicl.io/api/v1/bookkeeping/payments/{payment}`

#### Path Parameters

| Name                                      | Type   | Description |
| ----------------------------------------- | ------ | ----------- |
| payment<mark style="color:red;">\*</mark> | String | Payment id  |

{% tabs %}
{% tab title="200: OK Bookkeeping Activity" %}

```javascript
BookkeepingActivity
```

{% endtab %}

{% tab title="403: Forbidden You don't have the permission." %}

```javascript
{ code : 4 }
```

{% endtab %}

{% tab title="404: Not Found Payment not found" %}

```javascript
{ code : 1502 }
```

{% endtab %}

{% tab title="422: Unprocessable Entity Your organization's current plan has insufficient. You can upgrade it." %}

```javascript
{ code : 1201 }
```

{% endtab %}
{% endtabs %}

## Data

### BookkeepingEntry

```typescript
{
    org : string, // Organization id
    customer : string, // Client id
    /* receivable: The payment you will receive from your clients.
     * payable: The payment you will pay to your clients.
     */
    type : 'receivable' | 'payable',
    amount : number, // Current account balance. It must be greater than 0.
    /* Currency. It must contain one of the following values:
     * TRY, USD, EUR, GBP, AUD, CAD, CHF, CNY, HKD, NZD, SEK,
     * KRW, SGD, NOK, MXN, INR, ZAR, RUB, BRL, JPY, TWD, DKK,
     * THB, IDR, HUF, CZK, ILS, PHP, AED, COP, SAR, MYR, RON
     */
    currency : string,
    name : string,
    desc : string | null,
    paidAmount : number,     // How much of the total is paid? It must be greater than zero and less than total amount.
    isPaid : boolean,        // Is completely paid off?
    dueAt : number | null,   // Due date. Payment is expected to be made before this date.
    createdBy : string,      // Id of the user who created the entry.
    createdAt : number,
}
```

### BookkeepingPayment

```typescript
{
    org : string, // Organization id
    customer : string, // Client id
    amount : number, // Current account balance. It must be greater than 0.
    entry : string, // Bookkeeping Entry id
    note : string | null, // Optional note about the payment
    createdBy : string, // Id of the user who created the entry
    createdAt : number
}
```

### BookkeepingActivity

```typescript
{
    org : string, // Organization id
    customer : string, // Client id
    entry : string, // Bookkeeping Entry id. Always exists
    payment? : string, // Exists if type is 'payment-received', 'payment-sent' or 'payment-deleted'
    type : 'receivable-created' | 'payable-created' | 'payment-received' | 'payment-sent' | 'payment-deleted',
    data : {
        entryName : string,
        entryDueAt? : number, // Exists if entry dueAt defined
        amount : number, // Current account balance. It must be greater than 0.
        /* Currency. It must contain one of the following values:
         * TRY, USD, EUR, GBP, AUD, CAD, CHF, CNY, HKD, NZD, SEK,
         * KRW, SGD, NOK, MXN, INR, ZAR, RUB, BRL, JPY, TWD, DKK,
         * THB, IDR, HUF, CZK, ILS, PHP, AED, COP, SAR, MYR, RON
         */
        currency : string,
        paidAmount? : number, // Exists if type is receivable/payable-created. How much of the total is paid? It must be greater than zero
    },
    createdBy : string // Id of the user who created the entry
    createdAt : number,
}
```