Epox Connector for WooCommerce

This plugin is the store-side half of the Epox integration. Install it on your WooCommerce
store and Epox can publish generated images and video straight into your products, reusing
the WooCommerce API key you have already issued — there is nothing extra to configure.

It exists because the generic WooCommerce product endpoint cannot express what the
integration needs. Without this plugin, publishing one image takes three round trips
(upload, attach, verify) and WooCommerce re-downloads the file itself, which fails on some
hosting stacks and can leave duplicates behind on a retry. With it, the whole operation
happens once, on your server, in a single transaction.

What it adds:

• One call per sync. Download, media-library registration, gallery placement and
  metadata all happen server-side in one request.
• Safe retries. Every media item carries an idempotency key. If Epox retries a sync,
  the plugin returns the attachment it already created instead of importing a second copy.
• All-or-nothing. If any part of a sync fails, attachments created during that request
  are removed. A failed sync leaves no orphans in your media library.
• Video support. Product video can be imported and linked to your gallery plugin’s
  metadata, which the standard WooCommerce product API has no way to express. The video file
  itself can be imported into your media library — not just referenced by URL — verified
  against “WooCommerce Gallery Slider” (gallery-slider-for-woocommerce, formerly WooGallery).
• Variation images. One generated image can be assigned across several variations
  without importing it more than once.

Endpoints

Management routes live under epox/v1 and authenticate with your existing WooCommerce
Read/Write API key. The shopper-facing Try-On permit exchange is same-origin and returns only a
short-lived permit, never a WooCommerce key or server-held bridge credential.

• GET /wp-json/epox/v1/status — reports the plugin version and capabilities.
• POST /wp-json/epox/v1/media-sync — import media and attach it to a product or its variations.
• POST /wp-json/epox/v1/media-detach — remove synced media from a product.
• POST /wp-json/epox/v1/tryon-bridge — Epox-only setup of the server-held Try-On bridge.
• GET /wp-json/epox/v1/tryon-bridge — Epox-only read-back of the bridge’s issuer and staleness
  (never the credential), so a drifted or stale bridge can be repaired without waiting for a
  shopper’s permit request to fail first.
• POST /wp-json/epox/v1/tryon-permit — product-page request for a short-lived Try-On permit.
• POST /wp-json/epox/v1/tryon-visibility — Epox-only batch sync of the per-product
  epox_tryon_enabled visibility marker (yes / no).

1. Upload the plugin zip via Plugins → Add New → Upload Plugin, or extract it into
   wp-content/plugins/.
2. Activate Epox Connector for WooCommerce. WooCommerce must already be active — WordPress
   will tell you so and block activation otherwise.
3. In Epox, connect the store as usual using a WooCommerce API key with Read/Write
   permissions. Epox detects the connector automatically.

There are no settings screens. If the plugin is deactivated, Epox falls back to the
standard WooCommerce API and keeps working. Deleting the plugin removes only its own
settings — media it has already imported into your library is never touched.

For secure Try-On, Epox configures a server-only bridge automatically through the same
WooCommerce key you already connected. Your product page requests a short-lived permit from this
plugin and passes it to the Try-On iframe; neither your WooCommerce key nor the bridge credential
is exposed in browser code.

Do I need a separate API key or password?

No. The plugin registers its routes with WooCommerce’s own authentication, so the
consumer key and secret you already gave Epox authorise these endpoints too.

What permissions does it require?

The API key’s user must be able to edit products (shop manager or administrator, with a
Read/Write key). Every request is also checked against the specific product being changed.

My gallery plugin shows videos from a custom field. Will this work?

Probably, and if not it is one filter away. The plugin writes the video URL to its own
_epox_video_url field plus a configurable list of third-party keys — wcgs_video and
_product_video_url by default. To target a different key, add to the
epox_video_meta_keys filter or set the epox_video_meta_keys option.

wcgs_video is not a guess: it is the exact key "WooCommerce Gallery Slider" reads off the

gallery image’s own attachment (get_post_meta( $image_id, 'wcgs_video', true )), confirmed
against that plugin’s real source.

Does the video need to already be hosted somewhere, or can Epox upload it here?

