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.
Requests
Section titled “Requests”- Send JSON bodies with
Content-Type: application/json. Query parameters are forGETfilters. - Reads are
GET. Changes to a record or a settings area arePATCH. Actions with side effects, such as sending, marking paid or issuing a credit note, are namedPOSTpaths:POST /documents/invoices/:id/send,POST /documents/invoices/:id/mark_paid. - Moving an invoice to the trash is
DELETE /documents/invoices/:id. It’s reversible withPOST /documents/invoices/:id/restore.
Record ids
Section titled “Record ids”| 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 and pagination
Section titled “Lists and pagination”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.
curl -s "https://app.invoicefalcon.com/api/v3/external/orders?per_page=50&after=eyJsYXN0X2lkIjo..." \ -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"Creating records
Section titled “Creating records”- A create answers
201 Createdwith the new record. - Creating a document for an order that already has one answers
200with"already_existed": trueand the existing document. Retrying a create is safe.
Partial updates
Section titled “Partial updates”Settings PATCHes are deep-partial: fields you don’t send keep their value.
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
422andcode: "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.
Confirming permanent changes
Section titled “Confirming permanent changes”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=trueto the URL.POST: add"confirm": trueto the body.
The 409 body says what would happen. If your integration acts for a merchant, show that text and ask before you confirm.
Long-running jobs
Section titled “Long-running jobs”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".
Labels for values
Section titled “Labels for values”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.
Thanks for letting us know.
Still stuck? Ask Quinn or chat with support