Setting up Oyster for WooCommerce

Everything on the Oyster side is reached with a credential that belongs to this site, created when you connect and retired when you disconnect. No API key is ever pasted into wp-admin, and the only key that reaches a shopper's browser is the widget public key, which identifies your account without authorising anything on its own.

This guide covers the plugin. If you want to embed the widget by hand on a site that is not WordPress, see the Web SDK docs; for an iOS or Android app, see the mobile guide.

Steps 1, 2, 4 and 5 are the same for everyone. Step 3 is where the two setups diverge, so read the one that is yours and skip the other. Sections that apply to only one path are labelled, here and in the sidebar.

Doing both is supported and needs no decision here: follow the store path for your catalogue and the treatments section as well. Oyster matches each scan against whichever of the two you have enabled.

You do not need a widget public key, an API key, or a list of allowed domains. Connecting creates all three for you, and re-connecting refreshes them.

The plugin is not on the WordPress.org directory yet, so it installs from a zip rather than from the Plugins search. Updates arrive on your Plugins screen afterwards the same way every other plugin's do.

1. Download the plugin from the latest release. Take the oyster-woocommerce.zip asset, not the "Source code" archive, which carries files your site does not need. That link always resolves to the current version, so it is worth bookmarking. It is also linked from Apps in your Oyster dashboard.
2. In wp-admin, go to Plugins → Add New Plugin → Upload Plugin, choose the zip and install it.
3. Activate it. A new Oyster menu appears below WooCommerce.

# Or from the command line, if you have WP-CLI
wp plugin install https://github.com/oysterai/oyster-woocommerce/releases/latest/download/oyster-woocommerce.zip --activate

Go to Oyster → Connection and log in with your Oyster vendor email and password. Connecting produces a credential this site keeps using, so Oyster then emails you a six-digit code to confirm it is really you. Nothing is written to your site until you enter it, and a login you abandon leaves no trace.

1. Enter your Oyster email and password, then Connect.
2. Enter the code from your inbox, then Finish connecting. The code lasts about ten minutes and works once.
3. The screen turns into a green "Connected to Oyster vendor" panel with a setup checklist under it.

Connecting does four things on your behalf: it records this site on your vendor account, makes sure the account has widget keys, adds this site's address to your allowed domains, and registers the address Oyster sends scan events to. That is why there is nothing to copy.

When a code is refused

The setup checklist, and the scan-event line

The connected screen carries a Get set up with Oyster checklist that tracks the remaining steps from your real settings, so it ticks itself off as you go. Dismiss it when it is complete.

Under the connection status is a line about scan events and the address they are delivered to. Nobody types that address: it is there to be checked. If it ever says this site now answers somewhere else, your domain changed after you connected, and events are going to the old address. Reconnect to update it.

Open Oyster → Catalog. Pick a scope, save it, then press Sync now for the first import.

Categories and tags combine with OR inside whichever list is active: a product matches if it carries any of the terms you ticked, from either taxonomy. Variations have no terms of their own in WooCommerce, so each one is judged by its parent product.

What syncs, and when

• Published simple and variable products only. Drafts, private products, grouped products and external products are never sent.
• A product needs a name and a price to be accepted. One without either is skipped rather than sent and rejected.
• Saving a product re-syncs it on its own, scoped to whatever you chose here. You do not need to press Sync now after an ordinary edit.
• Sync now is for the first import, and for forcing a full re-sync after a bulk change made by a tool that does not fire WooCommerce's usual save hooks, which some CSV importers do not.

A full import runs in the background in batches and reports created, updated, claimed and failed counts as it goes. Refresh the screen to watch it. A large catalogue takes a few minutes.

Products that did not sync

If Oyster rejects anything, a red panel lists the products by name with the reason beside each and a link straight to the editor. Fix the product and save it, which re-syncs it, or use Sync now to retry them all. The panel lists the twenty most recent and links to the full filtered list when there are more.

Price, stock, images, brand, primary category and weight all sync on their own. Three things only you know, and they are what moves a recommendation from plausible to right. All three are on the product edit screen and all three sync with everything else.

All three are available to the WooCommerce product CSV importer, so a large catalogue can be filled in one pass rather than product by product.

Treatments are not a WooCommerce concept and none of this happens in wp-admin. Your procedures live in the Oyster dashboard, Oyster matches each scan against them, and the widget shows the matches to the customer. There is no catalogue to sync and no product to create.

1. Have treatment recommendations enabled on your account. Contact [email protected] to ask for it. Until it is enabled, the Treatment Recommendations card described below does not appear on your dashboard, which is the quickest way to tell where you stand.
2. Add your procedures in the Oyster dashboard under Procedures. Each one carries the detail Oyster matches a scan against. You can add them one at a time or import a list.
3. Turn on "Show treatments to customers" in the dashboard under Settings → Scan Settings, in the Treatment Recommendations card. This defaults to off. Your own team always sees matched treatments on the scan report; this switch is what adds them to the widget results and the scan-result email that reaches the customer.
4. Turn off "Recommend products after a scan" in the same screen, in the Product Recommendations card. See the warning below for why this matters.

