Shopify Flow Integration

ReturnShield AI connects with Shopify Flow so you can automate responses to return intelligence events. When a high-risk order is placed, a return spike is detected, or a customer becomes a Serial Returner, Flow can automatically tag orders, notify your team, hold fulfillment, or update customer records — without manual monitoring.

Shopify Flow is available on the Shopify, Advanced, and Plus plans. ReturnShield Flow triggers are available on the Growth and Scale plans.

Setting Up the Integration

ReturnShield AI's triggers and actions appear in Shopify Flow automatically once the app is installed. No additional configuration steps are required.

To create a workflow:

1. In your Shopify admin, go to Apps → Flow
2. Click "Create workflow"
3. Click "Select trigger" and search for "ReturnShield"
4. Choose a trigger, add conditions, and build your action sequence

Available Triggers

Trigger 1: High-Risk Order Placed

Fires when an order is placed by a customer whose current ReturnShield risk score exceeds your configured threshold.

When it fires: At order creation. The customer's risk score is checked at the moment the order is placed.

Configuration options:

• Risk score threshold (default: 70 — corresponds roughly to the At Risk/Serial Returner boundary)
• Segment filter: trigger only for Serial Returners, only for At Risk, or both

Payload fields:

| Field | Type | Example value | |---|---|---| | order.id | string | gid://shopify/Order/12345678 | | order.name | string | #1023 | | order.totalPrice | string | 89.95 | | customer.id | string | gid://shopify/Customer/87654321 | | customer.email | string | buyer@example.com | | returnshield.riskScore | integer | 82 | | returnshield.segment | string | serial_returner | | returnshield.returnRate | string | 0.47 | | returnshield.totalReturns | integer | 9 |

Gotcha: New customers with fewer than 3 orders do not have a risk score. These customers default to the Standard segment and will not trigger a High-Risk Order Placed trigger regardless of threshold.

Trigger 2: Return Spike Detected

Fires when a product's return rate exceeds its category benchmark by more than the configured spike multiplier.

When it fires: Nightly during the return analysis run, when a product crosses the threshold for the first time in the current window.

Configuration options:

• Spike multiplier threshold (default: 1.5x)
• Minimum order count (default: 20 — prevents noise from low-volume products)
• Observation window (default: 14 days)

Payload fields:

| Field | Type | Example value | |---|---|---| | product.id | string | gid://shopify/Product/11223344 | | product.title | string | Westfield Oxford Shirt | | product.handle | string | westfield-oxford-shirt | | returnshield.currentReturnRate | string | 0.28 | | returnshield.benchmarkReturnRate | string | 0.17 | | returnshield.spikeMultiplier | string | 1.65 | | returnshield.returnsCount | integer | 31 | | returnshield.topReturnReason | string | Not as described |

Common use: Alert your merchandise team when a product starts spiking so they can investigate the listing before more orders ship. A spike alert on a new product launch is almost always a photo or description issue.

Trigger 3: Serial Returner Identified

Fires when a customer's risk score and return rate first cross the Serial Returner threshold. This is a one-time trigger per customer per classification cycle — it does not fire on every subsequent order from that customer.

When it fires: After a return is processed and the customer's recalculated score crosses the threshold.

Payload fields:

| Field | Type | Example value | |---|---|---| | customer.id | string | gid://shopify/Customer/87654321 | | customer.email | string | buyer@example.com | | customer.firstName | string | Maria | | customer.lastName | string | Kowalska | | returnshield.riskScore | integer | 91 | | returnshield.returnRate | string | 0.53 | | returnshield.totalReturns | integer | 11 | | returnshield.totalOrders | integer | 21 | | returnshield.classifiedAt | string | ISO 8601 timestamp |

Trigger 4: Product Risk Threshold Exceeded

Fires when a product's risk score crosses a threshold you set. Unlike the Return Spike trigger (which compares against an external benchmark), this trigger uses the 0–100 internal risk score.

