Automattic\WooCommerce\Admin\Features\Fulfillments

OrderFulfillmentsRestController::update_fulfillment │ public │ WC 1.0

Update a specific fulfillment for the order.

Method of the class: OrderFulfillmentsRestController{}

Returns

WP_REST_Response. The updated fulfillment, or an error if the request fails.

Usage

$OrderFulfillmentsRestController = new OrderFulfillmentsRestController();
$OrderFulfillmentsRestController->update_fulfillment( $request ): WP_REST_Response;

$request(WP_REST_Request) (required)

The request object.

OrderFulfillmentsRestController::update_fulfillment() OrderFulfillmentsRestController::update fulfillment code ^{WC 10.8.1}

public function update_fulfillment( WP_REST_Request $request ): WP_REST_Response {
	$order_id          = (int) $request->get_param( 'order_id' );
	$fulfillment_id    = (int) $request->get_param( 'fulfillment_id' );
	$notify_customer   = (bool) $request->get_param( 'notify_customer' );
	$customer_note_raw = $request->get_param( 'customer_note' );
	$customer_note     = is_string( $customer_note_raw ) ? $customer_note_raw : '';

	$order = wc_get_order( $order_id );
	if ( ! $order ) {
		// If the order does not exist, return an error.
		FulfillmentsTracker::track_fulfillment_validation_error( 'update', 'woocommerce_rest_order_invalid_id', $this->check_request_source( $request ) );
		return $this->prepare_error_response(
			'woocommerce_rest_order_invalid_id',
			esc_html__( 'Invalid order ID.', 'woocommerce' ),
			WP_Http::NOT_FOUND
		);
	}

	// Update the fulfillment for the order.
	try {
		$fulfillment     = new Fulfillment( $fulfillment_id );
		$previous_state  = $fulfillment->get_is_fulfilled();
		$previous_status = $fulfillment->get_status() ?? 'unfulfilled';
		$this->validate_fulfillment( $fulfillment, $fulfillment_id, $order_id );

		$fulfillment->set_props( $request->get_json_params() );
		$next_state = $fulfillment->get_is_fulfilled();

		if ( isset( $request->get_json_params()['meta_data'] ) ) {
			$meta_data       = $request->get_json_params()['meta_data'];
			$normalized_keys = is_array( $meta_data ) ? array_column( MetaDataUtil::normalize( $meta_data, 0 ), 'key' ) : array();
			MetaDataUtil::update( $meta_data, $fulfillment, 0 );

			// Remove meta keys not in the request. Skip if all entries were malformed
			// (non-empty input but no valid keys), to avoid accidental data loss.
			if ( empty( $meta_data ) || ! empty( $normalized_keys ) ) {
				$existing_meta_data = $fulfillment->get_meta_data();
				foreach ( $existing_meta_data as $meta ) {
					if ( ! in_array( $meta->key, $normalized_keys, true ) ) {
						$fulfillment->delete_meta_data( $meta->key );
					}
				}
			}
		}

		$changed_fields = $fulfillment->get_changes();

		$fulfillment->save();

		FulfillmentsTracker::track_fulfillment_update(
			$this->check_request_source( $request ),
			$fulfillment->get_id(),
			$previous_status,
			$changed_fields,
			$notify_customer
		);

		// Track if tracking information was added or changed in this update.
		$this->maybe_track_tracking_added( $fulfillment, $request, $changed_fields );

		if ( $notify_customer ) {
			if ( ! $previous_state && $next_state ) {
				/**
				 * Trigger the fulfillment created notification on fulfilling a fulfillment.
				 *
				 * @since 10.1.0
				 */
				do_action( 'woocommerce_fulfillment_created_notification', $order_id, $fulfillment, wc_get_order( $order_id ) );
				FulfillmentsTracker::track_fulfillment_notification_sent( 'fulfillment_created', $fulfillment->get_id(), $order_id );
			} elseif ( $next_state ) {
				/**
				 * Trigger the fulfillment updated notification on updating a fulfillment.
				 *
				 * @param int                        $order_id      The order ID.
				 * @param Fulfillment                $fulfillment   The fulfillment object.
				 * @param \WC_Order|\WC_Order_Refund|false $order    The order object.
				 * @param string                     $customer_note Optional customer note from the merchant.
				 *
				 * @since 10.1.0
				 * @since 10.8.0 Added $customer_note parameter.
				 */
				do_action( 'woocommerce_fulfillment_updated_notification', $order_id, $fulfillment, $order, $customer_note );
				FulfillmentsTracker::track_fulfillment_notification_sent( 'fulfillment_updated', $fulfillment->get_id(), $order_id );
			}
		}
	} catch ( ApiException $ex ) {
		FulfillmentsTracker::track_fulfillment_validation_error( 'update', $ex->getErrorCode(), $this->check_request_source( $request ) );
		return $this->prepare_error_response(
			$ex->getErrorCode(),
			$ex->getMessage(),
			WP_Http::BAD_REQUEST
		);
	} catch ( \Exception $e ) {
		FulfillmentsTracker::track_fulfillment_validation_error( 'update', (string) $e->getCode(), $this->check_request_source( $request ) );
		return $this->prepare_error_response(
			$e->getCode(),
			$e->getMessage(),
			WP_Http::BAD_REQUEST
		);
	}

	return new WP_REST_Response(
		$fulfillment->get_raw_data(),
		WP_Http::OK
	);
}