woo-refund-and-reorder

Purpose

Process a full or line-item-level partial refund on a specified WooCommerce order, optionally restock the refunded items, and optionally create a replacement order. Includes a dry-run preview of the refund amount before any money movement occurs.

Prerequisites

• WooCommerce store with REST API enabled (WooCommerce → Settings → Advanced → REST API)
• Consumer Key and Consumer Secret with Read/Write scope
• Store accessible over HTTPS
• Payment gateway must support API refunds (most do; cash-on-delivery does not)
• Minimum WooCommerce version: 3.5.0

Parameters

Authentication

WooCommerce uses OAuth 1.0a for HTTP and Basic Auth over HTTPS.

For HTTPS stores (recommended):

Authorization: Basic base64(consumer_key:consumer_secret)

For HTTP stores (development only): Use OAuth 1.0a — include oauth_consumer_key, oauth_nonce, oauth_signature, oauth_signature_method=HMAC-SHA1, oauth_timestamp, oauth_version=1.0

Never log or output consumer_key or consumer_secret values.

See docs/AUTHENTICATION.md for full setup instructions.

Safety

Step 3 initiates a financial refund transaction. This is irreversible once the gateway processes it. Always run with dry_run: true first (the default) and confirm the refund amount and line items. Verify the order status is processing or completed before proceeding — refunding a cancelled or already-refunded order will fail.

Workflow Steps

Step 1 — Fetch the order

GET /wp-json/wc/v3/orders/{order_id}

Extract: id, number, status, total, total_tax, shipping_total, payment_method, payment_method_title, billing, line_items, tax_lines, shipping_lines, date_created

Validate:

• Order status must be processing or completed
• If status is refunded or cancelled, abort with a message
• total must be > 0

Step 2 — Compute refund amount

For refund_type == "full":

refund_amount = order.total
refund_line_items = all line_items with full quantity and subtotal

For refund_type == "partial":

refund_amount = sum of line_items[i].refund_total

Validate: refund_amount <= order.total

Step 3 — Preview or execute

If dry_run: true: emit the refund summary table and stop.

If dry_run: false and user has confirmed:

POST /wp-json/wc/v3/orders/{order_id}/refunds
  Body: {
    "amount": "<refund_amount>",
    "reason": "<reason>",
    "line_items": [ { "id": <id>, "quantity": N, "refund_total": "N.NN" } ],
    "restock_items": <restock_items>,
    "api_refund": <api_refund>
  }

Step 4 — Create replacement order (optional)

If create_replacement: true and refund succeeded:

POST /wp-json/wc/v3/orders
  Body: {
    "customer_id": <original.customer_id>,
    "billing": <original.billing>,
    "shipping": <original.shipping>,
    "line_items": <original.line_items mapped to product_id + quantity>,
    "payment_method": <original.payment_method>,
    "payment_method_title": <original.payment_method_title>,
    "customer_note": "Replacement for order #<original_number>"
  }

API Endpoints Used

GET  /wp-json/wc/v3/orders/{id}          — fetch order details
POST /wp-json/wc/v3/orders/{id}/refunds  — create the refund record
POST /wp-json/wc/v3/orders               — create replacement order (optional)

Pagination Strategy

WooCommerce REST API uses page/per_page pagination (not cursor-based).

Standard pattern:

page = 1
while True:
  response = GET /endpoint?per_page=100&page=page
  process(response)
  if len(response) < 100: break
  page += 1

Maximum per_page is 100 for most endpoints. The X-WP-Total and X-WP-TotalPages response headers report totals. Always read X-WP-TotalPages on the first request to estimate job size.

Session Tracking

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

STARTUP:

╔══════════════════════════════════════════╗
║  SKILL: woo-refund-and-reorder           ║
║  STORE: <store_url>                      ║
║  TIME:  <ISO-8601 UTC>                   ║
║  MODE:  <DRY RUN | LIVE>                 ║
╚══════════════════════════════════════════╝

PER-OPERATION (emit after each API call batch):

[N/TOTAL] <METHOD> <endpoint> → <result_count> records | params: <key>=<val>

COMPLETION (human format):

╔══════════════════════════════════════════╗
║  COMPLETE: woo-refund-and-reorder        ║
║  RECORDS PROCESSED: <n>                  ║
║  OUTPUT: stdout                          ║
╚══════════════════════════════════════════╝

COMPLETION (json format):

{
  "skill": "woo-refund-and-reorder",
  "store": "<store_url>",
  "completed_at": "<ISO-8601>",
  "records_processed": 1,
  "output_file": null,
  "dry_run": <bool>
}

Output Format

Dry-run preview (human format):

REFUND PREVIEW — Order #5821 (DRY RUN)

  Order:     #5821 — Jane Smith <[email protected]>
  Status:    processing
  Created:   2025-04-12 14:32 UTC
  Payment:   Stripe (stripe)

  Refund Type: FULL
  ─────────────────────────────────────────────────
  Item                       Qty   Unit     Subtotal
  Leather Wallet              1    $29.99    $29.99
  Canvas Tote (Blue/Large)    2    $19.99    $39.98
  ─────────────────────────────────────────────────
  Subtotal:                               $69.97
  Tax:                                     $6.30
  Shipping:                                $0.00
  TOTAL REFUND:                           $76.27
  ─────────────────────────────────────────────────
  Restock items: YES
  Gateway refund: YES (Stripe)
  Reason: Damaged in transit

Post-execution summary:

✅ Refund processed — Order #5821
  Refund ID:     4,891
  Amount:        $76.27
  Gateway:       Stripe — transaction ID txn_3PqXm2...
  Items restocked: 3 units

Error Handling

Best Practices

• Always run with dry_run: true first (the default). Confirm amount and line items before proceeding.
• For partial refunds, confirm the line_item id values from the order detail — these are different from product IDs.
• Set restock_items: true unless the items are damaged and cannot be resold.
• Add a meaningful reason — it appears as an order note visible in WooCommerce admin.
• For cash/cheque payment methods, set api_refund: false — gateway API refund will not apply.