Order & Returns Manager

Manage UK-compliant Shopify and WooCommerce orders via chat, including status, returns, refunds, exchanges, edits, fraud flags, lost parcels, and reports.

Hussain Khuzema@hussainpatan9

Install

openclaw skills install @hussainpatan9/order-returns-manager

Order & Returns Manager

Overview

Manage Shopify and WooCommerce orders end-to-end via WhatsApp, Telegram, or any OpenClaw channel. Check order status with live tracking, process returns and exchanges, approve refunds, restock inventory, edit orders before dispatch, flag fraud, handle lost parcels, and generate fulfilment reports — all from a single message.

UK-focused: Consumer Rights Act 2015 compliance enforced throughout. Royal Mail, DPD, Evri, DHL, and Parcelforce carrier claim links included.

Trigger Phrases

Activate this skill when the user says any of the following (or similar):

Order lookups:

"check order [number/name/email]"
"where is order [X]" / "has order [X] shipped"
"find orders for [customer name/email]"
"show today's orders" / "morning report"
"show unfulfilled orders"
"orders from the last [X] days"

Returns, refunds & exchanges:

"process a return" / "customer wants to return [order]"
"approve / deny return for [order]"
"issue refund for [order]" / "partial refund on [order]"
"customer wants to exchange [order]"
"restock items from [order]"

Fulfilment & editing:

"mark [order] as fulfilled" / "add tracking to [order]"
"cancel [order]"
"edit order [X]" / "change address on [order]" / "remove item from [order]"
"add note to order [X]"

Reports & fraud:

"returns report" / "show returns this week/month"
"unfulfilled orders report"
"flag suspicious orders" / "fraud check on [order]"

Configuration (ask on first use if not set)

Check memory for the following before running any workflow. If missing, ask the user once and store under orders_config:

text

STORE_PLATFORM              # shopify | woocommerce
SHOPIFY_STORE_HANDLE        # e.g. my-store (Shopify only)
SHOPIFY_ACCESS_TOKEN        # starts with shpat_ (Shopify only)
WC_DOMAIN                   # e.g. mystore.co.uk (WooCommerce only)
WC_CONSUMER_KEY             # ck_xxx (WooCommerce only)
WC_CONSUMER_SECRET          # cs_xxx (WooCommerce only)
SHOPIFY_API_VERSION         # Default: 2025-01
SHOPIFY_LOCATION_ID         # Fetched automatically on first inventory op
CURRENCY                    # Default: GBP
RETURN_WINDOW_DAYS          # Default: 30
AUTO_RESTOCK_ON_RETURN      # Default: true
REFUND_APPROVAL_REQUIRED    # Default: true
HIGH_VALUE_APPROVAL_FLOOR   # Default: £100 (always confirm refunds above this)
FRAUD_ALERT_THRESHOLD       # Default: £150
NOTIFY_CUSTOMER_ON_RETURN   # Default: true
RETURN_ADDRESS              # Store's full return postal address
PREFERRED_CARRIER           # Default carrier for fulfilment notes

Never log or repeat access tokens back to the user.

Fetch location ID automatically (Shopify)

On first inventory operation:

text

GET https://{store}.myshopify.com/admin/api/{version}/locations.json

If multiple active locations exist, list them and ask which to use as default. Store the chosen ID as SHOPIFY_LOCATION_ID.

Workflow A — Order Lookup

Step 1 — Identify the order

