# Invoice Falcon API v3 — Agent Skill

You are integrating with Invoice Falcon — invoices, quotes, credit notes and packing slips for Shopify orders. This is the root skill document: how to authenticate, discover the surface and call any action.

## Getting started

- **Base URL:** `https://app.invoicefalcon.com/api/v3/external`
- **Auth:** every call needs an `X-Auth-Token: <api_key>` header (`Authorization: Bearer <api_key>` also works). The merchant copies the key from the Invoice Falcon dashboard → Settings → API. This document, `/llms.txt`, the `/help` manifests, `openapi.json` and `mcp.json` need no key.
- **Content type:** JSON in, JSON out. Errors return `{ "errors": [string, ...], "code": "..." }`.
- **Example:** `curl -H 'X-Auth-Token: <api_key>' 'https://app.invoicefalcon.com/api/v3/external/documents/invoices?per_page=5'`
- **OpenAPI:** `https://app.invoicefalcon.com/api/v3/openapi.json`
- **MCP:** `https://app.invoicefalcon.com/api/v3/external/mcp` is an MCP server (streamable HTTP) with three tools over the same action catalog: `search` finds the action for a request, `execute_read` runs a GET action, `execute_write` runs a POST, PATCH or DELETE action. It authenticates with an OAuth 2.1 sign-in (Claude.ai and ChatGPT connectors do this by themselves) or with the shop's connector key as `Authorization: Bearer <mcp_connector_key>` (dashboard → Settings → Integrations → AI connectors); the REST `api_key` is refused there. Manifest: `https://app.invoicefalcon.com/api/v3/mcp.json`. OAuth discovery: `https://app.invoicefalcon.com/.well-known/oauth-authorization-server` and `https://app.invoicefalcon.com/.well-known/oauth-protected-resource`.

## Core idea

The API is action-driven. Every action declares a description, aliases (natural-language phrasings), a path and a verb. Match the merchant's intent to one action from the manifest, build its body from `request_schema`, call it.

## Discovery

- `GET /help` — every action: path, method, description, aliases, request schema, value labels.
- `GET /help?prefix=/documents/invoices` or `GET /documents/invoices/help` — a scope.

## Conventions

- Reads return the resource shape; lists return `{ "items": [...], "page": { "number", "size", "total", "total_pages" } }` and take `page` (1-based) and `per_page` (max 100). Order lists page by cursor instead: `page.end_cursor` goes into `after`.
- Settings are deep-partial `PATCH`es: fields you do not send are untouched. Unknown keys fail with `422 unmapped_settings`, nothing saved.
- Named `POST` actions carry side effects (send, mark paid, issue a credit note). Bulk print/send answer `202` with a job id to poll.
- Shopify records are named by gid (`gid://shopify/Order/123`); bare numbers are accepted on input.
- Creates answer `201`; creating a document for an order that already has one answers `200` with `already_existed: true`.

## Common tasks

Each recipe is a sequence of calls. Read first, change only after the merchant agrees, and write the `#` of an order number as `%23` in a REST path (`/orders/%231080`; the MCP accepts it plain).

- **Plan and invoices left:** `GET /account/plan` → `usage.remaining` is what is left this cycle (`null` on a paid plan), `usage.cycle_resets_on` when it resets.
- **Latest invoice PDF:** `GET /orders` (newest first; pages by `after` cursor, `first` is ignored) → the order's `invoice.id` → `GET /documents/invoices/:id` and use `pdf.url` when `pdf.available` is true. Only when it is false, or a fresh render is wanted, `POST /documents/invoices/:id/pdf`. The link is signed and long; copy it whole.
- **Change an email subject or body:** `PATCH /account/emails/invoice` with `{"subject": "..."}`, then check `custom_text` in the answer: the text is only sent when `PATCH /account/emails {"custom_text": true}`. Each template says `in_use`. Sending `""` returns a field to the default.
- **Translate template text:** `PATCH /templates/:id` with `{"content_translations": {"footer_message": {"de": "..."}}}` (only `footer_message` is translatable). The value replaces the stored one, so send `{}` to clear. Undo an edit with `POST /templates/:id/versions/:version_id/restore`: it returns the template as it was just before that revision (`changes.from` in `GET /templates/:id/versions/:version_id`).
- **Resend an invoice:** `GET /documents/invoices/:id/history` (who got it, bounces) → `POST /documents/invoices/:id/send`, with `to` only for a corrected address. A send to another address is shown in the history with `to_customer: false`.
- **Customer says they never got the invoice:** `GET /orders/:id/troubleshoot` in one call: cancelled order, missing email, unverified sender, plan limit, automatic-invoice rules, never emailed, bounced. Its `diagnosis` names the request that fixes each finding.
- **Delete something permanent:** `DELETE /templates/:id` (or a credit note) first without `confirm`: nothing is deleted and the `409 confirmation_required` says what would be. Ask the merchant, then repeat with `?confirm=true`.

