Merge pull request #3588 from woocommerce/PCP-2908-create-snippet-to-automatically-add-tracking-details-for-sendle-shipping-plugin

Create an API function for adding tracking info. (2908)

api/order-functions.php

@@ -17,6 +17,8 @@ use RuntimeException;
 use WC_Order;
 use WooCommerce\PayPalCommerce\ApiClient\Endpoint\OrderEndpoint;
 use WooCommerce\PayPalCommerce\ApiClient\Entity\Order;
+use WooCommerce\PayPalCommerce\OrderTracking\Endpoint\OrderTrackingEndpoint;
+use WooCommerce\PayPalCommerce\OrderTracking\Shipment\ShipmentFactoryInterface;
 use WooCommerce\PayPalCommerce\PPCP;
 use WooCommerce\PayPalCommerce\WcGateway\Gateway\PayPalGateway;
 use WooCommerce\PayPalCommerce\WcGateway\Helper\RefundFeesUpdater;
@@ -159,3 +161,53 @@ function ppcp_update_order_refund_fees( WC_Order $wc_order ): void {
 	assert( $updater instanceof RefundFeesUpdater );
 	$updater->update( $wc_order );
 }
+
+/**
+ * Creates or updates PayPal order tracking information for a WooCommerce order.
+ *
+ * Retrieves the PayPal capture ID associated with the given WooCommerce order,
+ * creates a shipment instance, and sends it to the PayPal Order Tracking API.
+ * If tracking information for the given tracking number already exists, it will
+ * be updated; otherwise, it will be added as new tracking information.
+ *
+ * @param WC_Order $wc_order WooCommerce order instance to attach tracking to.
+ * @param string   $tracking_number Tracking number provided by the carrier.
+ * @param string   $carrier Name of the shipping carrier (must be PayPal-approved).
+ * @param string   $status Shipment status (must be PayPal-approved). Defaults to 'SHIPPED'.
+ *
+ * @see https://developer.paypal.com/docs/tracking/reference/carriers/ List of PayPal-approved carriers.
+ * @see https://developer.paypal.com/docs/tracking/reference/shipping-status/ List of PayPal-approved shipment statuses.
+ *
+ * @return void
+ */
+function ppcp_create_order_tracking( WC_Order $wc_order, string $tracking_number, string $carrier, string $status = 'SHIPPED' ): void {
+	$shipment_factory = PPCP::container()->get( 'order-tracking.shipment.factory' );
+	assert( $shipment_factory instanceof ShipmentFactoryInterface );
+
+	$endpoint = PPCP::container()->get( 'order-tracking.endpoint.controller' );
+	assert( $endpoint instanceof OrderTrackingEndpoint );
+
+	$paypal_order = ppcp_get_paypal_order( $wc_order );
+	$capture_id   = $endpoint->get_paypal_order_transaction_id( $paypal_order );
+	if ( is_null( $capture_id ) ) {
+		throw new RuntimeException( 'Could not retrieve transaction ID from PayPal order' );
+	}
+
+	$wc_order_id = $wc_order->get_id();
+
+	$ppcp_shipment = $shipment_factory->create_shipment(
+		$wc_order_id,
+		$capture_id,
+		$tracking_number,
+		$status,
+		'OTHER',
+		$carrier,
+		array()
+	);
+
+	$tracking_information = $endpoint->get_tracking_information( $wc_order_id, $tracking_number );
+
+	$tracking_information
+		? $endpoint->update_tracking_information( $ppcp_shipment, $wc_order_id )
+		: $endpoint->add_tracking_information( $ppcp_shipment, $wc_order_id );
+}

modules/ppcp-order-tracking/src/Endpoint/OrderTrackingEndpoint.php

@@ -34,7 +34,7 @@ use function WooCommerce\PayPalCommerce\Api\ppcp_get_paypal_order;
  *     status: SupportedStatuses,
  *     tracking_number: string,
  *     carrier: string,
- *     items?: list<int>,
+ *     items?: array,
  *     carrier_name_other?: string,
  * }
  * Class OrderTrackingEndpoint
@@ -393,7 +393,7 @@ class OrderTrackingEndpoint {
 			'carrier_name_other' => $data['carrier_name_other'] ?? '',
 		);
 
-		if ( ! empty( $data['items'] ) ) {
+		if ( ! empty( $data['items'] ) && is_numeric( reset( $data['items'] ) ) ) {
 			$tracking_info['items'] = array_map( 'intval', $data['items'] );
 		}