Accept: order number (#1234 or 1234), customer email, or customer name.

By order number:

text

GET https://{store}.myshopify.com/admin/api/{version}/orders.json?name=%23{number}&status=any

By customer email:

text

GET .../customers/search.json?query=email:{email}&limit=5
→ GET .../customers/{id}/orders.json?status=any&limit=10

By customer name:

text

GET .../customers/search.json?query={name}&limit=5

Multiple matches → show compact list, ask user to confirm:

text

Found 2 orders for "James":
  #1234 · James Thornton · £67.98 · 08 Apr ✅ Fulfilled
  #1198 · James Okafor   · £34.99 · 02 Apr ✅ Fulfilled
Which one?

Step 2 — Display order summary

text

📦 Order #1234 — James Thornton

Status:    Fulfilled ✅
Placed:    08 Apr 2026, 14:32
Payment:   Paid via Stripe

Items:
  · Merino Wool Scarf — Navy (×1)        £34.99
  · Ceramic Plant Pot — Terracotta (×1)  £12.99
  ──────────────────────────────────────────────
  Subtotal                               £47.98
  Shipping — Standard                     £3.99
  Total                                  £51.97

Dispatch:
  Carrier:     Royal Mail Tracked 48
  Tracking:    TT123456785GB
  Sent:        09 Apr 2026
  Live status: [fetched from carrier — see Step 3]

Customer:
  Email:    james.thornton@email.com
  Phone:    +44 7700 900123
  History:  4 orders · £234.50 lifetime · 0 prior returns

Reply: "return" · "exchange" · "refund" · "cancel" · "edit" · "add tracking" · "note" · "lost parcel"

Step 3 — Live tracking lookup

Attempt web_fetch on the carrier tracking URL. Use the carrier name stored in order.fulfillments[0].tracking_company to select the correct URL:

Carrier	Tracking URL	web_fetch reliable?
Royal Mail	https://www.royalmail.com/track-your-item#/tracking-results/{tracking_number}	⚠️ No — hash fragment is client-side JS
DPD	https://www.dpd.co.uk/apps/tracking/redirect?reference={tracking_number}	⚠️ Unreliable
Evri	https://www.evri.com/track-a-parcel/results/{tracking_number}	⚠️ Unreliable
DHL	https://www.dhl.com/gb-en/home/tracking/tracking-express.html?submit=1&tracking-id={tracking_number}	⚠️ Unreliable
Parcelforce	https://www.parcelforce.com/track-trace?trackNumber={tracking_number}	⚠️ Unreliable

Important: All major UK carrier tracking pages load status via client-side JavaScript after the initial page load. web_fetch retrieves the HTML shell only, not the rendered tracking status. Do not claim to show "live status" — instead:

Attempt web_fetch and check if any status text is parseable in the raw HTML
If parseable: show the status clearly labelled as "last fetched status"

If not parseable (most cases): show the tracking number and a direct link so the merchant can check in one tap:

text

Tracking: TT123456785GB (Royal Mail Tracked 48)
Check live: https://www.royalmail.com/track-your-item#/tracking-results/TT123456785GB

Never silently skip tracking or claim "In transit ✅" without actual data to support it.

Workflow B — Return Request

Follow every step precisely. UK law is enforced throughout.

Step 1 — Find the order (Workflow A, Step 1)

Step 2 — Eligibility check

Calculate days since delivery (not order date) for the 14-day cancellation right:

text

dispatch_date  = order.fulfillments[0].created_at  (date dispatched)
days_since_order    = today - order.created_at
days_since_dispatch = today - dispatch_date

The 14-day cancellation right runs from the delivery date. Since the exact delivery date is rarely recorded, use days_since_dispatch as the conservative estimate (errs toward customer's favour, which is legally safer for the merchant). If the merchant knows the actual delivery date, use that instead.

Check all of the following:

days_since_order vs RETURN_WINDOW_DAYS (flag if outside, but UK law overrides — see below)
Is the order fulfillment_status: fulfilled? If null/unfulfilled → route to cancel (Workflow D)
Has a return already been processed? Check order.refunds[] — if non-empty, warn and ask if this is an additional partial return
Are any line items non-returnable?
- Digital products (requires_shipping: false) → not returnable under distance selling regs
- Personalised / custom items → not returnable (flag and ask owner to confirm)
- Opened hygiene products, perishables → not returnable
- Note these exceptions in the approval summary

UK statutory minimums (always apply, regardless of store policy):

Within 14 days of delivery: customer can cancel for any reason (Consumer Contracts Regs 2013) → Full refund including standard delivery cost must be given
Within 30 days of delivery: faulty or not-as-described goods → full refund
Within 6 months of delivery: if fault is proven to have existed at sale → repair/replace/refund

Step 3 — Return reason

Parse from user message if present. If not, ask in one message:

text

Reason for return?
  1 · Changed mind
  2 · Wrong size or colour ordered
  3 · Item arrived damaged
  4 · Item not as described
  5 · Faulty / stopped working
  6 · Item not received → I'll open a lost parcel claim (Workflow F) instead

Return shipping cost responsibility (UK law):

Reasons 1–2 → customer pays return shipping
Reasons 3–5 → merchant pays (provide prepaid label or reimburse cost)
Reason 6 → exit to Workflow F — this is not a return

Step 4 — Owner approval (if REFUND_APPROVAL_REQUIRED = true)

Always require approval if refund amount > HIGH_VALUE_APPROVAL_FLOOR, regardless of config.

text

↩️ Return request — approval needed

Order:        #1234 — James Thornton
Items:        Merino Wool Scarf — Navy (×1)        £34.99
Reason:       Changed mind
Days:         12 days ✅ within {RETURN_WINDOW_DAYS}-day window
Return ship:  Customer pays (changed mind)
Refund:       £34.99 item only — original shipping (£3.99) not refunded
              [If within 14-day cancellation window: full refund incl. shipping]
Restock:      +1 Merino Wool Scarf Navy

Customer:     4 orders · 0 prior returns ✅ · low risk
UK law:       ✅ Within 14-day right to cancel — legally must accept

YES · DENY · PARTIAL [amount]

Auto-approve (skip this step) only if REFUND_APPROVAL_REQUIRED = false AND refund amount ≤ HIGH_VALUE_APPROVAL_FLOOR.

Step 5a — Approve: create return and refund

Step 1 of 3 — Create the return record (Shopify Returns API):

text

POST https://{store}.myshopify.com/admin/api/{version}/orders/{order_id}/returns.json
Content-Type: application/json
X-Shopify-Access-Token: {token}

{
  "return": {
    "refund_line_items": [
      {
        "line_item_id": {line_item_id},
        "quantity": {qty},
        "restock_type": "return",
        "location_id": {SHOPIFY_LOCATION_ID}
      }
    ],
    "note": "{return_reason}"
  }
}

This creates the return record and handles restocking for the returned line items. Save the returned return.id for reference.

Step 2 of 3 — Issue the refund (separate API call):

text

POST https://{store}.myshopify.com/admin/api/{version}/orders/{order_id}/refunds.json

{
  "refund": {
    "notify": true,
    "note": "Return approved — {reason}",
    "refund_line_items": [
      {
        "line_item_id": {line_item_id},
        "quantity": {qty},
        "restock_type": "no_restock"
      }
    ],
    "shipping": {
      "full_refund": {true_if_within_14_day_cancellation_window}
    },
    "transactions": [
      {
        "parent_id": {order.transactions[0].id},
        "amount": "{refund_amount}",
        "kind": "refund",
        "gateway": "{order.transactions[0].gateway}"
      }
    ]
  }
}

Important: set restock_type: "no_restock" in the refund body — restocking was already handled in the returns API call above. Double-restocking will inflate inventory.

Step 3 of 3 — Send return instructions to customer: (Only if NOTIFY_CUSTOMER_ON_RETURN = true)

Compose and send via Shopify email or the configured email tool:

text

Subject: Return approved — Order #{order_name}

Hi {first_name},

Your return request for order #{order_name} has been approved.

Items to return:
{list each item with qty — e.g. "· Merino Wool Scarf — Navy (×1)"}

Please send your return to:
{RETURN_ADDRESS}

{IF reason is 3, 4, or 5 — merchant pays shipping}
We've arranged a prepaid Royal Mail return label. Please see the
attachment, or visit your local Post Office and quote the reference below:
[label reference or attach label]
{ELSE}
Please use a tracked postal service and keep your proof of postage.
We recommend Royal Mail Tracked 48 (available at any Post Office).
{ENDIF}

Once we receive your return, we'll process your refund of £{refund_amount}
to your original payment method within 3–5 business days.

Any questions? Just reply to this email.

{store_name}

Confirm to owner:

text

✅ Return approved — #1234

Refund:   £34.99 issued → Stripe (James Thornton)
Restock:  +1 Merino Wool Scarf Navy at {location_name} ✅
Email:    Return instructions sent to james.thornton@email.com ✅
Note:     Added to order internally

Step 5b — Deny return

Before composing denial, run UK law check:

Condition	Block denial?
Within 14 days of delivery (any reason)	✅ Block — statutory cancellation right
Within 30 days, item faulty or not as described	✅ Block — Consumer Rights Act
Within 6 months, fault provable at time of sale	✅ Block — must offer repair/replace first
Beyond return window, item not faulty, item as described	Allow denial

If block applies:

text

⚠️ Legal alert — this denial is not safe

Reason: {specific law that applies}
Risk: chargeback (£15–25 fee) and/or Trading Standards complaint

Strongly recommended: accept the return.

APPROVE — accept and process return
OVERRIDE — deny anyway (not recommended, you accept legal risk)

If denial is legally safe: Fetch existing note first, then append (same null guard as Workflow G):

text

GET .../orders/{order_id}.json?fields=id,note
PUT .../orders/{order_id}.json
{
  "order": {
    "note": "{existing_note is null ? '' : existing_note + '\n'}[{DD MMM YYYY}] Return denied — {reason}"
  }
}

Send denial email:

text

Subject: Your return request — Order #{order_name}

Hi {first_name},

Thank you for contacting us about order #{order_name}.

Unfortunately we're unable to process this return:
{denial_reason}

{IF outside_window}
Our return window is {RETURN_WINDOW_DAYS} days from the order date.
This order was placed on {order_date}, which is outside this period.
{ENDIF}

If you think this is an error, or if there's anything else we can help
with, please reply to this email.

{store_name}

Step 5c — Partial refund (goodwill or damaged item)

Ask for the amount if not in the user's message. Partial refunds do not create a return record and do not restock inventory.

text

POST .../orders/{order_id}/refunds.json
{
  "refund": {
    "notify": true,
    "note": "Partial refund — {reason}",
    "transactions": [
      {
        "parent_id": {order.transactions[0].id},
        "amount": "{partial_amount}",
        "kind": "refund",
        "gateway": "{order.transactions[0].gateway}"
      }
    ]
  }
}

Confirm:

text

✅ Partial refund — #1234

Amount:  £{partial_amount} → {gateway} ({customer_name})
Reason:  {reason}
Note:    Added to order
Customer notified: ✅

Workflow C — Exchange (Return + Replacement)

Triggered by: "customer wants to exchange", "swap size on [order]", "different colour"

Exchanges are a two-part process: issue a return/refund for the original item, then create a new order or manually adjust the replacement.

Step 1 — Find original order (Workflow A)

Step 2 — Confirm exchange details

text

↔️ Exchange request — #1234

Original:    Merino Wool Scarf — Navy (×1)        £34.99
Exchange for: [ask user] — e.g. "same scarf in Forest Green"

Options:
  DRAFT ORDER — create a new draft order for the replacement (recommended)
  MANUAL — I'll just process the return and you'll create the new order yourself

Which approach?

Step 3a — Draft order approach (recommended)

Create a draft order for the replacement item at £0 (or at cost if different price):

text

POST .../draft_orders.json
{
  "draft_order": {
    "line_items": [
      {
        "variant_id": {replacement_variant_id},
        "quantity": {qty},
        "price": "0.00",
        "title": "{product title} — exchange for order #{original_order_name}"
      }
    ],
    "customer": { "id": {customer_id} },
    "shipping_address": {original_order.shipping_address},
    "shipping_line": {
      "custom": true,
      "title": "{PREFERRED_CARRIER} — exchange shipping",
      "price": "0.00"
    },
    "note": "Exchange — original order #{original_order_name}",
    "send_invoice": false
  }
}

Complete the draft order to create the replacement order:

text

PUT .../draft_orders/{draft_id}/complete.json

Then process the return/refund for the original item (Workflow B, Step 5a).

Confirm:

text

↔️ Exchange processed — #1234

Return:       Merino Wool Scarf — Navy refunded (£34.99)
Replacement:  Merino Wool Scarf — Forest Green dispatched
New order:    #{new_order_name}
Customer:     Exchange confirmation sent ✅

Step 3b — Manual approach

Just process the return (Workflow B) and note to owner:

text

↩️ Return processed — #1234

Refund: £34.99 → {customer_name}
Next step: create a new order manually for the replacement item.
Draft orders → New order in your Shopify admin.

Workflow D — Cancel an Order

Triggered by: "cancel order [X]", "customer wants to cancel"

Step 1 — Check cancellability

text

GET .../orders/{order_id}.json?fields=id,name,status,fulfillment_status,financial_status,total_price,line_items,transactions,customer,email

fulfillment_status: fulfilled → cannot cancel via API → route to Workflow B (return)
status: cancelled → already cancelled → inform user (note: use status, not financial_status, to check cancellation)
fulfillment_status: null (unfulfilled) → proceed

Step 2 — Confirm

text

⚠️ Cancel order #1234?

Customer:  James Thornton · james.thornton@email.com
Total:     £51.97
Status:    Unfulfilled ✅ — can be cancelled
Refund:    £51.97 → original payment method (Stripe)
Restock:   +2 items → inventory

Reply YES to cancel and refund in full.
Reply HOLD to cancel without refund (non-standard — confirm reason first).

Step 3 — Cancel (two API calls)

Call 1 — Cancel the order:

text

POST .../orders/{order_id}/cancel.json
{
  "reason": "customer",
  "email": true
}

Note: the cancel endpoint does NOT process refunds. It only sets order status to cancelled.

Call 2 — Issue the refund separately:

text

POST .../orders/{order_id}/refunds.json
{
  "refund": {
    "notify": true,
    "note": "Order cancelled at customer request",
    "refund_line_items": [
      {
        "line_item_id": {id},
        "quantity": {qty},
        "restock_type": "cancel"
      }
    ],
    "shipping": { "full_refund": true },
    "transactions": [
      {
        "parent_id": {order.transactions[0].id},
        "amount": "{order.total_price}",
        "kind": "refund",
        "gateway": "{order.transactions[0].gateway}"
      }
    ]
  }
}

Confirm:

text

✅ Order #1234 cancelled

Refund:   £51.97 → Stripe (James Thornton)
Restock:  2 items returned to inventory ✅
Email:    Cancellation confirmation sent ✅

Workflow E — Fulfil an Order

Triggered by: "mark [order] as fulfilled", "add tracking to [order]", "dispatch [order]"

Step 1 — Get fulfillment order ID

text

GET .../orders/{order_id}/fulfillment_orders.json

Use the fulfillment_order.id (not the order ID) in the fulfilment creation call. Only fulfil line items where fulfillment_order.status is open.

Step 2 — Ask for tracking (single message)

Carrier: Royal Mail / DPD / Evri / DHL / Parcelforce / Other (specify)
Tracking number

Step 3 — Create fulfilment

text

POST .../fulfillments.json
{
  "fulfillment": {
    "line_items_by_fulfillment_order": [
      {
        "fulfillment_order_id": {fulfillment_order_id},
        "fulfillment_order_line_items": [
          { "id": {fulfillment_order_line_item_id}, "quantity": {qty} }
        ]
      }
    ],
    "tracking_info": {
      "number": "{tracking_number}",
      "company": "{carrier_name}",
      "url": "{carrier_tracking_url_with_number}"
    },
    "notify_customer": true
  }
}

Note: use the top-level /fulfillments.json endpoint, not the order-scoped one. The order-scoped /orders/{id}/fulfillments.json is deprecated as of API version 2022-07.

Confirm:

text

✅ Order #1234 fulfilled

Carrier:   Royal Mail Tracked 48
Tracking:  TT123456785GB
Items:     Merino Wool Scarf — Navy (×1), Ceramic Plant Pot — Terracotta (×1)
Customer:  Dispatch notification sent ✅

Workflow F — Edit an Order

Triggered by: "edit order [X]", "change address on [order]", "remove item from [order]", "add item to [order]"

Order editing is only available on unfulfilled orders.

Important: two different edit paths

Shipping address changes → use REST API (simple, always works) Line item changes (add/remove items) → Shopify Order Editing API is GraphQL-only. The REST API has no endpoint for editing line items on existing orders. If the user needs line item edits, advise them to use Shopify Admin directly, or use the exchange workflow (Workflow C) to cancel + recreate.

Change shipping address (REST)

text

PUT https://{store}.myshopify.com/admin/api/{version}/orders/{order_id}.json
{
  "order": {
    "shipping_address": {
      "first_name": "{first_name}",
      "last_name": "{last_name}",
      "address1": "{address1}",
      "address2": "{address2_or_empty_string}",
      "city": "{city}",
      "province": "{county_or_empty_string}",
      "zip": "{postcode}",
      "country": "United Kingdom",
      "country_code": "GB",
      "phone": "{phone_or_empty_string}"
    }
  }
}

Always confirm before updating:

text

✏️ Address update — #1234

Current:  James Thornton · 12 Old Street · London · E1 1AA
Updated:  James Thornton · 12 New Street · Bristol · BS1 2AB

Confirm? YES / cancel

Line item edits (add/remove products)

Shopify's line item editing requires the GraphQL Admin API (orderEditBegin, orderEditAddLineItem, orderEditRemoveLineItem, orderEditCommit mutations). This is beyond the scope of this skill's REST-based implementation.

When the user asks to add or remove items from an existing order, respond:

text

⚠️ Line item edits require Shopify's GraphQL API which this skill doesn't
currently support via REST.

Options:
  1. Cancel this order (Workflow D) and ask the customer to re-order
  2. Use the Exchange workflow (Workflow C) to handle a product swap
  3. Edit line items directly in Shopify Admin:
     https://{store}.myshopify.com/admin/orders/{order_id}

Workflow G — Add Note to Order

Triggered by: "add note to order [X]", "note on [order]"

Always fetch the existing note first to avoid overwriting:

text

GET .../orders/{order_id}.json?fields=id,note

Then append with a null guard:

text

PUT .../orders/{order_id}.json
{
  "order": {
    "note": "{existing_note is null ? '' : existing_note + '\n'}[{DD MMM YYYY}] {new_note}"
  }
}

If order.note is null or empty string, the new note becomes the full value with no leading newline. If order.note has content, append with a newline separator.

Confirm:

text

📝 Note added — #1234
"[10 Apr 2026] {note_text}"

Workflow H — Fraud Detection

Run automatically on new orders above FRAUD_ALERT_THRESHOLD, or on demand.

Step 1 — Fetch order with risk assessment

Explicitly request the risks field — it is not included in default order responses:

text

GET .../orders/{order_id}.json?fields=id,name,email,total_price,financial_status,fulfillment_status,billing_address,shipping_address,customer,tags,note,browser_ip,risks,transactions,line_items,fulfillments

Fields to check: order.risks[], order.financial_status, order.browser_ip, order.billing_address, order.shipping_address, order.email, order.customer.orders_count, order.tags.

Step 2 — Score signals

Signal	Risk
Shipping to freight forwarder postcode	🔴 High
Disposable/temporary email domain	🔴 High
Multiple orders same day, different payment methods, same shipping address	🔴 High
Shopify risk level = HIGH	🔴 High
Billing address ≠ shipping address	🟡 Medium
First order, value above threshold	🟡 Medium
Express shipping on high-value order	🟡 Medium
Shopify risk level = MEDIUM	🟡 Medium
Phone number missing	🟢 Low
Order placed 01:00–05:00 UK time	🟢 Low

UK freight forwarder postcodes (common): E1W, IG11, UB3, SL3, EN3, RM9, UB8. Disposable email domains: mailinator.com, guerrillamail.com, tempmail.com, throwam.com, yopmail.com, sharklasers.com (extend list in memory as you encounter more).

Overall risk score:

Any 🔴 signal = HIGH
2+ 🟡 signals and no 🔴 = MEDIUM
Only 🟢 signals = LOW

Step 3 — Action by risk level

HIGH:

text

🚨 Fraud alert — Order #{order_name}

Risk:      HIGH — recommend holding before dispatch
Value:     £{total} (above £{threshold} threshold)
Customer:  {new/returning} — {order_count} previous orders

Signals:
  🔴 {signal}
  🟡 {signal}
  🟢 {signal}

Shopify risk: {LOW/MEDIUM/HIGH}

HOLD · CANCEL · APPROVE

MEDIUM → notify owner but don't block:

text

⚠️ Order #{order_name} — moderate risk signals

{signals list}

REVIEW before fulfilling? YES / APPROVE to proceed

LOW → no action, process normally.

Step 4 — HOLD action

First fetch existing tags to avoid overwriting them:

text

GET .../orders/{order_id}.json?fields=id,tags,note

Then append the fraud-review tag and note:

text

PUT .../orders/{order_id}.json
{
  "order": {
    "tags": "{existing_tags}, fraud-review",
    "note": "{existing_note}\n[{date}] Held for fraud review — {signals summary}"
  }
}

If existing_tags is empty, use "tags": "fraud-review" only (no leading comma). If existing_note is null, use "note": "[{date}] Held for fraud review — {signals summary}" only.

Confirm: 🔒 Order #{name} held — tagged "fraud-review". Will not appear in standard fulfilment queue.

Workflow I — Lost Parcel Claim

Triggered by: "order not received", "customer hasn't received [order]", "missing parcel"

This is NOT a return. No item is coming back. Handle separately.

Step 1 — Verify tracking status (Workflow A, Step 3)

Step 2 — Assess situation

Tracking status	Assessment	Action
Shows delivered	Possible misdelivery	Ask customer to check neighbours, safe place, building reception
In transit, within expected window	Early	Ask customer to wait — share tracking URL
In transit, 3–5 days overdue	Delayed	Raise with carrier, give 2 more days before escalating
No movement for 7+ days	Likely lost	Present resolution options
No tracking at all	Untracked order	Resolution options immediately

Step 3 — Resolution options

text

📦 Possible lost parcel — Order #1234

Dispatched:   06 Apr via Royal Mail Tracked 48
Tracking:     TT123456785GB
Last scan:    07 Apr, London MC — no movement (4 days)
Expected:     08 Apr (2 days overdue)
Value:        £34.99

UK law: merchant bears risk of non-delivery — customer entitled to full refund
if goods not delivered in agreed or reasonable timeframe.

RESHIP  — send replacement now (no inventory adjustment needed)
REFUND  — full refund incl. original shipping (total: £38.98)
WAIT    — message customer, allow 2 more working days before escalating

Carrier claim links (for your records):
  Royal Mail: https://www.royalmail.com/help/claims (claim after 10 working days)
  DPD:        https://www.dpd.co.uk/content/products_services/claims.jsp
  Evri:       https://www.evri.com/help/claim-for-a-parcel
  DHL:        https://www.dhl.com/gb-en/home/our-divisions/parcel/customer-service/submit-a-claim.html
  Parcelforce: https://www.parcelforce.com/help-and-advice/sending/compensation-claims

Workflow J — Daily Orders Report

Triggered by: "morning report", "show today's orders", "orders summary", or heartbeat.

text

GET .../orders.json?status=any&created_at_min={today_start_iso8601}&limit=250

Also fetch orders older than 1 day that are still unfulfilled:

text

GET .../orders.json?fulfillment_status=unfulfilled&created_at_max={yesterday_start_iso8601}&limit=50

text

📊 Orders — 10 Apr 2026

Today:          12 orders · £847.50 revenue · £70.63 avg
Fulfilled:       7 ✅ · Unfulfilled: 4 ⏳ · Cancelled: 1 ❌

Action needed:
  ⚠️ #1267 · Sarah Chen   · £124.00 · 2 days unfulfilled
  ⏳ #1271 · Mike Patel   · £67.99  · placed today
  ⏳ #1272 · Anna Brooks  · £34.99  · placed today
  ⏳ #1274 · Tom Wright   · £89.00  · placed today

Returns awaiting your decision:  1
Fraud holds:                      1 (order #1265 — tagged fraud-review)
High-value orders (>£{FRAUD_ALERT_THRESHOLD}): 2

Reply "fulfil #[order]" to dispatch, or "returns" for the returns queue.

Workflow K — Returns Report

Triggered by: "returns report", "show returns this week/month"

Fetch refunded orders AND filter out cancellations:

text

GET .../orders.json?financial_status=refunded&updated_at_min={period_start_iso8601}&limit=250

Filter: exclude orders where order.cancel_reason is non-null (those are cancellations, not returns).

Important — return reason data: Shopify's API does not store return reasons as a structured field. Reasons only exist if they were recorded in order notes or the common_return_reasons memory map (updated each time Workflow B runs). Pull reason breakdown from common_return_reasons memory. If no memory data exists yet, omit the "by reason" breakdown and note: "Reason tracking begins after your first processed return via this skill."

text

↩️ Returns — April 2026 (1–10 Apr)

Total returns:    8 · £423.50 refunded
Return rate:      6.2% of 129 orders

By reason:
  Changed mind:       4    £198.00   50%
  Wrong size/colour:  2    £134.50   25%
  Arrived damaged:    1     £67.99   13%
  Not as described:   1     £23.01   13%

Most returned products:
  1. Merino Wool Scarf — Navy         3 returns  ⚠️  18% return rate
  2. Leather Bifold Wallet — Brown    2 returns       8% return rate

⚠️ Merino Wool Scarf — Navy has an 18% return rate.
   Top reason: "wrong size" (×2). Consider adding a size guide or more
   detailed measurements to the product listing.

Processing speed:   avg 1.4 days from request to refund
Restocked:          7 of 8 items
Outstanding refunds: 0

UK Consumer Law Reference

Enforce throughout. Never advise actions that violate these:

Situation	Customer right	Time limit	Merchant obligation
Cancel any distance sale	Full refund incl. standard shipping	Within 14 days of delivery	Refund within 14 days of receiving goods back
Faulty or not as described	Full refund	Within 30 days of delivery	Cannot refuse, cannot charge restocking fee
Fault at time of sale	Repair or replacement; if fails, refund	Within 6 months	One repair/replacement attempt then must refund
Item not delivered	Full refund	Reasonable timeframe (usually 30 days)	Merchant bears delivery risk
Goods not matching description	Full refund	No time limit	No restocking fee

Sources: Consumer Rights Act 2015, Consumer Contracts (Information, Cancellation and Additional Charges) Regulations 2013.

Key practical notes:

Merchants cannot charge a restocking fee on any return within statutory rights
The 14-day cancellation right applies from the date of delivery, not the order date
"Not as described" applies if listing photos or text materially misled the buyer
Chargeback cost (£15–25 + potential account risk) nearly always exceeds refund cost

Error Handling

HTTP Error	Common cause	Action
401 Unauthorized	Invalid/expired token	Ask user to regenerate in Shopify Admin → Apps
403 Forbidden	Missing API scope	Name the exact missing scope from the required list
422 — already refunded	Duplicate refund attempt	Fetch and display existing refund details
422 — amount exceeds order total	Refund amount too large	Ask user for the correct amount
422 — order not editable	Order is fulfilled or cancelled	Inform user, suggest alternative action
404 Order not found	Wrong order number	Suggest searching by customer email instead
429 Too Many Requests	Rate limit hit	Auto-retry after 2 seconds, up to 3 attempts
503 Service Unavailable	Shopify outage	Wait 30 seconds, retry once, then report

Required Shopify API scopes for this skill:

read_orders and write_orders
read_fulfillments and write_fulfillments
read_customers
read_inventory and write_inventory
read_draft_orders and write_draft_orders (for exchange workflow)

WooCommerce Support

When STORE_PLATFORM = woocommerce:

Base URL: https://{WC_DOMAIN}/wp-json/wc/v3 Auth header: Authorization: Basic {base64(WC_CONSUMER_KEY:WC_CONSUMER_SECRET)}

Key endpoints and request bodies

Get order:

text

GET /orders/{id}

List orders:

text

GET /orders?status={status}&per_page=50&page=1

Update order status:

text

PUT /orders/{id}
{ "status": "completed" }

Create refund:

text

POST /orders/{id}/refunds
{
  "amount": "{refund_amount}",
  "reason": "{reason}",
  "line_items": [
    {
      "id": {order_line_item_id},
      "quantity": {qty},
      "refund_total": "{line_item_refund_amount}",
      "restock_items": true
    }
  ],
  "api_refund": true
}

Update product stock:

text

PUT /products/{product_id}
{ "stock_quantity": {new_qty} }

For variable products (with variants):

text

PUT /products/{product_id}/variations/{variation_id}
{ "stock_quantity": {new_qty} }

WooCommerce status map:

WooCommerce status	Display
pending	Unpaid ⏸️
processing	Unfulfilled ⏳
on-hold	On hold ⏸️
completed	Fulfilled ✅
cancelled	Cancelled ❌
refunded	Refunded ↩️
failed	Payment failed ❌

Memory Instructions

After each interaction, update memory with:

preferred_approval_words: the words this owner uses to approve (e.g. "yes", "go", "do it", "approved") — learn from pattern so the skill recognises their shorthand
preferred_denial_words: same for denials
RETURN_ADDRESS: store once, use in every return email without asking again
SHOPIFY_LOCATION_ID: store once, avoid re-fetching every session
PREFERRED_CARRIER: the carrier this merchant most often uses — pre-fill in fulfilment prompts
FRAUD_THRESHOLD_ADJUSTED: if owner ever says "change my fraud threshold to £X", update and store
common_return_reasons: running tally of return reasons for monthly reports — store as {reason: count} map
freight_forwarder_postcodes_seen: any new freight forwarder postcodes the owner flags — append to detection list

Tone & Communication

✅ fulfilled · ⏳ pending · ❌ cancelled · ↩️ return · ↔️ exchange · 🚨 fraud · 📊 report · ⚠️ warning · 📝 note · 🔒 hold
Dates always DD MMM YYYY (e.g. 08 Apr 2026) — never MM/DD/YYYY or ISO format shown to user
Currency always £ GBP — never USD or unadorned numbers
For fraud: present signals factually, no drama — owner makes the call
For refunds above HIGH_VALUE_APPROVAL_FLOOR: always confirm with owner even if REFUND_APPROVAL_REQUIRED = false
For UK law blocks on denials: firm but not preachy — one clear warning, then respect the owner's decision
For partial refunds on damaged items: acknowledge it's goodwill and note UK law supports the claim
Keep action prompts short: "YES · DENY · PARTIAL" — not paragraphs
If the owner is clearly busy (short messages, quick replies), be more concise and skip explanatory text