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. Called only when both the default numeric ID lookup AND the built-in WooCommerce search fall through.

Note

Most custom order number plugins (Sequential Order Numbers for WooCommerce, Sequential Order Numbers Pro, Custom Order Numbers for WooCommerce, …) hook into WooCommerce’s built-in order search and are picked up automatically — no filter needed. Use this filter only for plugins that do not extend WC search.

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_type_labels

Human-readable labels for request types. Register additional types or override the defaults.

apply_filters( 'wpify_woo_withdrawal_claims_request_type_labels', array $labels );

Defaults: withdrawal → “Withdrawal”, claim → “Claim”.

---

wpify_woo_withdrawal_claims_scope_labels

Human-readable labels for request scopes.

apply_filters( 'wpify_woo_withdrawal_claims_scope_labels', array $labels );

Defaults: whole_order → “Whole order”, specific_items → “Specific items”.

---

wpify_woo_withdrawal_claims_status_labels

Human-readable labels for request statuses. Use this to register custom statuses set by your own integration so they display correctly in emails and the admin overview.

apply_filters( 'wpify_woo_withdrawal_claims_status_labels', array $labels );

Default: submitted → “Submitted”.

Example: register custom statuses

add_filter( 'wpify_woo_withdrawal_claims_status_labels', function( $labels ) {
    $labels['in_progress'] = __( 'In progress', 'my-plugin' );
    $labels['resolved']    = __( 'Resolved', 'my-plugin' );
    return $labels;
} );

---

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'.

Caution

Default for customer notifications is always billing_email to prevent data leaks. Override at your own risk.

---

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

Add custom fields to the request form (e.g. IBAN, phone, custom consent). A field defined via this filter is automatically rendered in the form, validated, persisted, and shown everywhere the plugin displays the request — admin detail, customer “My Account” history, and both HTML and plain-text emails.

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

Field schema

Each field is an associative array:

Key	Type	Required	Description
id	string	yes	Unique identifier (used as HTML input name and as the key in stored data)
label	string	yes	Field label shown in the form, admin, and emails
type	string	no	text (default), email, tel, textarea, select, checkbox
placeholder	string	no	HTML placeholder for input fields
required	bool	no	true to require the field before submission (with validation message)
options	array	only for select	Array of ['value' => ..., 'label' => ...]
sanitize	callable	no	Custom sanitizer; defaults per type if omitted
validate	callable	no	Custom validator; returns WP_Error or true

Example: add IBAN to the withdrawal form

add_filter( 'wpify_woo_withdrawal_claims_form_fields', function ( array $fields, string $type ) {
    if ( $type !== 'withdrawal' ) {
        return $fields;
    }

    $fields[] = array(
        'id'          => 'iban',
        'type'        => 'text',
        'label'       => __( 'Bank account (IBAN)', 'my-textdomain' ),
        'placeholder' => 'SK00 0000 0000 0000 0000 0000',
        'required'    => true,
    );

    return $fields;
}, 10, 2 );

The IBAN field is then shown in the form, required at submission, stored with the request, and displayed in admin, customer “My Account” history, and admin/customer emails — with no extra code.

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

Note

No item snapshot (name/SKU/price) is stored. Display reads live data from the order. If the line item is later deleted, “Item no longer in order (line #N)” is shown. Full historical change log is in WC order notes.

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