## Errors

| Status | `code` | Meaning |
|---|---|---|
| 401 | `unauthorized` | Missing or unknown `X-Auth-Token`, or the shop uninstalled the app. |
| 403 | `v3_required` | The shop still uses the previous dashboard. |
| 403 | `paid_plan_required` | API access needs a paid plan. |
| 404 | `not_found` | No such resource for this shop, or no action registered at this path. |
| 409 | `confirmation_required` | A destructive action needs `confirm: true` after the merchant agrees. Nothing changed. |
| 409 | `invoice_locked`, `stale_next_invoice_number`, ... | The request conflicts with the current state. Nothing changed. |
| 422 | `unmapped_settings`, `invalid_date`, ... or none | Validation failed. Nothing saved. |
| 429 | `rate_limited`, `bulk_action_in_progress` | Wait `retry_after` seconds (also the `Retry-After` header). |
| 502 | `shopify_error` | Shopify did not answer. Retry later. |

## All registered actions

| Method + Path | Description | Aliases |
|---|---|---|
| `GET /account/automation` | What the store automates: whether invoices are emailed automatically, after what delay and on which order condition (any order, a payment status, a fulfillment status or a shipment status, narrowed by customer and order tags and by sales channel); automatic credit notes on refunds; the pay-now button in emails; and payment reminders (due days, interval, before/after, extra recipients). Read-only. | automatic invoicing settings, are invoices sent automatically, when do invoices go out, payment reminder settings, automatic credit notes, pay now button, automation rules |
| `PATCH /account/automation` | Change what the store automates: automatic invoice emails and their condition (any order, a payment, fulfillment or shipment status, narrowed by customer and order tags and by sales channel), automatic credit notes on refunds, the Pay now button, and payment reminders. Deep partial. Returns the automation section as the read shows it. | turn on automatic invoicing, send invoices automatically when paid, stop automatic invoices, enable payment reminders, remind customers every 7 days, create credit notes on refund, turn off the pay now button, only invoice customers tagged wholesale, only invoice online store orders, skip marketplace orders |
| `GET /account/documents` | The document defaults: invoice numbering (prefix, next number, order number reuse), which dates are printed, document language and auto-detection, multicurrency, PDF file name, the business name, address, contact and tax registration shown on every document, invoice locking, EU VAT footer notes and the "Created with Invoice Falcon" brand. Read-only. | document settings, invoice numbering, business address on invoices, invoice language, tax id on invoices, pdf file name, are invoices locked after issue, next invoice number |
| `PATCH /account/documents` | Change the document defaults every template inherits: invoice numbering, which dates are printed, language and currency, the PDF file name, the business name, address and contact, the tax registration, invoice locking, EU VAT footer notes and the Invoice Falcon brand line. Deep partial. Returns the documents section as the read shows it. | change invoice prefix, set the next invoice number, update business address on invoices, change document language, set my vat number, lock invoices after issue, remove invoice falcon branding, change the pdf file name |
| `GET /account/e_invoicing` | The e-invoicing setup: whether it is available for the store (German stores), switched on and actually active (paid plan and a complete seller profile), whether e-invoices are generated automatically or on request, and the seller profile (legal name, VAT id or tax number, city, postcode, small-business status, bank details) with the values resolved from store details where the profile leaves them blank. Read-only. | e-invoicing settings, is e-invoicing on, xrechnung setup, zugferd settings, e-invoice seller profile, why is my e-invoice not generated |
| `PATCH /account/e_invoicing` | Change the e-invoicing setup of a German store: switch it on or off, choose automatic or on-request generation, and edit the seller profile (legal name, VAT id or tax number, city, postcode, small-business status) and bank details. Deep partial. Returns the e_invoicing section, including whether it is now active. | turn on e-invoicing, set up xrechnung, enter my vat id for e-invoices, add my iban, generate e-invoices only on request, disable e-invoicing, zugferd settings |
| `GET /account/emails` | The email language and, for each document type (invoice, quote, credit note, payment reminder), the subject and body the store sends, with `customized` telling whether that is the merchant's own text or the default for the language. Read-only. | email templates, what does my invoice email say, email subject and body, email language, custom email text, payment reminder email text |
| `PATCH /account/emails` | Change the language emails go out in and whether the store's own email text is used instead of the default. Deep partial. To change the text itself use PATCH /account/emails/:kind. Returns the emails section as the read shows it. | change email language, send emails in german, use my own email text, turn off custom email text, email locale, switch to default email text |
| `PATCH /account/emails/:kind` | Set the store's own subject and/or body for one email kind: invoice, quote, credit_note or payment_reminder. Liquid placeholders are allowed and checked. Sending the default text (or an empty string) returns that field to the default for the language. The text is only sent when `custom_text` is true (PATCH /account/emails); each template says `in_use`. Returns the emails section. | change the invoice email text, edit email subject, edit the payment reminder email, customise the quote email, reset the email body to default, set credit note email wording |
| `GET /account/integrations` | What the store has connected: whether an API key exists (never the key itself), the payment processor used for pay-now links and its mode, and the per-language texts of the Customer Accounts invoice download widget. Read-only. | integrations, is stripe connected, do I have an API key, customer accounts translations, payment processor settings, connected apps |
| `POST /account/integrations/api_key/rotate` | Replace the store's API key with a new one and return it. The old key stops working at once, including for the request that rotated it. The key is shown only in this response. | rotate api key, regenerate api key, new api key, reset api key, my api key was leaked |
| `GET /account/plan` | The shop's Invoice Falcon plan and this billing cycle's usage: the plan name, whether it is paid, the Free plan monthly invoice limit and how many orders have been invoiced against it, and when the cycle resets. Read-only. | what plan am i on, plan and usage, how many invoices have i used, monthly limit, when does my limit reset, am i on the free plan |
| `GET /account/sending` | How the store sends email: the custom "from" address and whether its domain is verified (and therefore in use), who gets a copy of every invoice email (a BCC list and an optional customer metafield holding extra recipients), and whether sending is currently allowed. Read-only. | email sender settings, what address do my invoices come from, is my sending domain verified, bcc settings, who gets copies of invoice emails, can I send emails |
| `PATCH /account/sending` | Change how the store sends email: the custom "from" address, whether copies of every invoice email go to the store and to which addresses, and the customer metafield that adds recipients. Deep partial: only the fields sent change. Returns the sending section as the read shows it. | change the from address, send invoice emails from my domain, bcc me on invoices, send a copy of every invoice, stop copying invoice emails, set the cc metafield, change sender email |
| `GET /account/setup` | The store's setup state: store name, domain, country, currency and timezone; plan name; when the app was installed and onboarding finished; which interface the store uses; and the getting-started checklist (design picked, editor opened, first document, automatic invoicing). Read-only. | setup status, onboarding checklist, is the store set up, store details, what is left to set up, store timezone and currency |
| `POST /account/setup/dismiss` | Hide the getting-started checklist on the dashboard home for good. Idempotent. Returns the setup section. | dismiss the setup checklist, hide getting started, skip onboarding checklist, remove the checklist from home |
| `GET /customers` | The customers Invoice Falcon stores: those on one of its documents, edited in the app or added in it. Not every Shopify customer (Invoice Falcon no longer copies them). Alphabetical, with contact details, tax and EORI numbers, tags and default address. `q` searches name, email, phone, tax number, EORI number and tags. Offset pages (`page`, `per_page`). Read-only. | list customers, find customer, search customers by email, customers with a VAT number, who is this customer, customer list |
| `GET /customers/:id` | One customer with every address on file and the documents issued to them: how many, and the most recent five with their numbers and sent/paid times. Accepts the Invoice Falcon customer id (a number) or the Shopify customer gid (gid://shopify/Customer/123). Read-only. | show customer, customer details, customer addresses, invoices for a customer, how many invoices did this customer get |
| `GET /documents/bulk` | The shop bulk jobs, newest first, as the Bulk actions page lists them: kind, status, progress, count and the download link of finished PDF jobs. | list bulk jobs, bulk action history, my bulk downloads, recent bulk prints, running bulk jobs, bulk exports |
| `GET /documents/bulk/:job_id` | One bulk job: status (pending, processing, finalizing, complete, failed, cancelled), progress, the invoices done and failed by number, the failure reason, and for a finished PDF job a signed download link valid for one week. | bulk job status, is my bulk download ready, bulk print progress, download bulk pdf, check bulk send, bulk action result |
| `POST /documents/bulk/:job_id/cancel` | Cancels a bulk job that has not finished, as the Bulk actions page does. Work already done stays done (emails already sent are sent); the job stops picking up more invoices. | cancel bulk job, stop bulk print, stop bulk send, abort bulk action, cancel bulk download, halt bulk job |
| `POST /documents/bulk/print` | Starts a bulk PDF job for many invoices, as the Invoices page bulk print / download does: pick invoices by id or by the list filters, get one merged PDF (bundle) or a zip of single PDFs (separate). Returns 202 with a job id; poll GET /documents/bulk/:job_id for progress and the download link. | bulk print invoices, download many invoices, export invoices as pdf, print all invoices, zip of invoices, print invoices for a date range, download last month invoices |
| `POST /documents/bulk/send` | Emails many invoices to their customers in one job, as the Invoices page bulk send does: pick invoices by id, or by a created date range with optional status / link / document type. Returns 202 with a job id; GET /documents/bulk/:job_id reports which were sent. | bulk send invoices, email all unpaid invoices, send invoices for a date range, send many invoices, email these invoices, mass send invoices |
| `POST /documents/credit_notes` | Raises a credit note for an invoice, as the order page does: a copy of the invoice with the next credit note number that credits the full invoice, then renders its PDF and returns it in full. If the invoice already has a credit note, that one is returned with already_existed: true. Partial credits are not supported; edit the credit note lines in the dashboard editor. | create credit note, credit this invoice, issue credit note, refund invoice as credit note, raise credit note for invoice, new credit note, cancel invoice with credit note |
| `GET /documents/credit_notes` | The credit notes the Credit notes tab lists, newest first, as list rows: credit note number, the invoice and Shopify order it credits, customer, total, and when it was sent or printed. q matches the credit note number and the credited invoice number. Read-only. | list credit notes, show credit notes, find a credit note, credit notes for an invoice, refund documents, credit notes this month |
| `DELETE /documents/credit_notes/:id` | Deletes a credit note permanently, as the dashboard does. The credited invoice is untouched and a new credit note can be raised for it afterwards. (An invoice created by mistake has its own permanent delete: DELETE /documents/invoices/:id/permanent.) | delete credit note, remove credit note, discard credit note, undo credit note, cancel credit note, erase credit note |
| `GET /documents/credit_notes/:id` | One credit note in full: the invoice shape (numbers, dates, totals, customer, addresses, line items, PDF availability) plus the credited invoice and Shopify order, and the Shopify refunds on that order with their reason and lines. 404 for an id that is not a credit note. Read-only. | show credit note, credit note details, open credit note, which invoice does this credit note credit, credit note pdf link, refund lines on a credit note |
| `POST /documents/credit_notes/:id/pdf` | Renders the credit note PDF (or reuses the stored one when nothing changed) and returns a signed download URL valid for one week, the file name and when it was generated. | download credit note pdf, get credit note pdf, print credit note, regenerate credit note pdf, credit note pdf link, render credit note |
| `POST /documents/credit_notes/:id/send` | Emails a credit note to the customer through the shop sender, as the Send button does: renders the PDF when needed, attaches it, records the send and returns the credit note in full. Recipient, cc, subject and message can be overridden for this one email. | send credit note, email credit note, email the credit note to the customer, resend credit note, send credit note to another address, mail the credit note |
| `POST /documents/invoices` | Creates the invoice for a Shopify order the way the order page does: reads the order from Shopify, builds the invoice with its line items, taxes and addresses, renders the PDF and returns the full invoice. If the shop already has an invoice for that order (most are created by the order webhook) that invoice is returned with already_existed: true instead of a duplicate. | create invoice, invoice this order, generate invoice for order, make an invoice, new invoice, invoice order #1001, issue invoice |
| `GET /documents/invoices` | The invoices the V3 Invoices page lists, newest first, as list rows (number, order, customer, financial status, total, sent / printed / reminder timestamps). Invoices only by default; pass document_type to list quotes, credit notes or pro forma invoices from the same table. Trashed invoices are left out unless link=trashed. Read-only. | list invoices, show my invoices, find an invoice, search invoices, unpaid invoices, invoices for an order, invoices from last month, trashed invoices |
| `DELETE /documents/invoices/:id` | Moves an invoice to the trash, as the Invoices page does: it leaves the lists, keeps its number and PDF, and can be restored. Nothing is deleted permanently and Shopify is not touched. | trash invoice, delete invoice, remove invoice, move invoice to trash, hide invoice, discard invoice |
| `GET /documents/invoices/:id` | One document in full, as the order page and the invoice editor show it: numbers, dates, financial status, totals in the document currency, customer, billing and shipping addresses, line items with tax and discount, shipping and tax lines, notes, the Shopify order link, whether a PDF is stored (with a one-week signed URL) and the e-invoice state. Any document type the shop issued can be read here; document_type says which. Read-only: it never generates or regenerates the PDF. | show invoice, invoice details, open invoice, what is on this invoice, invoice totals, invoice line items, invoice pdf link |
| `PATCH /documents/invoices/:id` | Edits the fields of one invoice the invoice editor lets a merchant change: document number, issue, due, tax and fulfilment dates, PO number, payment terms, the order note, the footer note and up to four custom fields. Only the keys sent change; returns the full invoice. | edit invoice, change invoice due date, change invoice number, add note to invoice, set po number on invoice, update invoice fields, change invoice date, edit custom fields |
| `GET /documents/invoices/:id/history` | What happened to a document: every time it was emailed (to which address, whether that is the customer's, and whether it was automatic, a payment reminder, a bulk send or a BCC copy), printed, downloaded or opened, newest first, plus the emails sent for it with the recipient and the delivery, open, click and bounce timestamps the mail provider reported. The last 200 of each. Read-only. | invoice history, was this invoice sent, when was the invoice emailed, invoice activity, did the customer open the invoice, did the invoice bounce, who received this invoice |
| `POST /documents/invoices/:id/mark_paid` | Marks an invoice paid on the document: sets its financial status to paid and the paid-at time, the same field edit the invoice editor saves. Payment reminders stop for it. Shopify is not told; the order itself keeps its own payment state. | mark invoice paid, mark as paid, invoice was paid, record payment on invoice, set invoice paid, customer paid this invoice |
| `POST /documents/invoices/:id/mark_unpaid` | Reverts a paid mark: sets the invoice financial status back to pending and clears the paid-at time, the same field edit the invoice editor saves. Shopify is not told. | mark invoice unpaid, mark as unpaid, undo mark paid, invoice not paid after all, set invoice pending, reopen invoice |
| `POST /documents/invoices/:id/pdf` | Renders the invoice PDF (or reuses the stored one when nothing changed) and returns a signed download URL valid for one week, the file name and when it was generated. Records a download in the invoice history. To only get the link, read the invoice instead (`pdf.url`); use this for a fresh render or when no PDF is stored yet. | download invoice pdf, get invoice pdf, print invoice, regenerate invoice pdf, invoice pdf link, render invoice |
| `DELETE /documents/invoices/:id/permanent` | Deletes an invoice permanently so its number can be used again. For an invoice created by mistake (an order opened by accident) that was never emailed. When the invoice holds the latest sequential number, `rewind_counter: true` also sets the template's next invoice number back to it. Refused for an invoice that was emailed, has a credit note or has an e-invoice: raise a credit note for those instead. Paid plans only. | delete invoice permanently, permanently delete invoice, erase invoice, free up invoice number, reuse invoice number, undo invoice, remove accidental invoice, delete invoice and reset numbering |
| `POST /documents/invoices/:id/restore` | Takes an invoice out of the trash so it shows in the lists again. Returns the full invoice; a no-op for an invoice that is not trashed. | restore invoice, untrash invoice, recover deleted invoice, bring back invoice, undo delete invoice, restore from trash |
| `POST /documents/invoices/:id/send` | Emails an invoice to its customer through the shop sender, exactly as the Send button does: renders the PDF when needed, attaches it, records the send in the invoice history and returns the full invoice. Recipient, cc, subject and message can be overridden for this one email. | send invoice, email invoice, email this invoice to the customer, resend invoice, send invoice to another address, mail the invoice |
| `GET /documents/packing_slips/:invoice_id` | Whether a packing slip PDF is stored for an invoice, and a one-week signed URL to it when it is. A packing slip is the invoice rendered through a packing-slip template; it exists only after it was printed or downloaded once. Read-only: it never renders the PDF. | packing slip for invoice, packing slip pdf, is there a packing slip, download packing slip, delivery note for order |
| `POST /documents/quotes` | Creates the quote for a Shopify draft order the way the Quotes page does: reads the draft order from Shopify, builds the quote with its line items and addresses (and the payment link when the draft has an invoice URL), renders the PDF and returns the full quote. If the shop already has a quote for that draft order it is returned with already_existed: true. | create quote, quote this draft order, generate quote, make a quote, new quote, quote for draft order, send quote for draft |
| `GET /documents/quotes` | The quotes the Draft orders page knows about: invoices raised from Shopify draft orders, newest first, as list rows. A quote is the same record as an invoice with document_type 'quote', so the rows read like invoice rows plus the draft order gid. Trashed quotes are left out unless link=trashed. Read-only. | list quotes, show my quotes, draft order invoices, find a quote, quotes for a draft order, quotes from last week |
| `GET /documents/quotes/:id` | One quote in full: the invoice shape (numbers, dates, totals, customer, addresses, line items, PDF availability) plus the Shopify draft order gid and the payment link. 404 for an id that is not a quote; invoices and credit notes have their own reads. Read-only. | show quote, quote details, open quote, what is on this quote, quote pdf link, quote for draft order |
| `POST /documents/quotes/:id/pdf` | Renders the quote PDF (or reuses the stored one when nothing changed) and returns a signed download URL valid for one week, the file name and when it was generated. | download quote pdf, get quote pdf, print quote, regenerate quote pdf, quote pdf link, render quote |
| `POST /documents/quotes/:id/send` | Emails a quote to the customer through the shop sender, as the Send button does: renders the PDF when needed, attaches it, records the send and returns the quote in full. Recipient, cc, subject and message can be overridden for this one email. | send quote, email quote, email the quote to the customer, resend quote, send quote to another address, mail the quote |
| `GET /orders` | The Shopify orders of the store as the Orders page lists them, newest first, each with the Invoice Falcon invoice that exists for it (number, when it was sent, printed or downloaded, e-invoice state) or `invoice: null` when none was made yet. Filters match the page: payment status, fulfillment status, a created date range and a free-text search. Pages by Shopify cursor: pass `page.end_cursor` as `after` for the next page. Read-only; it never creates invoices. | list orders, show my orders, recent orders, orders without an invoice, unpaid orders, orders from last week, find order, which orders were invoiced |
| `GET /orders/:id` | One Shopify order as the order page shows it: customer, addresses, line items, totals and tax lines from Shopify, plus every Invoice Falcon document that exists for it (invoice, credit notes) with their numbers and send/print/download times. Accepts a gid, a bare Shopify id or the order number ("#1001" or "1001"). Read-only. | show order, order details, what did we send for order, is order 1001 invoiced, open order, order line items, documents for an order |
| `GET /orders/:id/troubleshoot` | Why a customer did not get their invoice, in one call: the order (cancelled? has an email address?), whether an invoice exists and was ever emailed and to which address, bounces and rejections, the store's sender (verified?), whether sending is allowed, the Free plan limit and the automatic-invoice rules. Ends with a `diagnosis` that names the request fixing each finding. | customer didn't get their invoice, invoice not received, why was the invoice not sent, customer says no email, troubleshoot order, why did the invoice not go out, diagnose order |
| `GET /orders/drafts` | The Shopify draft orders as the Draft orders tab lists them, newest first, each with the quote Invoice Falcon made for it (number, when it was sent, printed or downloaded) or `invoice: null`. Filters: draft status (open, invoice_sent, completed), a created date range and a free-text search. Pages by Shopify cursor. Read-only. | list draft orders, show drafts, open quotes, draft orders without a quote, recent drafts, which drafts got a quote |
| `GET /orders/drafts/:id` | One Shopify draft order as its page shows it: customer, addresses, line items and totals from Shopify, plus the quote Invoice Falcon made for it, if any. Accepts a gid (gid://shopify/DraftOrder/123), a bare id or the draft name ("#D12"). Read-only. | show draft order, draft order details, open quote, is the draft quoted, draft line items |
| `POST /templates` | Create a template from one of the app's designs (see GET /templates/designs): the design sets the document type and the starting layout. Optionally name it and make it the default for regular orders. Returns the new template in full; edit it with PATCH /templates/:id. | create a template, add a packing slip template, new invoice template from the modern design, start a template, add another template |
| `GET /templates` | The store's document templates (invoices, packing slips, quotes, credit notes, return forms), newest first: name, document type, the design it started from, which order kinds it is the default for, and its logo. Filter with `document_type`. Read-only. | list templates, which templates do I have, default invoice template, packing slip templates, show my templates, template list |
| `DELETE /templates/:id` | Delete a template. A template that is the default for any order kind is refused: make another template the default first. Existing PDFs are kept. | delete template, remove a template, get rid of the old invoice template |
| `GET /templates/:id` | One template in full: style (colour, font, date format), numbering, every editor section (order information, payment, shipping, customer, items, order total, extra, social) with its switches and texts, label overrides, content translations and the Liquid source. Read-only. | show template, template settings, what does my invoice template show, template details, is the SKU shown on invoices, template liquid code |
| `PATCH /templates/:id` | Change a template: its name, which order kinds it is the default for, logo, style, numbering, any editor section switch or text (`sections.<group>.<field>`, exactly as the read lists them), label overrides, content translations or the Liquid source. Deep partial. Returns the template in full. | edit template, show the sku on invoices, hide product images on the invoice, rename template, change the accent colour, make this the default invoice template, set the invoice prefix on a template, turn off the footer notes |
| `POST /templates/:id/duplicate` | Copy a template, settings, texts and logo included, as "<name> (copy)". The copy is not a default for any order kind. Returns the new template in full. | duplicate template, copy template, clone my invoice template, make a copy of a template |
| `POST /templates/:id/set_default` | Make a template the default for one or more order kinds: orders, draft_orders, pos_orders or credit_notes (default: orders). The previous default for each kind is cleared. Returns the template in full. | set default template, use this template for all orders, make it the default for credit notes, default packing slip, change my default invoice template |
| `GET /templates/:id/versions` | A template's saved revisions, newest first (the last 15 edits are kept): when each was saved, its label if the merchant named it, and which fields changed. Read-only. | template history, template versions, what changed in my template, previous template versions, when was the template last edited |
| `GET /templates/:id/versions/:version_id` | One saved revision of a template with the before and after value of every field that changed in that save. Read-only. | show template version, what did this template edit change, template revision details, compare template version |
| `POST /templates/:id/versions/:version_id/restore` | Put a template back to how it was just before a saved revision was made (see GET /templates/:id/versions: each revision's changes.from is what you get back). The restore itself is not recorded as a revision. Returns the template in full. | restore template version, undo template changes, roll back the template, revert my invoice template |
| `GET /templates/designs` | The app-owned starting designs a new template can be created from (Standard, Classic, Modern and so on): key, name, description and document type. Static; the same for every store. Read-only. | template designs, which designs can I pick, invoice layouts, design gallery, available template styles |

## Rate limits

Cost-weighted per key: reads cost 1, writes 2, 40 points per 60 seconds. Headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`. Over the limit: `429 { "errors": [...], "code": "rate_limited", "retry_after": seconds }` with a `Retry-After` header.
