WooCommerce: prevent image duplication when sideloading via the REST API

[gabrielcld2]

Summary

When a product is created via the WooCommerce REST API and the images payload contains a Cloudinary URL, WooCommerce unconditionally sideloads the image into the WordPress media library as a new attachment. The Cloudinary plugin then auto-syncs this new attachment back up to Cloudinary, resulting in a duplicate asset on the Cloudinary account.

Approach

The fix intercepts the REST request before WooCommerce processes images, using the rest_request_before_callbacks filter — the same filter already used by the Cloudinary plugin's Delivery class.

For any image in the request that has a src but no id, we check whether the URL is a Cloudinary URL. If it is, we attempt to resolve it to an existing media library attachment using a three-step lookup:

1. Exact sync key — looks up the attachment whose sync key matches the full URL (including any transformation segments). Covers URLs that exist verbatim in
   the library.
2. Bare public ID — strips transformations and queries via get_linked_attachments(). Covers the most common case: an image uploaded from WordPress to
   Cloudinary with no transformations applied.
3. Base key fallback — queries the base_<public_id> meta key written for any asset imported directly from the Cloudinary dashboard.

When a match is found, the id field is populated on the image entry before the request reaches WC_REST_Products_Controller::set_product_images().

WooCommerce's own guard (if ( 0 === $attachment_id )) then skips the sideload entirely. If no match is found across all three steps, the request falls through unchanged and WooCommerce sideloads normally — existing behaviour is fully preserved.

The hook is registered in a new setup_rest_hooks() method on WooCommerceGallery, called whenever WooCommerce is active, independently of the Cloudinary gallery replacement toggle.

QA Instructions

Prerequisites

1. Ensure the Cloudinary plugin is installed, activated, and connected to a Cloudinary account.
2. Install and activate the WooCommerce plugin.

Generate a WooCommerce REST API key

1. In wp-admin, go to WooCommerce → Settings → Advanced → REST API.
2. Click Add key, give it a description (e.g. QA Test), set permissions to Read/Write, and click Generate API key.
3. Note the Consumer key and Consumer secret — they are shown only once.

Seed a Cloudinary image in the media library

The fix only prevents duplication when the image already exists in the WordPress media library as a Cloudinary-synced asset. Upload or import a Cloudinary asset into the media library via the Cloudinary plugin's media library sync so that it has the relevant post meta (_public_id, sync key) stored.

Take note of the full Cloudinary URL for that asset (e.g. from the media library's Cloudinary URL field, or from the Cloudinary console).

Test

Run the following curl request, substituting your own credentials, local domain, and Cloudinary image URL:

curl --location 'https://<your-local-domain>/wp-json/wc/v3/products' \
  --header 'Content-Type: application/json' \                                                                                                                   
  --insecure \
  -u '<consumer_key>:<consumer_secret>' \                                                                                                                       
  --data '{                                                                                                                                                     
    "name": "Cloudinary Duplicate Test",
    "type": "simple",                                                                                                                                           
    "regular_price": "10.00",
    "images": [                                                                                                                                                 
      {                                                                                                                                                         
        "src": "<your-cloudinary-image-url>"
      }                                                                                                                                                         
    ]           
  }'

After the request:

• In wp-admin, go to Media → Library and confirm a single attachment exists for that Cloudinary asset (i.e. the one you uploaded manually prior to the curl command, there should be no duplicate).
• Go to the list of products and confirm the latest product you just created via curl has the image associated to it.

[PatelUtkarsh]

Looks good!