Common tasks
Worked API v3 examples for the jobs integrations do most: PDFs, sending, troubleshooting, settings and templates.
Last updated
Each task is a short sequence of calls. All examples assume INVOICE_FALCON_API_KEY holds the store’s key and use this base URL:
BASE=https://app.invoicefalcon.com/api/v3/externalGet the PDF of an order’s invoice
Section titled “Get the PDF of an order’s invoice”-
Find the order.
GET /orderslists orders newest first, each with its Invoice Falconinvoice(ornullwhen none exists yet).Terminal window curl -s "$BASE/orders?q=%231042" -H "X-Auth-Token: $INVOICE_FALCON_API_KEY" -
Read the invoice with the order’s
invoice.id:Terminal window curl -s "$BASE/documents/invoices/48213" -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"When
pdf.availableistrue,pdf.urlis a signed link, valid for a week. Use it whole: it’s long and every character counts. -
Only when
pdf.availableisfalse, or you need a fresh render, generate it:Terminal window curl -s -X POST "$BASE/documents/invoices/48213/pdf" -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
A rendered PDF counts toward the Free plan’s monthly invoice limit.
Invoice an order
Section titled “Invoice an order”curl -s -X POST "$BASE/documents/invoices" \ -H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \ -H "Content-Type: application/json" \ -d '{"order_id": "#1042"}'Add "send_email": true to email it straight away, or "template_id" to render with a template other than the default. If the order already has an invoice, you get it back with "already_existed": true.
Resend an invoice
Section titled “Resend an invoice”-
Check who received it and whether it bounced:
Terminal window curl -s "$BASE/documents/invoices/48213/history" -H "X-Auth-Token: $INVOICE_FALCON_API_KEY" -
Send it. Pass
toonly to correct the address; the default is the order’s email.Terminal window curl -s -X POST "$BASE/documents/invoices/48213/send" \-H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \-H "Content-Type: application/json" \-d '{"to": "accounts@example.com"}'
A send to another address shows in the history with to_customer: false. Sending emails the customer at once.
Find out why a customer didn’t get their invoice
Section titled “Find out why a customer didn’t get their invoice”One call checks everything: a cancelled order, a missing email address, the sender, the plan limit, the automatic-invoice rules, whether the invoice was ever emailed, and bounces.
curl -s "$BASE/orders/%231042/troubleshoot" -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"verdict is the first blocking problem. diagnosis lists each finding with the request that fixes it.
Check the plan and invoices left
Section titled “Check the plan and invoices left”curl -s "$BASE/account/plan" -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"usage.remaining is what’s left this billing cycle (null on a paid plan), and usage.cycle_resets_on is when it resets.
Download many invoices as one PDF
Section titled “Download many invoices as one PDF”-
Start the job. Pick invoices by
ids, or by filters such asfrom,toandstatus.Terminal window curl -s -X POST "$BASE/documents/bulk/print" \-H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \-H "Content-Type: application/json" \-d '{"from": "2026-10-01", "to": "2026-10-31", "processing_type": "bundle"}'It answers
202with ajob_id. -
Poll until
statusiscomplete(orfailedorcancelled), then usedownload_url:Terminal window curl -s "$BASE/documents/bulk/7781" -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
Use "processing_type": "separate" for a zip of single PDFs. A job holds up to 5,000 invoices, and one job runs per store at a time.
Send invoices automatically when an order is paid
Section titled “Send invoices automatically when an order is paid”curl -s -X PATCH "$BASE/account/automation" \ -H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \ -H "Content-Type: application/json" \ -d '{"automatic_invoices": {"enabled": true, "when": {"trigger": "payment_status", "payment_status": "paid"}}}'This applies to new orders only. Status and tag conditions need a paid plan.
Change an email’s subject or text
Section titled “Change an email’s subject or text”curl -s -X PATCH "$BASE/account/emails/invoice" \ -H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \ -H "Content-Type: application/json" \ -d '{"subject": "Your invoice is ready"}'Custom text is only sent while custom email text is on. Check custom_text in the response, and turn it on with PATCH /account/emails and {"custom_text": true}. Sending "" for a field returns it to the default.
Translate a template’s footer
Section titled “Translate a template’s footer”curl -s -X PATCH "$BASE/templates/312" \ -H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \ -H "Content-Type: application/json" \ -d '{"content_translations": {"footer_message": {"de": "Vielen Dank für Ihren Einkauf!"}}}'Only footer_message is translatable. The value replaces the stored translations, so send {} to clear them.
Undo a template change
Section titled “Undo a template change”-
List the template’s versions and pick the one to go back to:
Terminal window curl -s "$BASE/templates/312/versions" -H "X-Auth-Token: $INVOICE_FALCON_API_KEY" -
Restore it. The template returns to how it was just before that revision.
Terminal window curl -s -X POST "$BASE/templates/312/versions/9024/restore" -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
Delete a template
Section titled “Delete a template”Deleting is permanent, so the first call only says what would happen:
curl -s -X DELETE "$BASE/templates/312" -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"# 409 confirmation_required: nothing deleted
curl -s -X DELETE "$BASE/templates/312?confirm=true" -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"A template that is the default for any document type is refused. Make another template the default first with POST /templates/:id/set_default.
Thanks for letting us know.
Still stuck? Ask Quinn or chat with support