# 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,
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cubicl.io/api-integration/bookkeeping.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.