Either. Send video_url (a string) to point at an already-hosted video — nothing is
downloaded, the URL is written to your gallery plugin’s meta as-is. Send video (an object
with a url) to have this plugin import the video file itself into your media library, the
same way it imports images, then write that attachment’s own URL as the meta value. The
two are mutually exclusive on one media item.

Will it delete my own product photos?

No. Removal only ever deletes files this plugin imported; anything you uploaded yourself
is detached from the product but left in your media library.

Can it fetch media from anywhere on the internet?

Only over HTTPS, and only from public hosts — WordPress’s own URL safety checks apply. To
restrict it further to specific hostnames, use the epox_allowed_media_hosts filter.

1.2.1

• Security: the Try-On bridge now only accepts an Epox platform origin (app.epox.ai,
  platform.epox.ai) as its issuer. Previously any API key able to edit products could point
  the storefront’s Try-On loader script at an arbitrary host. Developers testing against another
  Epox origin can add it with the epox_tryon_allowed_issuer_hosts filter from code.

1.2.0

• Epox now records, on each product, whether Try-On is enabled for it under your visibility
  settings (product meta epox_tryon_enabled, yes or no). [epox_tryon] is opt-in and renders
  only when epox_tryon_enabled is yes, so products marked no or not yet opted in never make a
  permit request — and your theme can read the same value to adjust the page. Epox still checks its
  own policy on every shopper request.

1.1.7

• Adds a read-only GET /wp-json/epox/v1/tryon-bridge status endpoint (issuer origin and
  staleness, never the credential), so Epox can detect a Try-On bridge this store no longer holds,
  has retired as permanently rejected, or that points at a different Epox environment — and repair
  it automatically when your Try-On settings page loads, instead of waiting for a shopper’s
  request to fail first. In particular, reinstalling this plugin no longer needs a manual
  re-save in Epox: the bridge re-provisions itself on the next settings load.

1.1.6

• The Try-On widget now hides itself on your storefront whenever it cannot load, instead of
  showing shoppers an error they cannot act on. Nothing is lost: when you are logged in with
  permission to manage the store, the same failure is spelled out in place — what happened, what
  to do about it, and a note that your customers see none of it.
• That answer is computed on the permit request, not baked into the page, so a full-page cache
  warmed by an admin can never show the diagnostic message to a shopper.
• Forwards the platform’s new “store is not connected to a workspace” code.

1.1.5

• A permit rejection that can never succeed on retry — the platform does not recognise this
  store’s widget key, or the bridge credential has been rotated away — now retires the stored
  bridge instead of failing every storefront request forever. [epox_tryon] renders nothing
  until Epox reconfigures it (re-enable Try-On in your workspace), rather than showing shoppers
  an error only you can fix.
• Logs the issuer’s status and error code to the PHP error log under WP_DEBUG, so a broken
  Try-On install can be diagnosed from the store instead of guessing at a generic 503.

1.1.4

• [epox_tryon] now forwards specific “widget disabled” / “out of try-on credits” errors from
  the platform instead of collapsing every failure into a generic unavailable message — lets the
  storefront loader hide the widget silently in those expected cases rather than showing an error.
• Reserves the widget’s aspect ratio up front to avoid a layout shift once it mounts.

1.1.3

• Adds the [epox_tryon] shortcode. Place it anywhere — product description, a text widget,
  a page builder’s shortcode block — and it renders the storefront widget itself; the workspace’s
  publishable widget key is stored server-side at enable-time and never needs to be copied.

1.1.2

• Adds the server-side Try-On permit bridge for connected stores. Epox configures the connector
  through its existing authenticated API; storefront code receives only a short-lived permit.

1.1.1

• media-detach with delete_files now also removes the video file an imported thumbnail
  points at. Previously only the thumbnail itself was deleted, orphaning the raw video
  attachment in the media library on every video removal.

1.1.0

• media-sync items accept a video object (in addition to the existing video_url
  string) to import the video file itself into the media library — not just reference an
  already-hosted URL — then write the imported attachment’s own URL as the video meta.
  Idempotent and rolled back atomically along with its thumbnail, same as everything else.
  New video_upload capability reported by status.

1.0.0

• Initial release: status, media-sync and media-detach endpoints, idempotent media
  import, atomic rollback, video metadata bridging and variation image assignment.