Billing & Invoicing

This guide explains how to work with invoices, payments, credit notes, and prepayments (unallocated payments) through the Provet Cloud REST API.

Invoices in Provet Cloud are created by the application itself — either when a consultation is finalized or through a countersale. The REST API cannot create invoices directly. Instead, the API is used to read invoice data, record payments, issue refunds, and synchronize financial data with external systems such as ERP or accounting software.

Invoice Lifecycle

An invoice moves through the following statuses:

Value	Status	Description
0	Draft	Invoice is being prepared, not yet ready for payment
1	Sent	Invoice has been sent to the client
2	Open	Invoice is open and awaiting payment
3	Finalized	Invoice is complete and ready for payment
4	Invoicing	Invoice has been sent to the client for later payment
99	Voided	Invoice has been cancelled

Note

Payments can only be recorded against invoices with status 3 (Finalized). Attempting to pay a Draft or Voided invoice will result in a validation error.

Fetching and Filtering Invoices

API endpoint: https://provetcloud.com/<provet_id>/api/0.1/invoice/

Use query parameters to filter the invoice list. Commonly used filters:

Parameter	Example	Description
`status__is`	`status__is=3`	Filter by status value
`invoice_date__gte`	`invoice_date__gte=2024-01-01`	Invoices on or after this date
`invoice_date__lte`	`invoice_date__lte=2024-01-31`	Invoices on or before this date
`modified__gte`	`modified__gte=2024-03-01T00:00:00`	Records changed since this timestamp (use for delta sync)
`date_paid__gte`	`date_paid__gte=2024-01-01`	Invoices paid on or after this date
`client__is`	`client__is=456`	Filter by client ID
`department__is`	`department__is=1`	Filter by department ID
`credit_note__is`	`credit_note__is=true`	Only return credit notes
`countersale__is`	`countersale__is=false`	Exclude countersales

Example — fetch all finalized invoices changed since a specific timestamp:

GET /api/0.1/invoice/?status__is=3&modified__gte=2024-03-20T00:00:00

Understanding Invoice Date Fields

Several date fields exist on an invoice. Choosing the wrong one for ERP synchronization is a common source of confusion.

Field	Writable	Description
`invoice_date`	Yes (on draft)	The business date of the invoice. Use this as the accounting document date in your ERP.
`invoice_due_date`	Yes	The date by which payment is expected.
`created`	No	Timestamp when the invoice record was created in the database. Not suitable for accounting purposes.
`modified`	No	Timestamp of the last change to the invoice record. Use this for delta synchronization polling.
`date_paid`	No	Set automatically when the invoice is fully paid. Use this to detect settled invoices.

Note

For ERP integration: use invoice_date as the document date and poll using modified__gte to detect changes since your last sync run. date_paid tells you when an invoice was fully settled.

Recording a Payment

API endpoint: POST https://provetcloud.com/<provet_id>/api/0.1/invoicepayment/

Record a payment against a finalized invoice. The invoice must have status=3 (Finalized) before a payment can be created.

Request Body Example:

{
    "invoice": "https://provetcloud.com/<provet_id>/api/0.1/invoice/12345/",
    "payment_type": 1,
    "paid": "124.00",
    "date_added": "2024-03-20T14:00:00"
}

Payment type values:

Value	Description
0	Card
1	Cash
2	Bank payment
3	Rounding
4	Cheque
5	Voucher
6	Consolidated invoice
7	Mobile payment
9	Gift card
10	Financing company
11	Other
12	Credit invoice
15	Insurance claim

Note

payment_type=8 (Prepayment) is not accepted on this endpoint. Applying an unallocated payment balance to an invoice is handled through the Provet Cloud UI, not via the REST API.

You can filter existing payments by invoice:

GET /api/0.1/invoicepayment/?invoice__is=12345

Cancelling a Payment

API endpoint: POST https://provetcloud.com/<provet_id>/api/0.1/invoicepayment/<id>/cancel_payment/

Use this when a payment was recorded incorrectly — wrong amount, wrong method, or duplicate entry. Cancellation creates a new negative payment record to reverse the original; the original payment is not deleted.

Request Body Example:

{
    "info": "Wrong payment method used",
    "cancel_date": "2024-03-20T14:00:00"
}

The info field is required and should describe the reason for cancellation. The cancel_date field is required. Note that if the department setting payment_cancel_set_date is not enabled, the provided date is ignored and the system assigns the date automatically.

Note

After cancellation, the invoice’s outstanding balance is restored. You can then record a new payment with the correct details.

Credit Notes (Refunds)

Credit notes are used to fully or partially refund a finalized invoice. The result is a new invoice with credit_note=true that represents the amount being credited back to the client.

Full Refund

