Troubleshoot order
/orders/{id}/troubleshootCosts 1 rate-limit point · Rate limits
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.
Read-only. Start here for a missing-invoice complaint, then run the request a finding names (sends and deletes preview or ask first). Write the # of an order number as %23 in a REST path.
Also searched ascustomer didn't get their invoiceinvoice not receivedwhy was the invoice not sentcustomer says no emailtroubleshoot orderwhy did the invoice not go outdiagnose order
Path parameters
idstringRequiredA Shopify id (gid://shopify/Order/123 or 123) or the order number as the store shows it ("#1001" or "1001").
Returns
orderobjectShow 7 child attributesHide child attributes
shopify_order_idstringExample:gid://shopify/Order/5552001order_numberstringExample:#1080created_atstringExample:2026-03-01T10:00:00Zfinancial_statusstringExample:paidfulfillment_statusstringExample:fulfilledcancelled_atstring, nullableemailstringExample:ann@example.com
documentobjectShow 4 child attributesHide child attributes
idintegerExample:980191022typestringExample:invoicenumberstringExample:INV-1sent_atstringExample:2026-11-10T09:07:40Z
diagnosisarray of objectsShow 4 child attributesHide child attributes
codestringExample:sender_unverifiedseveritystringExample:warningmessagestringExample:The custom from address invoicefalcon@molecularapps.com i…fixstringExample:Verify the sender domain (GET /account/sending shows the …
verdictstringExample:The email to bad@example.com bounced ({"type"=>"Permanent…
Errors
Missing or unknown X-Auth-Token, or the shop uninstalled the app.
v3_required: the shop still runs the previous dashboard. paid_plan_required: API access needs a paid plan.
The resource does not exist for this shop, or no action is registered at this path.
The request failed validation. Nothing was saved.
Rate limited: cost-weighted per key (reads cost less than writes). Wait Retry-After seconds; see X-RateLimit-* headers.
Every error has the same shape: see Errors.
curl "https://app.invoicefalcon.com/api/v3/external/orders/{id}/troubleshoot" \
-H "X-Auth-Token: $INVOICE_FALCON_API_KEY"const res = await fetch("https://app.invoicefalcon.com/api/v3/external/orders/{id}/troubleshoot", {
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/v3/external/orders/{id}/troubleshoot",
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/v3/external/orders/{id}/troubleshoot")
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){
"order": {
"shopify_order_id": "gid://shopify/Order/5552001",
"order_number": "#1080",
"created_at": "2026-03-01T10:00:00Z",
"financial_status": "paid",
"fulfillment_status": "fulfilled",
"cancelled_at": null,
"email": "ann@example.com"
},
"document": {
"id": 980191022,
"type": "invoice",
"number": "INV-1",
"sent_at": "2026-11-10T09:07:40Z"
},
"diagnosis": [
{
"code": "sender_unverified",
"severity": "warning",
"message": "The custom from address invoicefalcon@molecularapps.com is not verified, so emails do not go out as that address.",
"fix": "Verify the sender domain (GET /account/sending shows the state), or clear the address in PATCH /account/sending."
},
{
"code": "automation_off",
"severity": "info",
"message": "Automatic invoices are off, so invoices go out only when someone sends them.",
"fix": "Send it with POST /documents/invoices/:id/send, or turn it on with PATCH /account/automation."
},
{
"code": "delivery_failed",
"severity": "problem",
"message": "The email to bad@example.com bounced ({\"type\"=>\"Permanent\"}).",
"fix": "Confirm the address with the customer and resend with `to`."
}
],
"verdict": "The email to bad@example.com bounced ({\"type\"=>\"Permanent\"})."
}{
"errors": [
"Invalid API key"
],
"code": "unauthorized"
}{
"errors": [
"API access requires a paid plan"
],
"code": "paid_plan_required"
}{
"errors": [
"Resource not found"
],
"code": "not_found"
}{
"errors": [
"id is missing"
]
}{
"errors": [
"Rate limit exceeded"
],
"code": "rate_limited"
}