Customers only ever see the procedures you have added. Nobody is told to ask for a treatment you do not offer, so an empty Procedures list means an empty treatments section however the rest is configured.

What you can skip

Oyster → Catalog in wp-admin does not apply to you. You can leave it untouched: the default scope syncs nothing, so there is no switch to turn off and no import to avoid. The same goes for the ingredients, Skin Type and size fields on products, and for the order attribution that credits a product sale back to a scan.

Everything else in this guide does apply. Carry on at Put the scan on your site.

All four read the same settings and show the same scan. Use as many as you like. Everything here is under Oyster → Widget.

The scan page

This builds a real page at /skin-analysis titled "AI skin analysis", with a headline, a three-step explainer, the scan and an FAQ. It is an ordinary page, editable like any other, so change the copy to suit you. It starts out unlisted: search engines, your site's own search and auto-generated menus all skip it, so only people with the link reach it. Press Make it discoverable when you want it treated like any other page. You can add it to a menu yourself either way.

Launcher settings

Blank and zero are different answers for the offsets, which is why they are not pre-filled. Blank leaves the widget its own margin; 0 pins the launcher flush to the corner.

Layer arrives in a plugin release newer than 0.21.0. The same control is already on your dashboard, under Widget Manager, as Widget layer (z-index), and it applies to your storefront whether or not the field has reached wp-admin yet. Note that zero is not an answer here, unlike the offsets: the launcher sits one layer below the panel it opens, so the lowest the widget accepts is 1.

Where the scan deliberately does not appear

The scan payment page carries a body class you can target, if your own site greets visitors with a popup or banner you would rather hide there:

body.oyster-scan-payment .newsletter-modal { display: none; }

A scan can be free, paid to Oyster, or paid to you. Open Oyster → Scan payments and the screen tells you which of those you are on, because it is set on your Oyster account rather than here.

When you collect, a shopper who starts a paid scan is sent to your checkout to pay for it, and the scan is released the moment the order is marked paid. What they pay, and any scan pack you sell, are set on your Oyster dashboard and read from there. There is no price field in wp-admin, so a change you make on the dashboard takes effect without a plugin update.

Choosing which methods a scan may use

Tick the methods a scan may be paid with. Only methods your checkout already has enabled are listed, so an absence here means WooCommerce is not offering it, not that the plugin does not support it. Ticking nothing offers every enabled method, which is the behaviour every store had before this setting existed.

If every method you ticked is later disabled in WooCommerce, shoppers have no way to pay for a scan. The screen raises an error the moment that state exists, so it is worth revisiting after any change to your gateways.

Applies to stores collecting scan payments through their own checkout. A scan is delivered the moment the order is marked paid, and it cannot be taken back. Allow a scan to be paid for only with methods that actually capture money at that point.

For a physical order an offline method is a promise you can chase: goods are not shipped until the money arrives, so a cheque that never clears costs you postage at worst. A scan gives up its value immediately. The order reaches a paid state, the scan is released, the shopper takes it, Oyster runs the analysis, and Oyster bills you for it. There is no parcel to hold back.

Offline methods are genuinely useful while you are testing on a staging site, which is why this is a choice rather than a ban. Run one real scan payment yourself on the live store and confirm the money arrived at the gateway, not just that the order says paid.

The plugin runs inside WordPress, so it writes your widget configuration into the page as an inline script and prints the launcher's markup into the footer. Both are part of the HTML your server generates. A full-page cache stores that HTML and serves the stored copy to the next visitor, so a copy made before you configured the plugin has no launcher in it and will keep being served until it is purged.

The tell: caches almost always bypass logged-in users, so the signature is that the launcher shows for you as an administrator and not for a logged-out visitor, or shows on a page you just edited and nowhere else. Always confirm in a private window, logged out, before concluding anything.

The layers to clear

There is usually more than one, and clearing a single layer is the common reason a purge appears not to work.

When to purge

• After turning the launcher on, or changing its colour, copy, logo, position, layer or auto-open setting.
• After connecting or reconnecting, because the widget public key in the page changes.
• After creating the scan page, or making it discoverable.
• After adding the block or shortcode to an existing page.
• After updating the plugin.

Pages that should never be cached

Standard WooCommerce practice, and most caching plugins do it by default, but worth verifying on a store taking scan payments: cart, checkout and account pages; the pay page for an order, which is where a shopper pays for a scan; and the plugin's routes under /wp-json/oyster-woocommerce/. Those are POST requests, which most caches skip on their own, but an aggressive edge rule needs an explicit bypass.

