{
  "server": {
    "name": "invoicefalcon-api-v3",
    "version": "3.0.0",
    "url": "https://app.invoicefalcon.com/api/v3/external/mcp",
    "transport": "streamable-http",
    "description": "Invoice Falcon API v3 as an MCP server: 59 actions (documents, orders, templates, customers, account settings) reached through search / execute_read / execute_write instead of one tool per action. Full guide: GET https://app.invoicefalcon.com/api/v3/external/skill.md"
  },
  "auth": {
    "type": "oauth2",
    "header": "Authorization: Bearer <token>",
    "authorization_server": "https://app.invoicefalcon.com/.well-known/oauth-authorization-server",
    "protected_resource": "https://app.invoicefalcon.com/.well-known/oauth-protected-resource",
    "alternatives": [
      "Authorization: Bearer <mcp_connector_key> (from Settings → Integrations → AI connectors)"
    ],
    "description": "Connectors (Claude, ChatGPT) sign in through OAuth; scripts may use the shop's MCP connector key. The REST API key is not accepted here. The shop must be on the new dashboard and a paid plan."
  },
  "tools": [
    {
      "name": "search",
      "description": "Search the Invoice Falcon API v3 action catalog by keyword: matches path, name, description, aliases and notes (e.g. \"send invoice\", \"plan and usage\", \"credit note\", \"email settings\"). Returns method + path + description per match; 3 or fewer matches also include the full request JSON Schema so you know what params execute_read/execute_write expect. An empty query browses everything.",
      "inputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Keyword(s) to search for. Empty string browses the whole catalog."
          },
          "method": {
            "type": "string",
            "enum": [
              "GET",
              "POST",
              "PATCH",
              "DELETE"
            ],
            "description": "Optional: only actions with this HTTP method."
          },
          "limit": {
            "type": "integer",
            "description": "Max results. Default 20."
          }
        },
        "required": [
          "query"
        ]
      },
      "annotations": {
        "destructiveHint": false,
        "idempotentHint": true,
        "openWorldHint": false,
        "readOnlyHint": true
      }
    },
    {
      "name": "execute_read",
      "description": "Run a read (GET) action from the Invoice Falcon API v3 catalog. Use search first to find the method + path and the params it expects. `path` must be concrete: real ids in place of any :placeholder segment. An unknown path, or one registered under another method, returns a structured error.",
      "inputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "method": {
            "type": "string",
            "enum": [
              "GET"
            ],
            "description": "HTTP method: GET."
          },
          "path": {
            "type": "string",
            "description": "Concrete action path from search, e.g. \"/documents/invoices/123\"."
          },
          "params": {
            "type": "object",
            "description": "Request body or query for this action (see request_schema from search)."
          }
        },
        "required": [
          "method",
          "path"
        ]
      },
      "annotations": {
        "destructiveHint": false,
        "idempotentHint": true,
        "openWorldHint": true,
        "readOnlyHint": true
      }
    },
    {
      "name": "execute_write",
      "description": "Run a write (POST/PATCH/DELETE) action from the Invoice Falcon API v3 catalog. Use search first to find the method + path and the params it expects. `path` must be concrete: real ids in place of any :placeholder segment. An unknown path, or one registered under another method, returns a structured error.",
      "inputSchema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "method": {
            "type": "string",
            "enum": [
              "POST",
              "PATCH",
              "DELETE"
            ],
            "description": "HTTP method: POST or PATCH or DELETE."
          },
          "path": {
            "type": "string",
            "description": "Concrete action path from search, e.g. \"/documents/invoices/123\"."
          },
          "params": {
            "type": "object",
            "description": "Request body or query for this action (see request_schema from search)."
          }
        },
        "required": [
          "method",
          "path"
        ]
      },
      "annotations": {
        "destructiveHint": true,
        "idempotentHint": false,
        "openWorldHint": true,
        "readOnlyHint": false
      }
    }
  ],
  "actions": [
    {
      "method": "GET",
      "path": "/account/automation",
      "description": "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."
    },
    {
      "method": "PATCH",
      "path": "/account/automation",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/account/documents",
      "description": "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."
    },
    {
      "method": "PATCH",
      "path": "/account/documents",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/account/e_invoicing",
      "description": "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."
    },
    {
      "method": "PATCH",
      "path": "/account/e_invoicing",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/account/emails",
      "description": "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."
    },
    {
      "method": "PATCH",
      "path": "/account/emails",
      "description": "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."
    },
    {
      "method": "PATCH",
      "path": "/account/emails/:kind",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/account/integrations",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/account/plan",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/account/sending",
      "description": "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."
    },
    {
      "method": "PATCH",
      "path": "/account/sending",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/account/setup",
      "description": "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."
    },
    {
      "method": "POST",
      "path": "/account/setup/dismiss",
      "description": "Hide the getting-started checklist on the dashboard home for good. Idempotent. Returns the setup section."
    },
    {
      "method": "GET",
      "path": "/customers",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/customers/:id",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/documents/bulk",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/documents/bulk/:job_id",
      "description": "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."
    },
    {
      "method": "POST",
      "path": "/documents/bulk/:job_id/cancel",
      "description": "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."
    },
    {
      "method": "POST",
      "path": "/documents/bulk/print",
      "description": "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."
    },
    {
      "method": "POST",
      "path": "/documents/bulk/send",
      "description": "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."
    },
    {
      "method": "POST",
      "path": "/documents/credit_notes",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/documents/credit_notes",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/documents/credit_notes/:id",
      "description": "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."
    },
    {
      "method": "POST",
      "path": "/documents/credit_notes/:id/pdf",
      "description": "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."
    },
    {
      "method": "POST",
      "path": "/documents/credit_notes/:id/send",
      "description": "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."
    },
    {
      "method": "POST",
      "path": "/documents/invoices",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/documents/invoices",
      "description": "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."
    },
    {
      "method": "DELETE",
      "path": "/documents/invoices/:id",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/documents/invoices/:id",
      "description": "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."
    },
    {
      "method": "PATCH",
      "path": "/documents/invoices/:id",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/documents/invoices/:id/history",
      "description": "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."
    },
    {
      "method": "POST",
      "path": "/documents/invoices/:id/mark_paid",
      "description": "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."
    },
    {
      "method": "POST",
      "path": "/documents/invoices/:id/mark_unpaid",
      "description": "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."
    },
    {
      "method": "POST",
      "path": "/documents/invoices/:id/pdf",
      "description": "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."
    },
    {
      "method": "POST",
      "path": "/documents/invoices/:id/restore",
      "description": "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."
    },
    {
      "method": "POST",
      "path": "/documents/invoices/:id/send",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/documents/packing_slips/:invoice_id",
      "description": "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."
    },
    {
      "method": "POST",
      "path": "/documents/quotes",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/documents/quotes",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/documents/quotes/:id",
      "description": "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."
    },
    {
      "method": "POST",
      "path": "/documents/quotes/:id/pdf",
      "description": "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."
    },
    {
      "method": "POST",
      "path": "/documents/quotes/:id/send",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/orders",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/orders/:id",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/orders/:id/troubleshoot",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/orders/drafts",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/orders/drafts/:id",
      "description": "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."
    },
    {
      "method": "POST",
      "path": "/templates",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/templates",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/templates/:id",
      "description": "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."
    },
    {
      "method": "PATCH",
      "path": "/templates/:id",
      "description": "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."
    },
    {
      "method": "POST",
      "path": "/templates/:id/duplicate",
      "description": "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."
    },
    {
      "method": "POST",
      "path": "/templates/:id/set_default",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/templates/:id/versions",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/templates/:id/versions/:version_id",
      "description": "One saved revision of a template with the before and after value of every field that changed in that save. Read-only."
    },
    {
      "method": "POST",
      "path": "/templates/:id/versions/:version_id/restore",
      "description": "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."
    },
    {
      "method": "GET",
      "path": "/templates/designs",
      "description": "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."
    }
  ]
}
