Skip to content

Requests and responses

Pagination, record ids, partial updates, confirmations and other conventions every API v3 call follows.

Last updated

Every API v3 action follows the same conventions. Learn them once and every page of the reference reads the same way.

Record Id you send
Invoice Falcon documents, templates, customers The numeric id from a list or read, such as 48213
Shopify orders and draft orders A gid (gid://shopify/Order/5550001234), the bare number (5550001234) or the order name (#1042)

In a REST path, write the # of an order name as %23: GET /orders/%231042. In a JSON body, send it as is: {"order_id": "#1042"}. Responses always name Shopify records by gid.

Lists return the rows and a page object:

{
"items": [ { "id": 48213, "...": "..." } ],
"page": { "number": 1, "size": 25, "total": 318, "total_pages": 13 }
}

Pass page (starting at 1) and per_page (default 25, at most 100).

Orders come straight from Shopify, so GET /orders and GET /orders/drafts page by cursor instead: pass the response’s page.end_cursor as after for the next page, or page.start_cursor as before to go back.

Terminal window
curl -s "https://app.invoicefalcon.com/api/v3/external/orders?per_page=50&after=eyJsYXN0X2lkIjo..." \
-H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
  • A create answers 201 Created with the new record.
  • Creating a document for an order that already has one answers 200 with "already_existed": true and the existing document. Retrying a create is safe.

Settings PATCHes are deep-partial: fields you don’t send keep their value.

Terminal window
curl -s -X PATCH https://app.invoicefalcon.com/api/v3/external/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"}}}'
  • An unknown key fails the whole request with 422 and code: "unmapped_settings". Nothing is saved.
  • In email texts, sending "" returns a field to its default.
  • The response is the section as a read would return it, so you can check the result without a second call.

Deleting a template, deleting a credit note and rotating the API key can’t be undone. These actions answer 409 with code: "confirmation_required" and change nothing until you repeat the request with confirmation:

  • DELETE: add ?confirm=true to the URL.
  • POST: add "confirm": true to the body.

The 409 body says what would happen. If your integration acts for a merchant, show that text and ask before you confirm.

Bulk print and bulk send (POST /documents/bulk/print, POST /documents/bulk/send) answer 202 Accepted with a job id. Poll GET /documents/bulk/:job_id until the job finishes, then use the download link it returns. Only one bulk job runs per store at a time; a second one gets 429 with code: "bulk_action_in_progress".

Enum fields come with the label the dashboard shows. The reference lists both, for example financial_status value partially_paid (Partially paid). Use the label when you show a value to a merchant.

Was this page helpful?

Still stuck? Ask Quinn or chat with support