List invoices
GET
/invoicesCosts 1 rate-limit point · Rate limits
Retrieve a paginated list of invoices. Supports filtering by document type, financial status, and date range.
Query parameters
invoice_typestringFilter by document type.
One ofinvoicequotepro_formaDefault"invoice"financial_statusstringFilter by payment status.
One ofpaidpendingpartially_paidpartially_refundedrefundedvoidedauthorizedcreated_at_minstringFilter invoices created on or after this date (YYYY-MM-DD).
created_at_maxstringFilter invoices created on or before this date (YYYY-MM-DD).
pageintegerPage number.
Default1per_pageintegerItems per page (max 250).
Default25
Returns
invoicesarray of objectsShow 12 child attributesHide child attributes
idintegerExample:48213slugstringUnique identifier for API calls.
numberstringDisplay number (e.g. INV-001).
invoice_typestringExample:invoiceOne ofinvoicequotepro_formashopify_ordertotal_pricestringDecimal string.
currencystringISO 4217 code.
financial_statusstringExample:paidorder_namestringShopify order name (e.g. #1042).
customer_namestringExample:Jane Doecustomer_emailstringExample:jane.doe@example.comcreated_atstringExample:2026-01-15T09:31:12Zupdated_atstringExample:2026-01-15T09:31:40Z
metaobjectShow 4 child attributesHide child attributes
totalintegerExample:3pageintegerExample:1per_pageintegerExample:25total_pagesintegerExample:1
Errors
401
Missing or invalid API key.
403
The store is not on a paid plan. API access requires a paid Invoice Falcon plan.
429
Rate limit exceeded. Check X-RateLimit-Reset header.
GET/invoices
curl "https://app.invoicefalcon.com/api/v1/external/invoices" \
-H "X-Auth-Token: $INVOICE_FALCON_API_KEY"const res = await fetch("https://app.invoicefalcon.com/api/v1/external/invoices", {
headers: {
"X-Auth-Token": process.env.INVOICE_FALCON_API_KEY,
},
});
const data = await res.json();import os
import requests
res = requests.get(
"https://app.invoicefalcon.com/api/v1/external/invoices",
headers={"X-Auth-Token": os.environ["INVOICE_FALCON_API_KEY"]},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.invoicefalcon.com/api/v1/external/invoices")
req = Net::HTTP::Get.new(uri, "X-Auth-Token" => ENV["INVOICE_FALCON_API_KEY"])
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)GET/invoices
curl "https://app.invoicefalcon.com/api/v1/external/invoices?invoice_type=invoice&financial_status=paid" \
-H "X-Auth-Token: $INVOICE_FALCON_API_KEY"const res = await fetch("https://app.invoicefalcon.com/api/v1/external/invoices?invoice_type=invoice&financial_status=paid", {
headers: {
"X-Auth-Token": process.env.INVOICE_FALCON_API_KEY,
},
});
const data = await res.json();import os
import requests
res = requests.get(
"https://app.invoicefalcon.com/api/v1/external/invoices?invoice_type=invoice&financial_status=paid",
headers={"X-Auth-Token": os.environ["INVOICE_FALCON_API_KEY"]},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.invoicefalcon.com/api/v1/external/invoices?invoice_type=invoice&financial_status=paid")
req = Net::HTTP::Get.new(uri, "X-Auth-Token" => ENV["INVOICE_FALCON_API_KEY"])
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)Response
{
"invoices": [
{
"id": 48213,
"slug": "k7xq2m9d4r",
"number": "INV-1042",
"invoice_type": "invoice",
"total_price": "100.94",
"currency": "USD",
"financial_status": "paid",
"order_name": "#1042",
"customer_name": "Jane Doe",
"customer_email": "jane.doe@example.com",
"created_at": "2026-01-15T09:31:12Z",
"updated_at": "2026-01-15T09:31:40Z"
},
{
"id": 48190,
"slug": "p3wz8c1n6t",
"number": "INV-1041",
"invoice_type": "invoice",
"total_price": "58.50",
"currency": "USD",
"financial_status": "pending",
"order_name": "#1041",
"customer_name": "Sam Rivera",
"customer_email": "sam.rivera@example.com",
"created_at": "2026-01-14T09:31:12Z",
"updated_at": "2026-01-14T09:31:40Z"
},
{
"id": 48177,
"slug": "d5hb0y7f2e",
"number": "INV-1040",
"invoice_type": "invoice",
"total_price": "240.00",
"currency": "USD",
"financial_status": "paid",
"order_name": "#1040",
"customer_name": "Alex Chen",
"customer_email": "alex.chen@example.com",
"created_at": "2026-01-13T09:31:12Z",
"updated_at": "2026-01-13T09:31:40Z"
}
],
"meta": {
"total": 3,
"page": 1,
"per_page": 25,
"total_pages": 1
}
}{
"error": "Invalid API key"
}{
"error": "REST API access requires a paid plan"
}{
"error": "Rate limit exceeded",
"retry_after": 30,
"message": "You have exceeded the rate limit of 40 points per 60 seconds. Read requests cost 1 point(s) and write requests cost 2 point(s). Please retry after 30 second(s)."
}