Skip to content
woo-refund-and-reorder logo

Woo Refund And Reorder

woo-refund-and-reorder

Process a full or partial refund on a WooCommerce order and optionally create a replacement order for the customer.

SKILL.md

Full skill instructions

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

ParameterTypeRequiredDefaultDescription
store_urlstringyes—Base URL of the WooCommerce store (e.g., https://mystore.com)
consumer_keystringyes—WooCommerce REST API consumer key (ck_...)
consumer_secretstringyes—WooCommerce REST API consumer secret (cs_...)
dry_runboolnotruePreview refund amount without executing
formatstringnohumanOutput format: human or json
order_idintyes—WooCommerce order ID to refund
refund_typestringnofullfull or partial
line_itemsarrayno—For partial refunds: [{ "id": <line_item_id>, "quantity": N, "refund_total": "N.NN" }]
reasonstringnoCustomer requestReason for the refund (added as order note)
restock_itemsboolnotrueReturn stock quantities for refunded items
create_replacementboolnofalseCreate a new order copying the original's items
api_refundboolnotrueAttempt 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 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

ErrorCauseResolution
401 UnauthorizedInvalid or missing credentialsVerify consumer_key and consumer_secret
403 ForbiddenConsumer Key lacks Read/​Write scopeRegenerate key with Read/​Write scope
404 Not FoundOrder ID does not existConfirm the order ID
woocommerce_rest_invalid_order_statusOrder is not in a refundable stateConfirm order is processing or completed
woocommerce_rest_refund_total_invalidRefund amount exceeds order totalReduce refund amount
Gateway API errorPayment gateway declined the refundProcess 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.

More skills from navarroido

woo-cancel-and-restock logo
navarroido/Woocommerce-skill

woo-cancel-and-restock

Cancel one or many WooCommerce orders and restore stock quantities for all line items with dry-run preview.

7 0
View
woo-loyalty-segment-export logo
navarroido/Woocommerce-skill

woo-loyalty-segment-export

Read-only: Export customers meeting spend or order-count thresholds for loyalty program enrollment.

7 0
View
woo-order-status-bulk-update logo
navarroido/Woocommerce-skill

woo-order-status-bulk-update

Move a filtered set of orders (by date, current status, or payment method) to a new status with dry-run preview.

7 0
View
woo-variant-attribute-normalizer logo
navarroido/Woocommerce-skill

woo-variant-attribute-normalizer

Read-only: Find product variations where attribute values are inconsistently cased or spelled, and export a normalization report.

7 0
View
woo-product-tag-bulk-update logo
navarroido/Woocommerce-skill

woo-product-tag-bulk-update

Add or remove tags from a filtered set of products (by category, price range, or stock status) with dry-run preview.

7 0
View
woo-low-stock-restock-alert logo
navarroido/Woocommerce-skill

woo-low-stock-restock-alert

Read-only: Query products below a configurable stock threshold and export a prioritized reorder sheet grouped by category.

7 0
View
woo-product-data-completeness-score logo
navarroido/Woocommerce-skill

woo-product-data-completeness-score

Read-only: Score each product against a required fields checklist (images, description, weight, SKU, attributes) and export a completeness gap report.

7 0
View
woo-fulfillment-status-digest logo
navarroido/Woocommerce-skill

woo-fulfillment-status-digest

Read-only: Aggregate order counts by status and flag orders overdue for processing based on a configurable SLA age threshold.

7 0
View
woo-customer-spend-tier-tagger logo
navarroido/Woocommerce-skill

woo-customer-spend-tier-tagger

Segment customers into Bronze, Silver, and Gold tiers based on lifetime total_spent and write the tier as a customer meta field.

7 0
View
woo-bulk-order-notes logo
navarroido/Woocommerce-skill

woo-bulk-order-notes

Append a private or customer-visible note to multiple orders matching a status, date, or payment method filter.

7 0
View
woo-b2b-customer-overview logo
navarroido/Woocommerce-skill

woo-b2b-customer-overview

Read-only: Export customers with a B2B role or meta_data flag including order count, lifetime spend, and last order date.

7 0
View
woo-order-lookup-and-summary logo
navarroido/Woocommerce-skill

woo-order-lookup-and-summary

Read-only: Retrieve a WooCommerce order by ID or customer email and produce a human-readable support summary.

7 0
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View