> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumenaza.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Apply Charges and Credits to Customer Invoices

> Add one-time or recurring monetary charges and credits to customer invoices using the Lumenaza v3 API, including bulk CSV upload and update/delete flows.

# Apply Charges and Credits to Customer Invoices

Charges and credits are one-time or recurring monetary amounts that Lumenaza automatically includes in the next customer invoice for the relevant billing period. Common use cases include referral bonuses, promotional discounts, billing corrections, and late-payment fees.

**Base URLs**

| Environment | URL |
| - | - |
| Production | `https://api.lumenaza.de/` |
| Test | `https://api.test.lumenaza.de/` |

All requests require an `Authorization: Bearer <token>` header.

***

## Create a Charge or Credit

**Endpoint**

```
POST /v3/consumers/{userID}/contracts/{contractID}/charges_and_credits/
```

> The same endpoint is available for producers:
> `POST /v3/producers/{userID}/contracts/{contractID}/charges_and_credits/`

### Request fields

**Required**

| Field | Type | Description |
| - | - | - |
| `type_of_transaction` | string | `"credit"` (money towards the customer) or `"charge"` (money owed by the customer) |
| `amount_cent` | integer | Amount in euro cents — e.g., `1000` = **€10.00** |
| `is_gross` | boolean | `true` if the amount already includes VAT; `false` if it is net |
| `vat_type` | string | `"normal"` (19% VAT) or `"reduced"` (7% VAT) |
| `due_date` | date | ISO 8601 date (`YYYY-MM-DD`) — the billing period that **covers** this date will include the amount |
| `input_id` | string | Your unique identifier for this entry (max 128 characters) |
| `category` | string | Grouping label printed on the invoice (max 40 characters) |
| `display_name` | string | Human-readable line item shown to the customer on their invoice (max 128 characters) |

**Optional**

| Field | Type | Default | Description |
| - | - | - | - |
| `no_of_executions` | integer | `1` | How many times to apply the amount |
| `execution_cycle` | string | — | `"month"` or `"year"` — required when `no_of_executions` > 1 |
| `explanation_text` | string | — | Internal note or customer-facing explanation |
| `bookkeeping_account` | string | — | Account code for your accounting system |

### Example request

```bash theme={null}
curl -X POST "https://api.lumenaza.de/v3/consumers/{userID}/contracts/{contractID}/charges_and_credits/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type_of_transaction": "credit",
    "amount_cent": 1000,
    "is_gross": true,
    "vat_type": "normal",
    "due_date": "2024-04-15",
    "input_id": "referral-bonus-user-9876",
    "category": "Referral Bonus",
    "display_name": "Welcome referral credit",
    "explanation_text": "Credit applied for referring a new customer.",
    "no_of_executions": 1
  }'
```

### Example response

```json theme={null}
{
  "internal_id": "cc_a1b2c3d4",
  "input_id": "referral-bonus-user-9876",
  "type_of_transaction": "credit",
  "amount_cent": 1000,
  "is_gross": true,
  "vat_type": "normal",
  "due_date": "2024-04-15",
  "category": "Referral Bonus",
  "display_name": "Welcome referral credit",
  "status": "pending"
}
```

***

## Update Charges or Credits

You can update entries either by your own `input_id` (affects **all** entries sharing that ID) or by the Lumenaza-assigned `internal_id` (updates a **single** entry).

<Tabs>
  <Tab title="By input_id (all matching)">
    ```bash theme={null}
    curl -X PUT "https://api.lumenaza.de/v3/consumers/{userID}/contracts/{contractID}/charges_and_credits/input_id/{inputId}/" \
      -H "Authorization: Bearer <token>" \
      -H "Content-Type: application/json" \
      -d '{
        "amount_cent": 1500,
        "display_name": "Updated referral credit"
      }'
    ```

    All charges/credits that share `inputId` on this contract will be updated.
  </Tab>

  <Tab title="By internal_id (single entry)">
    ```bash theme={null}
    curl -X PUT "https://api.lumenaza.de/v3/consumers/{userID}/contracts/{contractID}/charges_and_credits/internal_id/{internalId}/" \
      -H "Authorization: Bearer <token>" \
      -H "Content-Type: application/json" \
      -d '{
        "amount_cent": 1500,
        "display_name": "Updated referral credit"
      }'
    ```

    Only the specific entry identified by `internalId` will be updated.
  </Tab>
</Tabs>

***

## Delete Charges or Credits

Deletion follows the same addressing pattern as updates.

<Tabs>
  <Tab title="By input_id (all matching)">
    ```bash theme={null}
    curl -X DELETE "https://api.lumenaza.de/v3/consumers/{userID}/contracts/{contractID}/charges_and_credits/input_id/{inputId}/" \
      -H "Authorization: Bearer <token>"
    ```
  </Tab>

  <Tab title="By internal_id (single entry)">
    ```bash theme={null}
    curl -X DELETE "https://api.lumenaza.de/v3/consumers/{userID}/contracts/{contractID}/charges_and_credits/internal_id/{internalId}/" \
      -H "Authorization: Bearer <token>"
    ```
  </Tab>
</Tabs>

<Warning>
  If a charge or credit has **already been included in an issued bill**, updating or deleting it via the API will **not** automatically revise that bill. To correct the invoice, you must cancel the original bill and recreate it. Always verify the `status` of an entry before attempting to modify it.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.