Free and Pro

A WooCommerce returns API with webhooks and PHP hooks

The WooCommerce returns API in WPReturns is the set of REST routes, webhooks and PHP hooks that connect returns to your other systems. REST lives under ddwcwr/v1 with application password auth, and WooCommerce webhooks fire on return_request.created and return_request.updated. Actions and filters cover requests, labels, rules and the order layer.

Get WPReturns Pro Read the docs

GET /wp-json/ddwcwr/v1/requests

curl -u "ops:app-password" \
  "https://yourstore.com/wp-json/ddwcwr/v1/requests?status=pending"

[{
  "id": 1042,
  "number": "RMA-01042",
  "type": "return",
  "status": "pending",
  "status_label": "Requested",
  "resolution": "store_credit",
  "items_total": 84,
  "credit_bonus": 8.4,
  "risk_flags": [],
  "items": [{ "name": "Linen Overshirt", "qty": 1,
              "reason": "wrong-size", "condition": "unopened" }]
}]

functions.php

// Post every approved request to your helpdesk.
add_action( 'ddwcwr_request_status_changed', function ( $request_id, $old_status, $new_status ) {
    if ( 'approved' !== $new_status ) {
        return;
    }
    my_helpdesk_note( $request_id, 'Return approved in WPReturns' );
}, 10, 3 );

The problem

Returns data trapped in wp-admin

Your helpdesk, warehouse and ERP all need to know when a return opens or changes. Without an API someone copies it across by hand.

None of the WooCommerce returns plugins we compared shipped a REST API or webhooks (compared on October 30, 2026). One listed only vague API settings.

How WPReturns solves it

What the WooCommerce returns API exposes

REST routes list, read, create and update requests, post messages and read reasons. Every route needs a user with the ddwcwr_manage_requests capability.

Webhooks use WooCommerce's own delivery. Add one under WooCommerce > Settings > Advanced > Webhooks and WooCommerce signs and retries it.

In PHP every order call goes through an adapter you can swap with the ddwcwr_order_adapter filter. New carriers plug in through DDWCWR_Label_Provider_Interface and the ddwcwr_label_providers filter.

REST namespace ddwcwr/v1
Application password auth
Signed WooCommerce webhooks
Request lifecycle actions
Swappable order adapter
Custom label providers
Theme template overrides
HPOS-safe order access

How it works

01
Create an application password
Add one under Users > Profile for a user who can manage requests. Send it with Basic auth on every REST call.
02
Call the REST routes
Use GET and POST on /wp-json/ddwcwr/v1/requests and GET and PUT on /requests/{id}. Messages and reasons have routes of their own.
03
Subscribe to webhooks
Pick Return request created or Return request updated as the topic. WooCommerce posts the request payload to your URL.
04
Hook into PHP events
Listen to ddwcwr_request_created or ddwcwr_request_status_changed for custom logic. Override front templates in yourtheme/wpreturns/front/.

The settings involved

These settings control this feature. The plugin explains each one next to its field.

SettingWhereWhat it does

DevelopersConfiguration > AdvancedShows the REST base URL and where to add webhooks.

WebhooksWooCommerce > Settings > Advanced > WebhooksAdds a webhook with the topic Return request created or Return request updated.

Application PasswordsUsers > ProfileCreates the credential a REST client uses to sign in.

UninstallConfiguration > AdvancedDeletes all WPReturns tables and settings when the plugin is deleted.

Free or Pro

Free

Action and filter hooks
Order adapter interface
Theme template overrides
Private upload folder filter
GDPR export and erase

Pro

REST API under ddwcwr/v1
WooCommerce webhook topics
Label provider interface
Action Scheduler automation
Rule and risk flag filters

Full Free vs Pro table

Developer API questions

Ask the team or read the docs if your question is not here.

How do I authenticate REST requests?

Use a WordPress application password for a user with the ddwcwr_manage_requests capability. Administrators and shop managers have it by default.

Which REST routes are available?

GET and POST /requests, GET and PUT /requests/{id}, GET and POST /requests/{id}/messages and GET /reasons. All of them live under /wp-json/ddwcwr/v1/.

How do the webhooks work?

WPReturns registers two WooCommerce webhook topics named Return request created and Return request updated. WooCommerce handles delivery, signing and retries like any other webhook.

Can I add my own shipping carrier?

Yes. Write a class for DDWCWR_Label_Provider_Interface with get_id(), get_name(), is_configured() and create_label(). Register it through the ddwcwr_label_providers filter.

Can I move private uploads outside the web root?

Yes, with the ddwcwr_private_upload_dir filter. On nginx with the folder inside uploads, add location ~ /ddwcwr-private- { deny all; } to your server block.

Is there a free version?

Yes. The free WPReturns plugin includes the action and filter hooks, the order adapter and template overrides. The REST API, webhooks, label provider interface and Action Scheduler automation are part of WPReturns Pro.

Related features

Free plugin on wordpress.org

Developer API for your WooCommerce store

Start with the free plugin and the EU withdrawal button. Move to Pro from $99 a year when you want credit, exchanges and rules.

Get WPReturns Pro Download free