Skip to content

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:

Terminal window
BASE=https://app.invoicefalcon.com/api/v3/external
  1. Find the order. GET /orders lists orders newest first, each with its Invoice Falcon invoice (or null when none exists yet).

    Terminal window
    curl -s "$BASE/orders?q=%231042" -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
  2. 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.available is true, pdf.url is a signed link, valid for a week. Use it whole: it’s long and every character counts.

  3. Only when pdf.available is false, 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.

Terminal window
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.

  1. 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"
  2. Send it. Pass to only 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.

Terminal window
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.

Terminal window
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.

  1. Start the job. Pick invoices by ids, or by filters such as from, to and status.

    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 202 with a job_id.

  2. Poll until status is complete (or failed or cancelled), then use download_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”
Terminal window
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.

Terminal window
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.

Terminal window
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.

  1. 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"
  2. 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"

Deleting is permanent, so the first call only says what would happen:

Terminal window
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.

Was this page helpful?

Still stuck? Ask Quinn or chat with support