Invoice Automation
Create, send, collect and correct invoices automatically, in line with GoBD.
Prerequisites
- An API key with the required scopes
- An active PlanDocket account
Prepare the Key and the Settings
Create an API key with the scope "invoices:write" (add "payments:write" to book payments). Your company data, bank details, tax rates and number ranges come from the invoice settings in the admin area: the API uses exactly the same rules as the admin. Line items may only use the tax rates of your invoice settings.
Create a Draft
POST /api/v1/invoices creates a draft for a participant ("event_participant_id") or a contact ("contact_id"). Without "items" the participant's open billable items (booths, service orders, formulas) are invoiced. Drafts have no invoice number yet ("display_number" shows "Draft #id") and can still be changed with PATCH.
curl -X POST "https://your-tenant.plandocket.com/api/v1/invoices" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"event_participant_id": 7,
"items": [
{"description": "Booth area 12 m²", "quantity": 12, "unit_price": 75, "tax_rate": 19}
],
"include_billable_items": false
}'Issue and Send
POST /api/v1/invoices/{id}/send issues the draft (assigns the next number and the invoice date, then locks it) and e-mails the PDF to the billing address, or to the addresses in "to" (optional "cc", "bcc", "subject", "message"). Use POST /api/v1/invoices/{id}/issue to issue without e-mail. Shortcut: "issue": true or "send": true already when creating. Issued invoices can no longer be edited.
curl -X POST "https://your-tenant.plandocket.com/api/v1/invoices/789/send" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Thank you for exhibiting with us."
}'Download PDF or E-Invoice
GET /api/v1/invoices/{id}/pdf returns the PDF (application/pdf). For invoices created with "e_invoice_format" xrechnung or zugferd, GET /api/v1/invoices/{id}/e-invoice returns the XRechnung XML or the ZUGFeRD PDF (requires e-invoicing to be enabled in the settings).
curl -o invoice.pdf "https://your-tenant.plandocket.com/api/v1/invoices/789/pdf" \
-H "Authorization: Bearer YOUR_API_KEY"
curl -o invoice.xml "https://your-tenant.plandocket.com/api/v1/invoices/789/e-invoice?format=xrechnung" \
-H "Authorization: Bearer YOUR_API_KEY"Book Payments
POST /api/v1/payments with "invoice_number" and "amount" books a payment. The status (partially paid, paid, overdue) follows automatically from payments and credit notes and cannot be set by hand (PATCH with "status": "paid" is rejected with 422). Webhooks: "payment.received" for every payment and "invoice.paid" once nothing is left to pay.
curl -X POST "https://your-tenant.plandocket.com/api/v1/payments" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"invoice_number": "RE-2027-000311",
"amount": 1071.00,
"payment_date": "2027-04-12"
}'Correct with a Credit Note
Issued invoices are never changed (GoBD). POST /api/v1/invoices/{id}/cancel with a "reason" cancels the invoice and creates a credit note for the amount still open. Credit notes are listed under GET /api/v1/credit-notes and have their own PDF. A draft that was never issued is simply discarded.
curl -X POST "https://your-tenant.plandocket.com/api/v1/invoices/789/cancel" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "Invoiced twice"
}'