Shopify Admin Address Correction

Purpose

Corrects a shipping address on an unfulfilled order without navigating the Shopify admin UI. This skill is useful when a customer provides a correction after placing the order — for example, a typo in the street address or a wrong ZIP code. It replaces the manual address editing flow in the Shopify admin by executing the address update directly via the Admin API. The update must be performed before the order is fulfilled; this skill will abort with an error if the order has already been fulfilled or is partially fulfilled. Once fulfillment begins, the Shopify order record cannot be updated through this skill.

Prerequisites

• Authenticated Shopify CLI session: shopify auth login --store <domain>
• API scopes: read_orders, write_orders

Parameters

Safety

⚠️ Step 2 executes orderUpdate which immediately changes the shipping address on record. If the order is already with a fulfillment partner, notify them separately — this skill updates the Shopify record only. This skill will abort with an error if displayFulfillmentStatus is not UNFULFILLED. Address changes cannot be applied to partially or fully fulfilled orders.

Workflow Steps

1. OPERATION: order — query Inputs: id: <order_id> Expected output: Order name, displayFulfillmentStatus, current shippingAddress; if displayFulfillmentStatus != "UNFULFILLED", abort with message: "Cannot update address: order has already been fulfilled."

2. OPERATION: orderUpdate — mutation Inputs: input.id: <order_id>, input.shippingAddress: <new_address object> Expected output: Updated shippingAddress on the order, userErrors

GraphQL Operations

graphqlCopy code
# order:query — validated against api_version 2025-01
query OrderForAddressCheck($id: ID!) {
  order(id: $id) {
    id
    name
    displayFulfillmentStatus
    shippingAddress {
      address1
      address2
      city
      province
      country
      zip
      phone
      firstName
      lastName
    }
  }
}

graphqlCopy code
# orderUpdate:mutation — validated against api_version 2025-01
mutation OrderUpdate($input: OrderInput!) {
  orderUpdate(input: $input) {
    order {
      id
      shippingAddress {
        address1
        address2
        city
        province
        country
        zip
        phone
      }
    }
    userErrors {
      field
      message
    }
  }
}

Session Tracking

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

On start, emit:

Copy code
╔══════════════════════════════════════════════╗
║  SKILL: address-correction                   ║
║  Store: <store domain>                       ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝

After each step, emit:

Copy code
[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):

Copy code
══════════════════════════════════════════════
OUTCOME SUMMARY
  Order:          <name>
  Address updated: yes
  Errors:          0
  Output:          none
══════════════════════════════════════════════

For format: json, emit:

jsonCopy code
{
  "skill": "address-correction",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    { "step": 1, "operation": "OrderForAddressCheck", "type": "query", "params_summary": "order_id: <id>", "result_summary": "UNFULFILLED, address confirmed", "skipped": false },
    { "step": 2, "operation": "OrderUpdate", "type": "mutation", "params_summary": "order_id: <id>, new_address: <summary>", "result_summary": "address updated", "skipped": false }
  ],
  "outcome": {
    "order_name": "<name>",
    "address_updated": true,
    "errors": 0,
    "output_file": null
  }
}

Output Format

No CSV output. The skill reports the updated address in the session completion summary. The new address is shown in the [2/2] step output.

Error Handling

Best Practices

1. Always run dry_run: true first — Step 1 shows the current address for confirmation before Step 2 commits the change.
2. Country must be the ISO 3166-1 alpha-2 code (e.g., US, CA, GB) — not the full country name.
3. This skill only updates the Shopify order record. If you use a third-party fulfillment provider, also update the address in their system.
4. For phone field, use E.164 format (e.g., +15551234567).
5. After updating, use the order-lookup-and-summary skill to confirm the address change took effect.