Invoice preview, payment registration, and crediting through the API

Historical retrospective - May to August 2026
This article was written afterwards and describes the separate invoice actions made available through the API.

An integration must distinguish between reading an invoice, recording an action, and moving money. Start with a preview when checking lines and amounts, then create or fetch the invoice described by the current contract.

A synthetic workflow

1. Use the customer’s invoice-preview endpoint to check periods, lines, and total.
2. Optionally fetch the preview PDF for internal approval.
3. Create or read the invoice and use its UUID for later calls.
4. Use mark-as-sent when your workflow has delivered or registered the document. The call never sends an email; it records delivery through an external channel and suppresses a pending automatic invoice email.
5. Use mark-as-paid when a payment should be registered manually. It does not start a new card charge.
6. Use the credit endpoint when individual invoice lines should be credited. A credit note is a separate action and is not the same as deleting the invoice.

A refund can remain pending even after the request is accepted. Read the response and later status before showing the money as returned.

Errors and expectations

Preview, PDF, sent, paid, and credited have different responses and statuses. Use the current OpenAPI reference for schemas and allowed fields. Do not put real tokens or customer information in test code; use synthetic UUIDs in examples.

See the public API and webhooks guide (Markdown file, AI agent-friendly) for the current contract.

Does mark-as-sent send an email? Never. It records that an external channel delivered the invoice and suppresses a pending automatic invoice email. Use the separate send action if Alunta should send the email.

Does mark-as-paid move money? No. It records a manual payment; it is not a new card charge.

Can crediting be partial? Yes. Use the documented line-credit action and read the status back before showing it as complete.

Keep statuses separate in your integration

A preview can show a user what will be invoiced before a final document exists. A PDF provides the same information in a format that can be approved or archived. Once the invoice exists, mark-as-sent records the workflow. If your integration must also send the document, it should use the documented send action and handle that response separately.

Likewise, mark-as-paid is a manual registration. Use it only when a user or reconciled external source has confirmed the payment. Do not infer a payment call from a successful preview or send status. Crediting selected lines changes the receivable through a credit action; it does not delete the original invoice and is not automatically a cash refund. mark-as-sent never sends email, including when called after invoice finalization; it blocks the pending automatic delivery.

Use the invoice UUID for follow-up calls and read the current status after each action. If the response is pending, show pending rather than complete. This lets the user check the integration’s next result without repeating an action that has already been recorded.