If purging does not fix it

Open a page in a private window, view source, and search the HTML for OysterWooConfig and data-oyster-widget.

Optimisation features that combine, defer or delay JavaScript can separate the inline configuration from the loader script, or postpone the loader past the point where it looks for anchors. If the markup is in the page but the widget never boots, exclude the plugin's loader script and its inline configuration from those features, then purge again.

Recommended products add straight to your WooCommerce cart, and a resulting paid order is credited back to the scan that drove it in your Oyster dashboard. Two things make that work, and only the second needs anything from you.

• A shopper who checks out from inside the scan carries the scan with them.
• A shopper who finishes a scan, closes the widget and buys later through your ordinary pages is matched by a first-party cookie, so those sales count too. Every paid order containing a product you have synced is reported, which also credits a shopper Oyster already recognises from a different device.

A purchase is only ever credited when the order contains something that scan recommended. Orders made up entirely of products you have not synced are never sent at all, since nothing in them could be attributed. Attribution applies to orders placed from the moment you install onwards: an order already in your store cannot be credited retrospectively, because nothing recorded a scan against it at the time.

What an order carries, and what leaves your site

An attributed order stores a batch id, a routine id and a widget attribution id, all opaque identifiers, plus a note when the scan was matched from the browser rather than from a checkout started in the widget. They are included in WordPress's own Tools → Export Personal Data and Tools → Erase Personal Data requests alongside the rest of that order.

Once an order is paid, what Oyster receives is the order id and number, its line items, totals and currency, the billing email, and those scan identifiers. The email is used only to look up a shopper who has already scanned with you. It does not create an account, and an order Oyster cannot attribute is discarded.

Two actions fire when Oyster reports on a scan at this store. They arrive as signed server-to-server requests, so they fire whether or not the shopper still has your site open. A repeated delivery fires once, though a handler should be safe to run twice anyway.

add_action( 'oyster_woocommerce_scan_completed', function ( $batch_id, $event ) {
    // Fires when a scan has finished analysing.
    // $event['data'] carries batch_id, vendor_id and channel.
}, 10, 2 );

add_action( 'oyster_woocommerce_recommendations_ready', function ( $batch_id, $event ) {
    // Fires when that scan's routine is ready.
}, 10, 2 );

Neither action carries the skin analysis. That is deliberate: a customer's results are not copied into your site's logs or handed to anything you hook up later. To read the detail, ask Oyster for it with this store's own connection, which never exposes the credential:

$result = apply_filters( 'oyster_woocommerce_api_get', null, $path );
// Decoded response body, or a WP_Error carrying the HTTP status.

$path is the Oyster API path you want. Ask support which one answers the question you are asking, and whether your account can read it.

Nothing to configure for any of this: the callback is registered when you connect and removed when you disconnect, and access ends with it. Your site does need to be reachable over HTTPS from the internet. Oyster → Connection shows when the last event arrived.

Three URLs can be repointed, for building against a sandbox account. Each is read from a wp-config.php constant and nothing else.

A value is accepted over https only on Oyster's own domains, and over http only on a loopback host for a local tunnel. Anything else is rejected and logged, and the default is used. Ask us for the sandbox values rather than guessing them, since accounts and keys are not shared between environments.

None of the three is filterable, and that is on purpose. A WordPress filter has no permission model, so any active plugin or theme could hook one and silently redirect API traffic, swap in a script that runs on every visit, or repoint an admin's dashboard link at a lookalike page. wp-config loads before any plugin code, which a normally-installed plugin cannot race.

The plugin checks its own releases and offers updates on your Plugins screen the way a directory-hosted plugin would, so there is no second zip to upload after the first one. Auto-updates can be enabled for it from the same screen.

Deactivating stops the widget showing and stops sync, and leaves your connection and settings in place for when you activate it again. Deleting removes them. Your products, scans and history stay in your Oyster account either way.

Purge your caches after an update, for the reasons in Caching and the launcher.

• Connected, with a green panel and no widget-key warning.
• Scan events confirmed arriving, and the address on the Connection screen matching your live domain.
• Catalogue scoped and imported, with the failures panel empty. Stores
• Ingredients, Skin Type and size filled in on at least your best sellers. Stores
• Treatments enabled on your account, your procedures added, and "Show treatments to customers" on. Clinics
• Product recommendations off, so no sample products are recommended. Clinics
• Placement chosen, and verified in a private window while logged out.
• Caches purged at every layer, including your CDN.
• Launcher position checked on a phone as well as a desktop, against your own chat bubble and cookie banner.
• Payment methods for scans limited to ones that capture money up front, with one real payment tested end to end.
• Consent banner listing oyster_scan_batch, if you run one.
• One full scan run on the live site, start to finish, by you.

Something not covered here, or behaving differently from what this says? Mail [email protected] with your store URL and what you were doing, and we will take a look.