Restock On Return

Purpose

Walks through recently approved or closed returns and restocks inventory for each returnLineItem whose physical item has been received and inspected. Adjusts the available quantity at the return's destination location using inventoryAdjustQuantities with reason restock and a referenceDocumentUri linking to the return record. Use when warehouse processing posts in a separate system from Shopify, or when manual restock has been deferred and needs a clean catch-up run.

Prerequisites

Parameters

Safety

> ⚠️ Step 2 executes inventoryAdjustQuantities mutations that immediately add units to the available count at the destination location. Restocking damaged or unsalable inventory inflates available stock and causes oversells. The default is dry_run: true — review the preview CSV to confirm each return line item is genuinely sellable before committing. By default skip_defective: true excludes DEFECTIVE returns. Each restock posts a permanent entry in Shopify's inventory activity log with reason restock.

Workflow Steps

Inputs: query: "status: updated_at:>=''" (use updated_at:>='...' only when return_status:ANY), first: 250, select id, name, status, closedAt, order { id name }, returnLineItems(first: 50) { quantity, returnReason, fulfillmentLineItem { lineItem { variant { id sku inventoryItem { id tracked } } } } }, reverseFulfillmentOrders(first: 5) { reverseDeliveries(first: 5) { deliverable { ... on ReverseDeliveryShippingDeliverable { label { ... } } } }, location { id name } }, pagination cursor

Expected output: Returns with their line items, return reasons, inventory item IDs, and destination location

Inputs: input.reason: "restock", input.name: "available", input.referenceDocumentUri: "shopify://returns/", input.changes: [{ inventoryItemId, locationId, delta: + }, ...]

Expected output: inventoryAdjustmentGroup.changes with quantityAfterChange per item; userErrors

GraphQL Operations

# returns:query — validated against api_version 2025-01
query ReturnsForRestock($query: String!, $after: String) {
  returns(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        status
        closedAt
        order { id name }
        returnLineItems(first: 50) {
          edges {
            node {
              id
              quantity
              returnReason
              returnReasonNote
              fulfillmentLineItem {
                lineItem {
                  id
                  title
                  variant {
                    id
                    sku
                    inventoryItem { id tracked }
                  }
                }
              }
            }
          }
        }
        reverseFulfillmentOrders(first: 5) {
          edges {
            node {
              id
              reverseDeliveries(first: 5) { edges { node { id } } }
            }
          }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

# inventoryAdjustQuantities:mutation — validated against api_version 2025-01
mutation RestockOnReturn($input: InventoryAdjustQuantitiesInput!) {
  inventoryAdjustQuantities(input: $input) {
    inventoryAdjustmentGroup {
      id
      reason
      referenceDocumentUri
      changes {
        name
        delta
        quantityAfterChange
        item { id sku }
        location { id name }
      }
    }
    userErrors { field message }
  }
}

Session Tracking

Claude MUST emit the following output at each stage. This is mandatory.

On start, emit:

╔══════════════════════════════════════════════╗
║  SKILL: Restock on Return                    ║
║  Store: <store domain>                       ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝

After each step, emit:

[N/TOTAL] <QUERY|MUTATION>  <OperationName>
          → Params: <brief summary of key inputs>
          → Result: <count or outcome>

If dry_run: true, prefix every mutation step with [DRY RUN] and do not execute it.

On completion, emit:

For format: human (default):

══════════════════════════════════════════════
RESTOCK ON RETURN
  Returns scanned:        <n>
  Line items eligible:    <n>
  Skipped (defective):    <n>
  Skipped (untracked):    <n>
  Units restocked:        <n>  (or "skipped — dry_run")
  Adjustment groups:      <n>
  Errors:                 <n>
  Output:                 restock_on_return_<date>.csv
══════════════════════════════════════════════

For format: json, emit:

{
  "skill": "restock-on-return",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": true,
  "outcome": {
    "returns_scanned": 0,
    "line_items_eligible": 0,
    "skipped_defective": 0,
    "skipped_untracked": 0,
    "units_restocked": 0,
    "adjustment_groups": 0,
    "errors": 0,
    "output_file": "restock_on_return_<date>.csv"
  }
}

Output Format

CSV file restock_on_return_.csv with columns:

return_id, return_name, order_name, sku, product_title, quantity_restocked, return_reason, location_name, quantity_after, inventory_item_id, status

Error Handling

Best Practices