When it fires: During the nightly risk recalculation, when a product's score rises above the threshold.

Configuration options:

• Risk score threshold (default: 70)
• Fire once per product per 30-day window (prevents repeated triggers during sustained high risk)

Payload fields:

| Field | Type | Example value | |---|---|---| | product.id | string | gid://shopify/Product/11223344 | | product.title | string | Westfield Oxford Shirt | | returnshield.newRiskScore | integer | 74 | | returnshield.previousRiskScore | integer | 61 | | returnshield.returnRate | string | 0.22 | | returnshield.topReturnReason | string | Sizing | | returnshield.pendingFixes | integer | 3 |

Available Actions

Action 1: Add Order Tag

Adds one or more tags to a Shopify order. Tags are visible in the Shopify orders list and can be filtered on.

Payload: Standard Shopify "Add tag" action — select the tag value in the Flow builder.

Commonly used tags:

| Tag | Purpose | |---|---| | review-before-ship | Hold the order for warehouse team review before fulfillment | | high-risk-return | Flag for customer service awareness if the order contacts support | | bracketing-suspected | Multiple variants ordered — warehouse should check before shipping | | serial-returner-order | Customer is in the Serial Returner tier | | at-risk-customer | Customer is in the At Risk tier |

Tags do not affect the order workflow on their own — they are informational flags. Pair them with fulfillment holds or internal notifications to create actionable workflows.

Action 2: Update Customer Metafield

Writes a value to a Shopify customer metafield. ReturnShield uses this action to keep customer segment data current in Shopify so email platforms can read it.

Metafield written: returnshield.risk_tier (namespace: returnshield, key: risk_tier)

Values: champion, standard, at_risk, serial_returner

This action is used internally by ReturnShield to maintain the metafield. You can also trigger it via Flow to write custom values to other namespaces based on return events.

Complete Workflow Examples

Workflow 1: Hold Serial Returner Orders Before Shipping

Goal: Prevent an order from a Serial Returner from shipping until a fulfillment team member reviews it.

Steps:

1. Trigger: High-Risk Order Placed (risk score > 75, segment: serial_returner)
2. Condition: Order total > $50 (skip holds on low-value orders — processing cost is not worth it)
3. Action: Add order tag → review-before-ship
4. Action: Send internal email to fulfillment@yourstore.com with message: "Order {{order.name}} from {{customer.email}} (ReturnShield risk score: {{returnshield.riskScore}}) is flagged for review before shipping."

Expected result: Your fulfillment team sees the review-before-ship tag when picking orders. For a store processing 300 orders/day, this typically catches 10–20 high-risk orders per week that would otherwise ship without review.

Tip: If your fulfillment software supports tag-based hold rules, combine this tag with a shipping hold rule to prevent accidental fulfillment while the order is under review.

Workflow 2: Return Spike Alert to Merchandise Team

Goal: Alert your buying or product team immediately when a product starts spiking in returns so they can review the listing before more orders ship.

Steps:

1. Trigger: Return Spike Detected (1.5x benchmark, 20-order minimum)
2. Condition: Product is in the "New Arrivals" collection (more urgent — recently launched products with no fix history)
3. Action: Send email to merch@yourstore.com with subject: "Return spike: {{product.title}}" and body including current return rate, benchmark, and top reason
4. Action: Add product tag under-review in Shopify (your team uses this as a visual flag in the product admin)

Optional extension: Add a Slack notification using a Shopify Flow webhook connector to post the alert in your #merchandising Slack channel.

Workflow 3: At Risk Customer — Proactive Sizing Email

Goal: Send At Risk customers a sizing guide email immediately after their next purchase, before a potential return is initiated.

Steps:

1. Trigger: High-Risk Order Placed (risk score 55–75, segment: at_risk)
2. Condition: Order contains a product from the "Apparel" collection
3. Action: Send email via your Klaviyo or Omnisend integration: sizing guide template, personalized with order line items

