Woo Order Hold And Release

woo-order-hold-and-release

Purpose

Place a set of WooCommerce orders into on-hold status (with a timestamped reason note) or bulk-release them back to processing. Common uses: hold orders pending fraud review, payment verification, or stock availability, then release them when cleared. Includes dry-run preview.

Prerequisites

• WooCommerce store with REST API enabled
• Consumer Key with Read/Write scope
• Minimum WooCommerce version: 3.5.0

Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | store_url | string | yes | — | Base URL of the WooCommerce store | | 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 without executing | | format | string | no | human | Output format: human or json | | action | string | yes | — | hold or release | | order_ids | array | no | — | Specific order IDs (if not using filters) | | filter_status | string | no | processing | For hold: filter orders in this status | | hold_reason | string | no | Order held for review | Reason added as private note | | release_target_status | string | no | processing | Status to set when releasing held orders |

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 changes order status. Always run with dry_run: true first (the default). Review the affected order list before holding or releasing.

Workflow Steps

Step 1 — Resolve order list

If order_ids provided: fetch each directly.

Otherwise:

GET /wp-json/wc/v3/orders?status=&per_page=100&page=1

For action: release: fetch orders with status=on-hold.

Step 2 — Preview or execute

If dry_run: true: list orders. Stop.

If dry_run: false and confirmed, use batch:

POST /wp-json/wc/v3/orders/batch
  Body: {
    "update": [
      { "id": , "status": "on-hold" }  // for hold
      // OR
      { "id": , "status": "" }  // for release
    ]
  }

API Endpoints Used

GET   /wp-json/wc/v3/orders          — filtered order list
POST  /wp-json/wc/v3/orders/batch    — bulk status update
PUT   /wp-json/wc/v3/orders/{id}     — add hold reason note

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-order-hold-and-release    ║
║  RECORDS PROCESSED:                   ║
║  OUTPUT: stdout                          ║
╚══════════════════════════════════════════╝

COMPLETION (json format):

{
  "skill": "woo-order-hold-and-release",
  "store": "",
  "completed_at": "",
  "records_processed": ,
  "output_file": null,
  "dry_run": 
}

Output Format

Human format: table of order number, customer, total, and new status.

Error Handling

| Error | Cause | Resolution | |-------|-------|------------| | 401 Unauthorized | Invalid credentials | Verify consumerkey and consumersecret | | 403 Forbidden | Key lacks Read/Write scope | Regenerate with Read/Write scope | | 429 Too Many Requests | Rate limit | Wait 2 seconds and retry |

Best Practices

• Always run with dry_run: true first.
• Include a specific hold_reason for audit purposes (e.g., "Held pending fraud review 2025-04-14").
• Pair with woo-fulfillment-status-digest to monitor how many orders are accumulating in on-hold.

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.