API endpoint: POST https://provetcloud.com/<provet_id>/api/0.1/invoice/<id>/full_refund/

Creates a credit note for the full invoice amount.

Request Body Example:

{
    "use_original_invoice_date": true
}

Set use_original_invoice_date to true to date the credit note on the same date as the original invoice. Set to false to use today’s date.

The response returns the new credit note invoice object with credit_note=true.

Partial Refund

API endpoint: POST https://provetcloud.com/<provet_id>/api/0.1/invoice/<id>/partial_refund/

Creates a credit note for selected invoice rows only.

Request Body Example:

{
    "invoice_rows": [
        {"invoice_row": "https://provetcloud.com/<provet_id>/api/0.1/invoicerow/789/"},
        {"invoice_row": "https://provetcloud.com/<provet_id>/api/0.1/invoicerow/790/"}
    ],
    "use_original_invoice_date": false
}

Fetch the list of rows for an invoice before calling this endpoint:

GET /api/0.1/invoicerow/?invoice__is=12345

Note

A credit note invoice is a new invoice record. After creating a credit note, record the actual payout to the client either by creating a payment cancellation on the original invoice or by recording a refund to a prepayment balance.

Unallocated Payments (Prepayments)

Unallocated payments represent funds received from a client before an invoice exists — for example, a deposit for a future procedure or boarding stay. The available balance (unused_amount) decreases automatically as the funds are applied to invoices.

Recording a Prepayment

API endpoint: POST https://provetcloud.com/<provet_id>/api/0.1/unallocatedpayment/

Request Body Example:

{
    "department": "https://provetcloud.com/<provet_id>/api/0.1/department/1/",
    "client": "https://provetcloud.com/<provet_id>/api/0.1/client/456/",
    "payment_type": 1,
    "paid": "500.00",
    "description": "Deposit for upcoming dental procedure"
}

The description field is optional.

Note

The unused_amount field in the response is read-only and system-calculated. It starts equal to paid and decreases as payments are applied to invoices. You cannot update it directly.

Checking Available Balance

GET /api/0.1/unallocatedpayment/?client__is=456

This returns all prepayments for a client. Check the fully_used and unused_amount fields on each record to identify those with a remaining balance.

Refunding a Prepayment

To refund a prepayment that was not used (or only partially used), create a new unallocated payment record with a negative paid amount and a refunds field pointing to the original prepayment:

Request Body Example:

{
    "department": "https://provetcloud.com/<provet_id>/api/0.1/department/1/",
    "client": "https://provetcloud.com/<provet_id>/api/0.1/client/456/",
    "payment_type": 1,
    "paid": "-200.00",
    "refunds": "https://provetcloud.com/<provet_id>/api/0.1/unallocatedpayment/50/"
}

The absolute value of paid must not exceed the unused_amount of the referenced prepayment.

Recommended ERP / Accounting Sync Pattern

This section describes a practical sync pattern for integrating Provet invoice data with an external accounting or ERP system such as Microsoft Business Central or SAP.

Step 1: Poll for changed invoices

Fetch finalized invoices that have been modified since your last sync run:

GET /api/0.1/invoice/?status__is=3&modified__gte=<last_sync_timestamp>

Store the current timestamp before each sync run and use it as modified__gte on the next run. This gives you only the changed records rather than the full dataset.

Step 2: Fetch invoice rows

For each invoice returned, fetch its line items:

GET /api/0.1/invoicerow/?invoice__is=<invoice_id>

Use account_number on each row to map line items to your chart of accounts.

Step 3: Fetch payments

For each invoice, fetch payment records to determine the payment method and amount received:

GET /api/0.1/invoicepayment/?invoice__is=<invoice_id>

Step 4: Check unallocated payments

To reconcile prepayments, poll for recently changed prepayments and filter out fully used ones in your integration:

GET /api/0.1/unallocatedpayment/?modified__gte=<last_sync_timestamp>

Step 5: Determine accounting fields

Use the following field mapping for ERP documents:

ERP concept	Provet field	Notes
Document date	`invoice_date`	The business date of the invoice
Due date	`invoice_due_date`	Payment deadline
Settlement date	`date_paid`	Set automatically when fully paid; `null` if unpaid
Document number	`id`	Unique invoice ID; use `invoice_number` if available
Net amount	`total`	Total excluding VAT
VAT amount	`total_vat`	Total VAT
Gross amount	`total_with_vat`	Total including VAT
Outstanding balance	`due_sum`	Amount still owed (including insurance portions)
Client portion outstanding	`client_due_sum`	Amount owed by client only

Note

Consider using webhooks for invoice and payment events to reduce polling frequency. Webhooks notify your system immediately when an invoice is finalized or a payment is recorded, which removes the need to poll every few minutes. See Webhooks for configuration details and List of Webhook Triggers for available events.