Note: This workflow requires your email platform to support Shopify Flow webhook triggers or have a Shopify customer event listener. Klaviyo natively supports Shopify Flow actions via the Klaviyo Flow app.

Workflow 4: New Serial Returner — Customer Service Alert

Goal: Notify your customer service team when a customer is newly classified as a Serial Returner so agents are aware on the customer's next contact.

Steps:

1. Trigger: Serial Returner Identified
2. Action: Add customer tag serial-returner in Shopify (visible in customer contact view)
3. Action: Update Customer Metafield → returnshield.risk_tier = serial_returner
4. Action: Send internal Slack notification (via webhook connector): "New serial returner identified: {{customer.email}} — {{returnshield.totalReturns}} returns out of {{returnshield.totalOrders}} orders."

Why this works: Your support agents see the serial-returner tag in the Shopify customer admin when the customer contacts support. Instead of processing a 12th return without context, the agent can have an informed conversation about fit guidance or alternative products.

Workflow 5: Bracketing Detection — Fulfillment Hold

Goal: Hold bracketed orders (multiple sizes of the same product) for warehouse review.

Prerequisite: ReturnShield's bracketing detection is enabled and the customer is At Risk or Serial Returner.

Steps:

1. Trigger: High-Risk Order Placed (include at_risk and serial_returner segments)
2. Condition: Check order line items for multiple variants of the same product — use Flow's "order line item quantity" condition with a count check
3. Action: Add order tag → bracketing-suspected
4. Action: Add order tag → review-before-ship
5. Action: Send email to fulfillment team with order details

Alternative approach: Configure this as a Shopify Flow trigger on order creation (not ReturnShield-triggered) with a condition checking for 3+ variants of the same product — this catches all bracketed orders regardless of customer segment.

Workflow 6: Product Risk Score Threshold — Auto-Queue Review Task

Goal: Create a Trello card or Asana task when a product's risk score crosses 70, so your content team knows to review the listing.

Steps:

1. Trigger: Product Risk Threshold Exceeded (score > 70)
2. Condition: Product has been live for more than 14 days (new products may spike briefly)
3. Action: Send webhook to your project management tool (Trello, Asana, Monday.com — use the webhook action in Flow) with product title and pending fix count
4. Action: Optional — send internal email to content team lead

Testing Workflows

Before activating a workflow for live orders:

1. Open the workflow in Shopify Flow
2. Click "Run test" (available for most trigger types)
3. Flow generates sample data matching the trigger's payload schema
4. Verify each condition and action evaluates correctly against the test data
5. Check the Run history tab after the test to see the full execution trace

For the High-Risk Order Placed trigger: Use a test order with a customer who has a known risk score. You can check a customer's current risk score in ReturnShield before placing the test order to ensure the threshold will be met.

For the Return Spike trigger: Spikes are calculated nightly, so real-time testing is not possible. Use the "Run test" feature with the sample payload to verify your action sequence.

Debugging Workflows

If a workflow is not firing as expected:

1. In Shopify admin → Apps → Flow, open the workflow and check the Run history tab
2. Find the most recent run and expand it — the trace shows each step with a pass/fail indicator and the reason
3. Common issues:
   • Trigger not fired: The event occurred but did not meet the trigger's configuration criteria (e.g., risk score threshold was 80 but the customer scored 75)
   • Condition failed: The condition evaluated to false (e.g., the order total was below the minimum)
   • Action failed: An action failed to execute — check for permission issues or API errors in the action step

Workflow is Active but not firing: Verify the workflow status shows "Active" (not "Draft" or "Paused"). A workflow accidentally paused during editing will not receive triggers.

Next Steps

• Customer Segments — understand how customers are classified before building segment-based flows
• Configuration — set risk score thresholds and alert settings
• Troubleshooting — diagnose why triggers are not firing