For Developers

Shortcodes

Withdrawal Form

[wpify_woo_withdrawal_form]

Renders the withdrawal form. Returns empty string (no output) if Withdrawal page is not assigned in module settings.

In the Gutenberg/block editor, an admin-only placeholder is shown when the half is disabled, so you know the block exists but won’t render on the front end.

Claim Form

[wpify_woo_claim_form]

Renders the claim (warranty) form. Same disabled-state behavior as the withdrawal form.

Both on the Same Page

Both shortcodes/blocks can be placed on a single page. The URL parameter ?form=withdrawal or ?form=claim controls which form is pre-filled when the customer arrives. HTML anchors #wpify-woo-withdrawal-form and #wpify-woo-claim-form allow direct links.

Example link:

/returns/?order_key=wc_order_abc123&form=withdrawal#wpify-woo-withdrawal-form

Gutenberg Blocks

Block	Equivalent Shortcode
`wpify-woo/withdrawal-form`	`[wpify_woo_withdrawal_form]`
`wpify-woo/claim-form`	`[wpify_woo_claim_form]`

Both blocks support align, className, and use ServerSideRender for live preview in the editor.

URL Parameters

Parameter	Purpose	Auth model
`?order_key={wc_order_key}`	Trusted token from WC (used in plugin-generated email links) — full pre-fill, no email match required	Possession of the cryptographic key = authorization
`?order={order_number_or_id}`	Identifier hint (manual entry, footer link) — empty form, 2-factor (order # + billing email match) required	Two-factor verification
`?form=withdrawal\|claim`	Selects which form on a shared page is pre-filled/active	—
`?submitted=1`	Triggers the thank-you state (set by the plugin after successful submission)	—
`?wcr_err={message}`	Error message shown on the form (no-JS PRG fallback only)	—

Filters

`wpify_woo_withdrawal_claims_blocked_statuses`

Defines order statuses where new withdrawal/claim requests are blocked.

apply_filters( 'wpify_woo_withdrawal_claims_blocked_statuses', array $statuses, WC_Order $order );

Default

array( 'refunded', 'cancelled', 'failed', 'checkout-draft', 'auto-draft' )

Example: also block “on-hold” orders

add_filter( 'wpify_woo_withdrawal_claims_blocked_statuses', function( $statuses ) {
    $statuses[] = 'on-hold';
    return $statuses;
} );

`wpify_woo_withdrawal_claims_resolve_order`

Fallback resolver for custom order_number formats (e.g., Sequential Order Numbers, custom prefixes). Called when the default ID lookup fails.

apply_filters( 'wpify_woo_withdrawal_claims_resolve_order', ?WC_Order $order, string $identifier );

Example: support custom prefix “ORD-”

add_filter( 'wpify_woo_withdrawal_claims_resolve_order', function( $order, $identifier ) {
    if ( strpos( $identifier, 'ORD-' ) === 0 ) {
        $id = (int) substr( $identifier, 4 );
        return wc_get_order( $id );
    }
    return $order;
}, 10, 2 );

`wpify_woo_withdrawal_claims_eligible_items`

Modifies the list of items shown in the form per type.

apply_filters( 'wpify_woo_withdrawal_claims_eligible_items', array $result, WC_Order $order, string $type );

$result has keys: items (array of rows), eligible_count, ineligible_count.

`wpify_woo_withdrawal_claims_is_eligible_item`

Per-item override of eligibility.

apply_filters( 'wpify_woo_withdrawal_claims_is_eligible_item', array $result, WC_Order_Item $item, WC_Order $order, string $type );

$result has keys: eligible (bool), reason (string), line_item_id (int).

`wpify_woo_withdrawal_claims_period_end` / `period_start`

Override the calculated period end/start dates.

apply_filters( 'wpify_woo_withdrawal_claims_period_end', DateTimeInterface $end, WC_Order $order, string $type );
apply_filters( 'wpify_woo_withdrawal_claims_period_start', DateTimeInterface $start, WC_Order $order, string $type );

`wpify_woo_withdrawal_claims_is_excluded_product`

Per-product exclusion override (default reads _wpify_woo_withdrawal_excluded / _wpify_woo_warranty_excluded meta).

apply_filters( 'wpify_woo_withdrawal_claims_is_excluded_product', bool $excluded, WC_Product $product, string $type );

`wpify_woo_withdrawal_claims_request_data`

Modify request data just before saving (including status, custom meta).

apply_filters( 'wpify_woo_withdrawal_claims_request_data', array $data, string $type );

Example: set custom default status

add_filter( 'wpify_woo_withdrawal_claims_request_data', function( $data, $type ) {
    $data['status'] = 'pending_review';
    return $data;
}, 10, 2 );

`wpify_woo_withdrawal_claims_email_recipient`

Override the recipient email of a request notification.

apply_filters( 'wpify_woo_withdrawal_claims_email_recipient', string $email, int $request_id, string $context );

$context is 'customer' or 'admin'.

`wpify_woo_withdrawal_claims_inject_link_emails`

Override the list of WC emails into which the withdrawal link is injected.

apply_filters( 'wpify_woo_withdrawal_claims_inject_link_emails', array $email_ids );

`wpify_woo_withdrawal_claims_my_account_button_args`

Modify the button rendered in the My Account order detail (text, URL, attributes).

apply_filters( 'wpify_woo_withdrawal_claims_my_account_button_args', array $args, WC_Order $order, string $type );

`wpify_woo_withdrawal_claims_form_fields`

Modify the list of form fields (advanced — for custom field additions).

apply_filters( 'wpify_woo_withdrawal_claims_form_fields', array $fields, string $type );

Actions

`wpify_woo_withdrawal_claims_request_created`

Fires after a request is successfully saved. Primary extension point for custom workflows.

do_action( 'wpify_woo_withdrawal_claims_request_created', int $request_id, int $order_id, string $type );

Example: notify Slack on each request

add_action( 'wpify_woo_withdrawal_claims_request_created', function( $request_id, $order_id, $type ) {
    wp_remote_post( 'https://hooks.slack.com/services/...', array(
        'body' => wp_json_encode( array(
            'text' => sprintf( 'New %s request #%d for order #%d', $type, $request_id, $order_id ),
        ) ),
    ) );
}, 10, 3 );

`wpify_woo_withdrawal_claims_status_changed`

For custom workflow extensions that change the request status. Plugin itself never changes the status.

do_action( 'wpify_woo_withdrawal_claims_status_changed', int $request_id, string $old_status, string $new_status );

`wpify_woo_withdrawal_claims_before_email_send` / `after_email_send`

Fire around email dispatch.

do_action( 'wpify_woo_withdrawal_claims_before_email_send', WC_Email $email, int $request_id );
do_action( 'wpify_woo_withdrawal_claims_after_email_send', WC_Email $email, int $request_id, bool $success );

`wpify_woo_withdrawal_claims_my_account_after_buttons`

Inject custom content under the buttons in My Account.

do_action( 'wpify_woo_withdrawal_claims_my_account_after_buttons', WC_Order $order );

`wpify_woo_withdrawal_claims_form_before` / `form_after`

Wrap the form with custom HTML.

do_action( 'wpify_woo_withdrawal_claims_form_before', string $type, ?WC_Order $order );
do_action( 'wpify_woo_withdrawal_claims_form_after', string $type, ?WC_Order $order );

REST API

The form uses two REST endpoints internally:

Endpoint	Method	Purpose
`/wp-json/wpify-woo/v1/withdrawal-claims/validate`	POST	Validates the auth fields (untrusted scenario) and returns the pre-rendered eligibility section HTML
`/wp-json/wpify-woo/v1/withdrawal-claims/submit`	POST	Final submission — validates everything, saves to DB, sends emails

Both endpoints accept JSON bodies with the form fields. Authentication is via X-WP-Nonce header (REST nonce) plus an inner _wpify_woo_nonce form-specific nonce.

Database Table

Table: {prefix}wpify_woo_requests (created automatically via Wpify\Model\CustomTableRepository).

Column	Type	Notes
`id`	INT, AUTO_INCREMENT, PK
`request_type`	VARCHAR(20)	`withdrawal` \| `claim`
`order_id`	BIGINT	WC order ID
`order_number`	VARCHAR(50)	For display/search
`customer_email`	VARCHAR(255)	Snapshot of `billing_email` at submission
`customer_name`	VARCHAR(255)	Name from form
`items_json`	TEXT	JSON `[{line_item_id, quantity}]`
`reason`	TEXT	Optional for withdrawal, required for claim
`scope`	VARCHAR(20)	`whole_order` \| `specific_items`
`status`	VARCHAR(50)	Default `submitted`, plugin never changes — extension point
`period_end`	DATETIME	Snapshot of period end at submission
`submitted_at`	DATETIME	Required by directive 2023/2673
`customer_ip`, `customer_user_agent`	VARCHAR	Audit
`created_at`	DATETIME

CSS Classes

Class	Element
`.wpify-woo-form`	Form section wrapper
`.wpify-woo-form--withdrawal` / `.wpify-woo-form--claim`	Type-specific class
`.wpify-woo-form--submitted`	Thank-you state
`.wpify-woo-form--loading`	Loading state during AJAX
`.wpify-woo-form-errors`	Error message block
`.wpify-woo-items`	Items fieldset (toggled by scope radio)
`.wpify-woo-scope`	Scope radio fieldset
`.woocommerce-form-withdrawal` / `.woocommerce-form-claim`	Form element class
`.wpify-woo-helper-text`	Helper text under submit button

Per-product Meta Keys

Meta key	Type	Description
`_wpify_woo_withdrawal_excluded`	yes/no	Excluded from withdrawal
`_wpify_woo_warranty_excluded`	yes/no	Excluded from claim/warranty
`_wpify_woo_withdrawal_period_override`	int (days)	Per-product withdrawal period
`_wpify_woo_warranty_months_override`	int (months)	Per-product warranty period

Per-order Meta Keys

Meta key	Type	Description
`_wpify_woo_period_start`	datetime (mysql)	Saved by the plugin when the order first transitions into a configured period-start status

Where to Add Code

You can add custom functions to:

The functions.php file in your child theme
The Code Snippets plugin
A custom plugin