Woo Refund And Reorder

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

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | store_url | string | yes | — | Base URL of the WooCommerce store (e.g., https://mystore.com) | | consumer_key | string | yes | — | WooCommerce REST API consumer key (ck_...) | | consumer_secret | string | yes | — | WooCommerce REST API consumer secret (cs_...) | | dry_run | bool | no | true | Preview refund amount without executing | | format | string | no | human | Output format: human or json | | order_id | int | yes | — | WooCommerce order ID to refund | | refund_type | string | no | full | full or partial | | line_items | array | no | — | For partial refunds: [{ "id": , "quantity": N, "refund_total": "N.NN" }] | | reason | string | no | Customer request | Reason for the refund (added as order note) | | restock_items | bool | no | true | Return stock quantities for refunded items | | create_replacement | bool | no | false | Create a new order copying the original's items | | api_refund | bool | no | true | Attempt refund via payment gateway API (vs manual) |

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 oauthconsumerkey, oauthnonce, oauthsignature, oauthsignaturemethod=HMAC-SHA1, oauthtimestamp, oauthversion=1.0

Never log or output consumerkey or consumersecret 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: `refundamount ", "reason": "", "lineitems": [ { "id": , "quantity": N, "refundtotal": "N.NN" } ], "restockitems": , "api_refund": }

**Step 4 — Create replacement order (optional)**

If `create_replacement: true` and refund succeeded:

POST /wp-json/wc/v3/orders Body: { "customerid": , "billing": , "shipping": , "lineitems": , "paymentmethod": , "paymentmethodtitle": , "customernote": "Replacement for order #" }

## 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) ║ ║ TIME: ║ ║ MODE: ║ ╚══════════════════════════════════════════╝

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

[N/TOTAL] → records | params: =

COMPLETION (human format):

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

COMPLETION (json format):

```json
{
  "skill": "woo-refund-and-reorder",
  "store": "",
  "completed_at": "",
  "records_processed": 1,
  "output_file": null,
  "dry_run": 
}

Output Format

Dry-run preview (human format):

REFUND PREVIEW — Order #5821 (DRY RUN)

  Order:     #5821 — Jane Smith 
  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

| Error | Cause | Resolution | |-------|-------|------------| | 401 Unauthorized | Invalid or missing credentials | Verify consumerkey and consumersecret | | 403 Forbidden | Consumer Key lacks Read/Write scope | Regenerate key with Read/Write scope | | 404 Not Found | Order ID does not exist | Confirm the order ID | | woocommerce_rest_invalid_order_status | Order is not in a refundable state | Confirm order is processing or completed | | woocommerce_rest_refund_total_invalid | Refund amount exceeds order total | Reduce refund amount | | Gateway API error | Payment gateway declined the refund | Process manually via gateway dashboard |

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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: navarroido
• Source: navarroido/Woocommerce-skill
• License: MIT

Install and usage instructions live in the source repository linked above.