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

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

{
  "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).

By input_id (all matching)
By internal_id (single entry)

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.

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.

Delete Charges or Credits

Deletion follows the same addressing pattern as updates.

By input_id (all matching)
By internal_id (single entry)

curl -X DELETE "https://api.lumenaza.de/v3/consumers/{userID}/contracts/{contractID}/charges_and_credits/input_id/{inputId}/" \
  -H "Authorization: Bearer <token>"

curl -X DELETE "https://api.lumenaza.de/v3/consumers/{userID}/contracts/{contractID}/charges_and_credits/internal_id/{internalId}/" \
  -H "Authorization: Bearer <token>"

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.

Get Started

Core Concepts

Guides

Data & Analytics

Apply Charges and Credits to Customer Invoices

Apply Charges and Credits to Customer Invoices

Create a Charge or Credit

Request fields

Example request

Example response

Update Charges or Credits

Delete Charges or Credits

​Apply Charges and Credits to Customer Invoices

​Create a Charge or Credit

​Request fields

​Example request

​Example response

​Update Charges or Credits

​Delete Charges or Credits

Apply Charges and Credits to Customer Invoices

Create a Charge or Credit

Request fields

Example request

Example response

Update Charges or Credits

Delete Charges or Credits