Skip to content

Troubleshoot order

GET/orders/{id}/troubleshoot

Costs 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

  • idstringRequired

    A Shopify id (gid://shopify/Order/123 or 123) or the order number as the store shows it ("#1001" or "1001").

Returns

  • orderobject
    Show 7 child attributesHide child attributes
    • shopify_order_idstring
      Example: gid://shopify/Order/5552001
    • order_numberstring
      Example: #1080
    • created_atstring
      Example: 2026-03-01T10:00:00Z
    • financial_statusstring
      Example: paid
    • fulfillment_statusstring
      Example: fulfilled
    • cancelled_atstring, nullable
    • emailstring
      Example: ann@example.com
  • documentobject
    Show 4 child attributesHide child attributes
    • idinteger
      Example: 980191022
    • typestring
      Example: invoice
    • numberstring
      Example: INV-1
    • sent_atstring
      Example: 2026-11-10T09:07:40Z
  • diagnosisarray of objects
    Show 4 child attributesHide child attributes
    • codestring
      Example: sender_unverified
    • severitystring
      Example: warning
    • messagestring
      Example: The custom from address invoicefalcon@molecularapps.com i…
    • fixstring
      Example: Verify the sender domain (GET /account/sending shows the …
  • verdictstring
    Example: The email to bad@example.com bounced ({"type"=>"Permanent…

Errors

401

Missing or unknown X-Auth-Token, or the shop uninstalled the app.

403

v3_required: the shop still runs the previous dashboard. paid_plan_required: API access needs a paid plan.

404

The resource does not exist for this shop, or no action is registered at this path.

422

The request failed validation. Nothing was saved.

429

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.

GET/orders/{id}/troubleshoot
curl "https://app.invoicefalcon.com/api/v3/external/orders/{id}/troubleshoot" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY"
Response
{
  "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\"})."
}