API referenceInvoices
Preview invoice totals
Needs a token with the write:invoices scope. Authentication
Try in Playground sends a real request to app.helvetly.com with a token you paste. It stays in this browser tab only (session storage) and goes to no one else.
POST
Computes lines, VAT groups and totals of an InvoiceInput without saving anything: no draft, no number, nothing booked. It is a POST (so it needs a write-scoped token) but has no side effects and is safe to repeat. The answer is an Invoice with an empty id. 422 validation_failed with details.fields.
bearerAuthheader
AuthorizationBearer <token>A personal API token, hvt_…, with scopes such as read:* or write:invoices
application/json- body
The same input as create_invoice, but client_id is optional (without it the workspace defaults apply). Nothing is saved. Unknown fields are refused (400).
client_id?stringkind?stringDefault
"invoice"Value in
"invoice""partial""prepayment""proforma""self_billed"issue_date?stringDefault: today in the workspace's time zone.
Format
datedue_date?stringDefault: issue date plus the client's terms.
Format
dateservice_date?|Format
dateservice_date_end?|Format
datecurrency?stringlanguage?stringValue in
"de""fr""it""en"vat_mode?stringValue in
"exclusive""inclusive""none"reference?|Length
length <= 100intro?|Length
length <= 1000footer?|Length
length <= 1000note?|Length
length <= 1000discount_percent?|A decimal: a string such as "12.50" (exact) or a number.
payment_methods?reminders_enabled?booleanlines?array<>Items
items <= 200OK
application/json- response
data*curl -X POST 'https://app.helvetly.com/api/v1/invoices/preview' \ -H 'Content-Type: application/json' \ -d '{ "client_id": "cli_123", "lines": [ { "description": "Consulting", "quantity": "2", "unit": "day", "unit_price": "1200.00", "vat_category": "S", "vat_rate": "8.1" } ]}'Example Response
{ "data": { "id": "string", "kind": "invoice", "type_code": "string", "number": "string", "status": "draft", "is_overdue": true, "client_id": "string", "client": { "id": "string", "number": 0, "name": "string" }, "quote": { "id": "string", "number": "string" }, "credited_invoice": { "id": "string", "number": "string" }, "issue_date": "2019-08-24", "due_date": "2019-08-24", "service_date": "2019-08-24", "service_date_end": "2019-08-24", "currency": "string", "language": "string", "vat_mode": "exclusive", "reference": "string", "tax_currency_rate": "string", "intro": "string", "footer": "string", "note": "string", "lines": [ { "id": "string", "position": 0, "description": "string", "quantity": "string", "unit": "string", "unit_price": "1234.50", "discount_percent": "string", "vat_category": "string", "vat_rate": "string", "amount": "1234.50", "vat_exemption_code": "string", "vat_exemption_reason": "string" } ], "discount_percent": "string", "subtotal": "1234.50", "discount_amount": "1234.50", "net_total": "1234.50", "vat_breakdown": [ { "category": "string", "rate": "string", "taxable_amount": "1234.50", "vat_amount": "1234.50" } ], "vat_total": "1234.50", "total": "1234.50", "rounding_amount": "1234.50", "payable_total": "1234.50", "prepaid_total": "1234.50", "prepayments": [ { "id": "string", "number": "string", "payable_total": "1234.50", "status": "string", "vat_breakdown": [ { "category": "string", "rate": "string", "taxable_amount": "1234.50", "vat_amount": "1234.50" } ] } ], "deducted_on": { "id": "string", "number": "string" }, "amount_paid": "1234.50", "amount_credited": "1234.50", "amount_due": "1234.50", "amount_refunded": "1234.50", "refund_due": "1234.50", "payment_methods": { "qr_bill": true, "revolut": true }, "payment": { "iban": "string", "reference_type": "string", "reference": "string", "qr_bill": true, "revolut_url": "string" }, "seller": { "name": "string", "street": "string", "street_number": "string", "apt": "string", "zip": "string", "city": "string", "country": "string", "vat_number": "string", "email": "string", "phone": "string", "electronic_address": { "scheme": "string", "id": "string" }, "registration_number": "string", "region": "string" }, "buyer": { "name": "string", "street": "string", "street_number": "string", "apt": "string", "zip": "string", "city": "string", "country": "string", "vat_number": "string", "email": "string", "phone": "string", "electronic_address": { "scheme": "string", "id": "string" }, "registration_number": "string", "region": "string" }, "payments": [ { "id": "string", "amount": "1234.50", "paid_on": "2019-08-24", "method": "bank_transfer", "note": "string", "created_at": "2019-08-24T14:15:22Z", "created_by": { "id": "string", "name": "string" } } ], "refunds": [ { "id": "string", "amount": "1234.50", "refunded_on": "2019-08-24", "method": "string", "note": "string", "created_at": "2019-08-24T14:15:22Z", "created_by": { "id": "string", "name": "string" } } ], "instalments": { "interval": "string", "items": [ { "seq": 0, "due_date": "2019-08-24", "amount": "1234.50", "effective": "1234.50", "paid": "1234.50", "open": "1234.50", "status": "string", "reference": "string" } ] }, "plan": { "id": "string", "seq": 0, "count": 0 }, "reminders_enabled": true, "issued_at": "2019-08-24T14:15:22Z", "sent_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "origin": "string", "source_document_id": "string" }}