Failure vs Failed Delivery in Shopify: What Merchants Need to Know
Failure vs "Failed Delivery" in Shopify
If you have set a fulfillment event status to Failure and then noticed Shopify showing "Failed delivery" in the order timeline, you are not seeing a bug. You are seeing a Shopify display layer decision.
Here is what is actually happening and why it matters for your team.
The API Value vs. the Display Label
Shopify's fulfillment event API uses an enum value called FAILURE. When you (or an app) sets that status via the API, Shopify stores it correctly as FAILURE.
However, Shopify's order timeline — the UI your staff and customers see — renders that API value with the human-readable label "Failed delivery".
This is intentional. Shopify's UI team chose display labels that read naturally to non-technical users. The underlying data is unchanged.
The short version:
| What you set | What Shopify shows in the timeline |
|---|---|
FAILURE (API value) | "Failed delivery" (display label) |
This same pattern exists for other statuses too: the API value LABEL_PURCHASED may display differently than its raw enum string in some Shopify contexts.
Why This Causes Confusion
Staff training
If your operations team is told "set status to Failure" but the timeline shows "Failed delivery", they may think something went wrong — or that a different status was applied.
Support documentation
If your internal SOPs reference the API value FAILURE but screenshots show "Failed delivery", new team members get confused quickly.
Automation conditions
Some third-party automations check fulfillment event status strings. If you built a Flow trigger or a Klaviyo condition based on what you see in the UI ("Failed delivery") rather than the actual API value (FAILURE), the condition may not match correctly.
How to Train Your Support Team
Use both terms together
When writing internal documentation, use the format: Failure (FAILURE) — shows as "Failed delivery" in Shopify. This bridges the API value and the display label.
Screenshot the timeline, label the API value
If you have visual SOPs or runbooks, annotate the "Failed delivery" text in the screenshot with: API value: FAILURE.
Test your automations against the API value
Any Flow, Klaviyo, or webhook condition that checks fulfillment event status should use the FAILURE enum value, not the string "Failed delivery".
Suggested Note Templates for Failure Events
Failure events should always include a note. Without context, a "Failed delivery" entry in the order timeline tells your support team nothing actionable.
Address not found:
Failure: Carrier could not locate address. Contact customer to confirm full delivery address before reshipment.
Customer not available, no safe location:
Failure: Three delivery attempts exhausted. Package returned to sender. Awaiting customer contact.
Customs/import issue:
Failure: Held at customs — import documentation required. Customer notified via email.
Refused delivery:
Failure: Customer refused delivery at door. RMA process initiated.
Keep notes factual and include a clear next step. This reduces back-and-forth between support and operations when handling exceptions.
Summary
- The API value is
FAILURE. - Shopify's order timeline displays it as "Failed delivery".
- These refer to the same status. The data is correct.
- Train your team on both terms to avoid confusion.
- Always pair a Failure event with a note explaining what happened and what happens next.
For the complete picture on all statuses, see All 11 Shopify Fulfillment Event Statuses Explained.
To set Failure status (with a note) from Shopify, use Mark Shipping Status.
Related Articles
Status Notes Best Practices for Shopify Operations Teams
Good status notes reduce support tickets and give ops teams the context they need. Here is what makes a note useful, with templates and governance tips for teams.
Bulk Update Mixed Shipping Statuses in Shopify (Delivered + In Transit + Delayed)
Not all orders in a batch have the same status. Here is how to run bulk fulfillment updates with per-row status, date, and note control — and a QA checklist to run after.
How to Backdate Fulfillment Events in Shopify (Without Data Chaos)
When carrier confirmations arrive late or batch corrections are needed, backdating fulfillment events keeps your timeline accurate. Here is the safe way to do it.