FulfillmentsTracker
in package
FulfillmentsTracker class.
Centralizes all telemetry for the Fulfillments feature. Every tracked event is recorded via WC_Tracks::record_event() which sends it to the analytics pipeline with a "wcadmin_" prefix.
Tracked events (WOOPLUG-5197):
-
Core Funnel (Adoption):
- fulfillment_modal_opened : Merchant opens the fulfillment editor drawer. (Frontend only)
- fulfillment_created : A new fulfillment is saved. (REST controller)
- fulfillment_updated : An existing fulfillment is modified. (REST controller)
- fulfillment_deleted : A fulfillment is deleted. (REST controller)
-
Tracking Information (Usage Patterns):
- fulfillment_tracking_added : Tracking info is attached to a fulfillment. (REST controller)
- fulfillment_tracking_lookup_attempted : Tracking number auto-lookup is attempted. (FulfillmentsManager)
-
Efficiency / Power-User:
- fulfillment_bulk_action_used : Bulk fulfill/unfulfill from the orders list. (FulfillmentsRenderer)
- fulfillment_filter_used : Orders list filtered by fulfillment status/provider. (FulfillmentsRenderer)
-
Customer Communication:
- fulfillment_notification_sent : A fulfillment email is queued to the customer. (REST controller)
- fulfillment_email_template_customized : Merchant saves fulfillment email template settings. (FulfillmentsManager)
-
Friction / Errors:
- fulfillment_validation_error : A create/update/delete action fails validation. (REST controller)
Tags
Table of Contents
- determine_tracking_entry_method() : string
- Determine the tracking entry method from the request source and fulfillment meta data.
- track_fulfillment_bulk_action_used() : void
- Track when a merchant applies a fulfillment-related bulk action from the orders list.
- track_fulfillment_creation() : void
- Track when a new fulfillment is successfully saved.
- track_fulfillment_deletion() : void
- Track when a fulfillment is successfully deleted.
- track_fulfillment_email_template_customized() : void
- Track when a merchant saves changes to a fulfillment email template in settings.
- track_fulfillment_filter_used() : void
- Track when the orders list is filtered using a fulfillment-related filter.
- track_fulfillment_modal_opened() : void
- Track when a merchant opens the fulfillment editor modal/sidebar.
- track_fulfillment_notification_sent() : void
- Track when a fulfillment notification email is successfully queued to a customer.
- track_fulfillment_tracking_added() : void
- Track when tracking information is successfully added to a fulfillment.
- track_fulfillment_tracking_lookup_attempt() : void
- Track when a tracking number auto-lookup is attempted.
- track_fulfillment_update() : void
- Track when an existing fulfillment is successfully updated.
- track_fulfillment_validation_error() : void
- Track when a fulfillment action fails due to a validation error.
Methods
determine_tracking_entry_method()
Determine the tracking entry method from the request source and fulfillment meta data.
public
static determine_tracking_entry_method(string $source, string $shipping_option) : string
Maps the shipping option meta value to the standardized entry_method values expected by the fulfillment_tracking_added event. Whether the provider is custom or native is tracked separately via the is_custom_provider property on the event.
- "ui_auto_lookup" : Tracking number was auto-detected via the lookup API.
- "ui_manual" : Merchant manually selected or entered a provider.
- "api" : Tracking was added via the REST API (not through the UI).
Parameters
- $source : string
-
The request source ("fulfillments_modal" or "api").
- $shipping_option : string
-
The shipping option meta value ("tracking-number", "manual-entry", or "no-info").
Tags
Return values
string — The entry method identifier.track_fulfillment_bulk_action_used()
Track when a merchant applies a fulfillment-related bulk action from the orders list.
public
static track_fulfillment_bulk_action_used(string $action, int $order_count) : void
Tracked from: FulfillmentsRenderer::handle_fulfillment_bulk_actions(). Measures: Whether merchants use the time-saving bulk-fulfill feature.
Parameters
- $action : string
-
The action performed ("fulfill_orders" or "unfulfill_orders").
- $order_count : int
-
The number of orders selected for the bulk action.
Tags
Return values
void —track_fulfillment_creation()
Track when a new fulfillment is successfully saved.
public
static track_fulfillment_creation(string $source, string $initial_status, string $fulfillment_type, int $item_count, int $total_quantity, bool $notification_sent) : void
Tracked from: OrderFulfillmentsRestController::create_fulfillment(). Measures: Core adoption; whether merchants create full vs. partial shipments.
Parameters
- $source : string
-
The source of the fulfillment ("fulfillments_modal", "bulk_action", or "api").
- $initial_status : string
-
The initial status of the fulfillment ("draft" or "fulfilled").
- $fulfillment_type : string
-
Whether all remaining items were included ("full" or "partial").
- $item_count : int
-
Total quantity of items in the fulfillment (sum of item quantities).
- $total_quantity : int
-
Total quantity of all items in the order.
- $notification_sent : bool
-
Whether the customer notification was requested.
Tags
Return values
void —track_fulfillment_deletion()
Track when a fulfillment is successfully deleted.
public
static track_fulfillment_deletion(string $source, int $fulfillment_id, string $status_at_deletion, bool $notification_sent) : void
Tracked from: OrderFulfillmentsRestController::delete_fulfillment(). Measures: How often merchants remove fulfillments and at what stage.
Parameters
- $source : string
-
The source of the deletion ("fulfillments_modal" or "api").
- $fulfillment_id : int
-
The ID of the fulfillment being deleted.
- $status_at_deletion : string
-
The status at the time of deletion ("draft" or "fulfilled").
- $notification_sent : bool
-
Whether a deletion notification was requested.
Tags
Return values
void —track_fulfillment_email_template_customized()
Track when a merchant saves changes to a fulfillment email template in settings.
public
static track_fulfillment_email_template_customized(string $template_name) : void
Tracked from: FulfillmentsManager (hooked to woocommerce_update_options_email_{id}). Measures: Whether merchants customize fulfillment email templates.
Parameters
- $template_name : string
-
The email template ID that was customized (e.g., "customer_fulfillment_created").
Tags
Return values
void —track_fulfillment_filter_used()
Track when the orders list is filtered using a fulfillment-related filter.
public
static track_fulfillment_filter_used(string $filter_by, string $filter_value) : void
Tracked from: FulfillmentsRenderer::filter_orders_list_table_query(). Measures: Whether merchants use fulfillment filters and which values they filter by most.
Parameters
- $filter_by : string
-
The filter field ("fulfillment_status" or "shipping_provider").
- $filter_value : string
-
The specific value selected (e.g., "partially_fulfilled", "usps").
Tags
Return values
void —track_fulfillment_modal_opened()
Track when a merchant opens the fulfillment editor modal/sidebar.
public
static track_fulfillment_modal_opened(string $source, int $order_id) : void
Tracked from: Frontend (JS recordEvent). Measures: Feature discoverability and adoption.
Parameters
- $source : string
-
Where the modal was opened from ("orders_list" or "order_detail_page").
- $order_id : int
-
The ID of the order being viewed.
Tags
Return values
void —track_fulfillment_notification_sent()
Track when a fulfillment notification email is successfully queued to a customer.
public
static track_fulfillment_notification_sent(string $trigger_action, int $fulfillment_id, int $order_id) : void
Tracked from: OrderFulfillmentsRestController (create, update, and delete flows). Measures: Whether the communication loop is being closed; how often merchants notify customers.
Parameters
- $trigger_action : string
-
The action that triggered the notification ("fulfillment_created", "fulfillment_updated", or "fulfillment_deleted").
- $fulfillment_id : int
-
The ID of the fulfillment.
- $order_id : int
-
The ID of the associated order.
Tags
Return values
void —track_fulfillment_tracking_added()
Track when tracking information is successfully added to a fulfillment.
public
static track_fulfillment_tracking_added(int $fulfillment_id, string $entry_method, string $provider_name, bool $is_custom_provider) : void
Tracked from: OrderFulfillmentsRestController (create and update flows). Measures: How merchants add tracking info (auto-lookup vs. manual vs. API) and which carriers are used. The provider_name property for custom providers is used to identify the most frequently added custom carriers, informing the roadmap for expanding native carrier support.
Parameters
- $fulfillment_id : int
-
The ID of the fulfillment to which tracking was added.
- $entry_method : string
-
How the tracking was added ("ui_auto_lookup", "ui_manual_select", "ui_manual_custom", or "api").
- $provider_name : string
-
The name/key of the shipping provider (e.g., "usps", "fedex").
- $is_custom_provider : bool
-
Whether the provider is a custom (non-native) provider.
Tags
Return values
void —track_fulfillment_tracking_lookup_attempt()
Track when a tracking number auto-lookup is attempted.
public
static track_fulfillment_tracking_lookup_attempt(string $lookup_status, string $provider_identified[, bool $url_generated = false ]) : void
Tracked from: FulfillmentsManager::try_parse_tracking_number(). Measures: Effectiveness of auto-detection. A high failure rate indicates the need to improve carrier detection logic. The url_generated flag checks if a functional tracking URL was constructed (a success requires both provider identification AND URL generation).
Parameters
- $lookup_status : string
-
The lookup result ("success" or "not_found").
- $provider_identified : string
-
The standardized carrier name identified (e.g., "usps"). Empty if not found.
- $url_generated : bool = false
-
Whether the system successfully constructed a tracking URL.
Tags
Return values
void —track_fulfillment_update()
Track when an existing fulfillment is successfully updated.
public
static track_fulfillment_update(string $source, int $fulfillment_id, string $original_status, array<string|int, mixed> $changed_fields, bool $notification_sent) : void
Tracked from: OrderFulfillmentsRestController::update_fulfillment(). Measures: How often merchants modify fulfillments and which fields change most.
Parameters
- $source : string
-
The source of the update ("fulfillments_modal" or "api").
- $fulfillment_id : int
-
The ID of the fulfillment being updated.
- $original_status : string
-
The status before the update ("draft" or "fulfilled").
- $changed_fields : array<string|int, mixed>
-
The changes as returned by Fulfillment::get_changes(). Core data props (e.g. 'status') at top level, meta changes under 'meta_data'. Serialized as JSON by WC_Tracks.
- $notification_sent : bool
-
Whether a customer re-notification was requested.
Tags
Return values
void —track_fulfillment_validation_error()
Track when a fulfillment action fails due to a validation error.
public
static track_fulfillment_validation_error(string $action_attempted, string $error_code, string $source) : void
Tracked from: OrderFulfillmentsRestController (create, update, and delete flows). Measures: Where users encounter errors; helps proactively identify bugs and UX problems.
Parameters
- $action_attempted : string
-
The action that was attempted ("create", "update", "delete", or "fulfill").
- $error_code : string
-
The error code from the exception.
- $source : string
-
The source of the error ("fulfillments_modal", "bulk_action", or "api").