VelvetPress/DocsDashboard →

Installing on a customer WordPress site

This guide is the customer-side counterpart to Publishing a plugin or theme. When the developer pushes a new release, this is what makes it show up in wp-admin.

Who this guide is for

You're a WordPress site administrator running a site that uses a plugin or theme distributed via VelvetPress. The developer has handed you a copy of the VelvetPress client plugin and a per-site API key, and you want updates to keep flowing into wp-admin without having to download zips yourself. After the one-time install in this guide, the client plugin handles fetching and installing every future release, and they all surface in one place: Dashboard → Updates, WordPress's native update flow. The walkthrough is in What it looks like when an update lands.

If you're the developer shipping the plugin or theme, you want Developer onboarding and Publishing a plugin or theme instead.

Prerequisites

  • A WordPress site (6.0 or newer, PHP 7.4 or newer) where you have an admin login.
  • The VelvetPress client plugin zip from the developer. This is the small PHP plugin that lives at plugins/velvetpress/ in the VelvetPress repo — the developer either sends it to you directly or links you to a download.
  • A per-site API key from the developer. It's a single opaque string, generated in the VelvetPress dashboard when the developer added your site. Treat it like a password.

You don't need a VelvetPress account of your own. The API key is what identifies your site to the backend.

Install the VelvetPress client plugin

The client plugin is what makes WordPress aware that some of its themes and plugins are managed by VelvetPress. Install it once per site.

  1. In wp-admin, go to Plugins → Add New and click Upload Plugin at the top of the page.
  2. Choose the velvetpress.zip file the developer gave you and click Install Now.
  3. When the install finishes, click Activate Plugin.

WordPress drops you back on the Plugins list with VelvetPress active. The plugin registers a single admin page at Settings → VelvetPress — that's where everything else in this guide happens.

Enter the API key and connect the site

Open Settings → VelvetPress. You'll see a single API Key field and a short explainer.

  1. Paste the API key the developer gave you into the API Key field.
  2. Click Save Changes.

Saving does two things. First, it stores the key in your WordPress database (in the velvetpress_settings option). Second, it fires a registration call to the VelvetPress backend that tells it "this site, on this domain, is alive, with this WordPress version and this active theme." The registration runs every time you save the settings page, so you can re-save to force a re-register if anything ever looks out of sync.

Confirm the connection is live

After saving, the page reloads with a status badge next to the VelvetPress heading. The badge starts as Checking... while the plugin pings the backend, then settles into one of:

  • ✓ Connected — the key is accepted and your domain matches what the developer registered. You're done.
  • ✗ Error — the backend reached your key but rejected it. A common cause is a domain mismatch: the developer registered the site for example.com and your WordPress is actually serving from www.example.com or staging.example.com. Ask the developer to add the domain you're actually on.
  • ✗ Offline — the request didn't reach the backend at all. Check the site can reach the public internet and that no firewall is blocking api.velvetpress.dev.

Below the badge, a collapsible Debug Info panel shows the environment, site name, domain, and active theme slug the plugin is reporting. Open it if you need to confirm exactly what's being sent.

Locking the key down (optional)

If you'd rather not store the key in the database — useful on multisite or when you keep secrets in wp-config.php — define it as a constant before /* That's all, stop editing! Happy publishing. */:

define( 'VELVETPRESS_API_KEY', 'your-api-key-here' );

When the constant is set, the API Key field on the settings page becomes read-only and shows "Set via wp-config.php constant." The constant always wins; the database value is ignored.

There's a matching VELVETPRESS_API_URL constant for pointing at a non-production backend; you almost never need it.

What it looks like when an update lands

Once the site is connected, every VelvetPress-managed product on the site — your active theme, the VelvetPress client plugin itself, and anything you installed through Available Products — sends its updates through the same place: Dashboard → Updates, WordPress's native update flow.

WordPress checks for plugin and theme updates on its own schedule — typically once every twelve hours, plus whenever you load Dashboard → Updates. When that check runs, the VelvetPress client plugin reports every VelvetPress-managed product on the site — the active theme, the client plugin, and anything installed via Available Products — and asks the VelvetPress backend whether there's a newer release for any of them.

If any has a newer version, you'll see it the same way you'd see any other WordPress update:

  • Dashboard → Updates — the product appears in the Plugins or Themes section with a checkbox and an Update Plugins / Update Themes button.
  • Plugins or Appearance → Themes — the row shows a "There is a new version available" notice with an update now link.

Click either one. WordPress fetches a short-lived download URL from VelvetPress, downloads the release zip, and runs the standard upgrade routine. There's no separate VelvetPress UI for installing these updates — it's the same flow you already know.

This is wired up through the open-source plugin-update-checker library bundled with the client plugin — the same library a lot of premium WordPress plugins use. You don't have to configure it; it just runs. (See plugins/velvetpress/includes/update-checker.php and self-update.php if you're curious about the wiring.)

If you don't want to wait for the next scheduled poll — for example, the developer just told you a fix is published — go to Dashboard → Updates and click Check Again at the top of the page. WordPress re-polls every update source, including VelvetPress.

Installing a new plugin or theme via Available Products

The Settings → VelvetPress → Available Products list is the install UI: it's where you go the first time you want to add a plugin or theme the developer has shared with you. After that one-time install, the product is on the site like any other WordPress plugin or theme and its updates flow through Dashboard → Updates with everything else.

To install a new product:

  1. Open Settings → VelvetPress and scroll to Available Products. It lists every plugin and theme your API key has access to.
  2. Click Install on the row for the product you want. The client plugin downloads the release and copies it into place — no extra confirmation.
  3. The product now appears in the standard WordPress UI (Plugins or Appearance → Themes) and any future updates show up under Dashboard → Updates.

Troubleshooting

Most issues fall into one of these:

  • "I don't see the update." Go to Dashboard → Updates and click Check Again at the top of the page to force an immediate poll. If the new version still isn't there: confirm the status badge at the top of Settings → VelvetPress says ✓ Connected, and ask the developer whether they actually pushed and whether the build finished (they can see this in the VelvetPress dashboard).
  • Activation failed. WordPress shows the error on the Plugins screen. The client plugin needs PHP 7.4 or newer and WordPress 6.0 or newer; if you're below either, upgrade WordPress / PHP first.
  • Wrong site is registered. If the status badge shows ✗ Error with a "domain mismatch" reason, the developer registered your site under a different hostname than the one you're serving from. Ask them to add the hostname shown in Debug Info to the site's allowed domains in the dashboard, then save the settings page again to re-register.
  • Status badge stays on "Checking..." or shows ✗ Offline. Your server can't reach api.velvetpress.dev. Check outbound connectivity and any firewall or proxy in front of the site.
  • Update downloaded but installation failed. The download URL is pre-signed and expires after a few minutes; this almost always means the zip was stale by the time WordPress tried to use it. Click Check Again on Dashboard → Updates and retry the update.

For raw API responses, the exact request/response shape of each endpoint the client plugin uses, and a one-line curl you can paste to confirm the backend side, see the Update manifest reference.

What's next

  • Quick Start — the five-minute version of the end-to-end flow, useful if you also run a development site.
  • Publishing a plugin or theme — the developer side. Read this if you want to know what's happening on the other end when an update appears.
  • Update manifest reference — wire-level details of the endpoint your site polls, with curl examples and a four-step troubleshooting checklist.