Wix API Integration: Auth, Webhooks and the Catalog V3 Trap

What Wix API integration covers

A Wix API integration is code that reads or writes Wix data (products, orders, contacts, bookings) through Wix's REST API or JavaScript SDK, or reacts to Wix events through webhooks. It can run on the Wix site itself, on your own server, or inside an app installed on other people's sites.

Where the code runs decides how it authenticates, and that choice shapes everything else. Wix's own documentation splits it into five paths:

Most "connect my Wix store to another system" projects land in the last two rows. Decide which one you are in before writing any code, because the credentials, token lifetimes and permission model all differ.

OAuth or API key: which Wix authentication to use

Wix supports OAuth and API keys for code that runs outside the Wix dashboard, editor or site. They are not interchangeable.

The rule of thumb for real projects: if the integration will be installed by more than one merchant or listed in the App Market, build an app and use OAuth. If it connects one business's Wix site to that same business's ERP, warehouse or marketplace tooling, a scoped API key is the shorter path, with a headless project's client credentials as the alternative when you only need admin access to that project's own site.

Treat an API key like an account password. Restrict it to the narrowest set of sites and scopes the integration needs, keep it in a secrets manager, and remember that site-level calls only work with keys generated from the account that owns the site. If you are doing this for a client, they will need to create the key, because only account owners and co-owners can.

How to get a Wix access token with client credentials

For admin operations in a headless project, the client credentials grant exchanges your OAuth client ID and secret for a short-lived token. Run it only in backend code. The secret is shown once when you generate it in Headless Settings, so store it immediately.

The token endpoint is https://www.wixapis.com/oauth2/token, and the response includes an expires_in of 14400 seconds. Do not request a new token on every call. Cache it and renew shortly before expiry:

let cached = { token: null, expiresAt: 0 };

async function getWixToken() {
  const now = Date.now();
  if (cached.token && now < cached.expiresAt - 5 * 60 * 1000) {
    return cached.token;
  }
  const res = await fetch('https://www.wixapis.com/oauth2/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      grant_type: 'client_credentials',
      client_id: process.env.WIX_CLIENT_ID,
      client_secret: process.env.WIX_CLIENT_SECRET
    })
  });
  if (!res.ok) throw new Error('Wix token request failed: ' + res.status);
  const data = await res.json();
  cached = { token: data.access_token, expiresAt: now + data.expires_in * 1000 };
  return cached.token;
}

async function wixPost(path, body) {
  const token = await getWixToken();
  const res = await fetch('https://www.wixapis.com' + path, {
    method: 'POST',
    headers: { 'Authorization': token, 'Content-Type': 'application/json' },
    body: JSON.stringify(body)
  });
  return res.json();
}

Note that the token goes into the Authorization header exactly as returned, with no extra prefix. An API key is sent in the same header. If a call returns 401, the token has most likely expired, so a renew-and-retry-once wrapper around wixPost is worth adding.

Wix Stores Catalog V1 vs V3: the trap in most integrations

This is where store integrations quietly break. Wix Stores has two product catalog APIs, and a given site is on one or the other. According to Wix's Catalog Versioning documentation, the two versions are not backwards compatible, all sites will eventually move to V3, and you should call the GetCatalogVersion endpoint at the beginning of each flow to know which API to use. Each version also fires its own webhooks, so an integration that must serve every site subscribes to both V1 and V3 events.

Wix's migration guide also states that there is no automatic migration path and that an app must support both versions to be installable by new and existing sites. The differences that matter in practice:

The expensive mistake is writing against V3 because it is newer, then discovering a merchant's store is still on V1, or the reverse. Put an adapter between your business logic and Wix so that the version check happens once:

// One interface, two implementations. Business logic never sees the version.
const catalog = (await isCatalogV3(siteAuth))
  ? new CatalogV3(siteAuth)
  : new CatalogV1(siteAuth);

const products = await catalog.listProducts();
const stock = await catalog.getStock(productId);

The V3 stock and variant split is the part that costs the most rework: what used to be one product read becomes a product query, a variants query and an inventory search. If you would rather not maintain two code paths yourself, this is the kind of work our Wix and ecommerce platform integration service covers.

How to handle Wix webhooks without losing events

Wix sends webhook data as a signed JSON Web Token in the request body, and you verify it with the public key from the Webhooks page of your app dashboard. The behavior below comes from Wix's webhooks documentation:

• Your endpoint must return HTTP 200 within 1250 ms, or Wix treats the delivery as failed.
• On failure, up to 12 additional attempts follow on a retry schedule.
• A resent webhook can arrive after a newer one that succeeded first time, so events can be delayed and out of order.
• Webhooks do not always carry the full entity, and Wix recommends designing for duplicate events.
• Sites on older major versions of your app do not receive newly added webhooks.

A 1250 ms window leaves no room for database writes or follow-up API calls. The handler should verify the signature, hand the event to a queue, and return 200. Nothing else:

import express from 'express';
import jwt from 'jsonwebtoken';

const app = express();

app.post('/webhooks/wix', express.text({ type: '*/*' }), function (req, res) {
  let event;
  try {
    event = jwt.verify(req.body, process.env.WIX_APP_PUBLIC_KEY, {
      algorithms: ['RS256']
    });
  } catch (err) {
    return res.sendStatus(401);
  }
  queue.add(event); // your own job queue: parse and process later
  res.sendStatus(200);
});

If you build with the Wix CLI, event extensions handle the payload for you, so this handler is only needed for self-hosted apps. The Logs tab on the Webhooks page of the app dashboard shows every delivery and is the first place to look when events seem to be missing.

A sync pattern that survives retries and outages

Because deliveries can repeat, arrive late or arrive out of order, a handler that says "stock changed, subtract 1" will drift. Wix's payload is a signal that something changed, not a ledger. This pattern holds up:

1. Acknowledge fast. Verify, enqueue a small job (event type and entity ID), return 200.
2. Re-read, do not trust the payload. The worker fetches the current entity from the Wix API, so the state it writes is always the latest one.
3. Upsert on the Wix entity ID. Running the same job twice must produce the same result.
4. Reconcile on a schedule. Wix itself recommends periodic API requests to confirm webhooks are accurate. A nightly query of recently changed products or orders catches anything a webhook missed.
5. Cap concurrency and back off on HTTP 429. Bulk imports are where integrations trip over request limits.

Steps 2 and 4 are the difference between an integration that works in a demo and one that stays correct for months.

Wix API errors and what causes them

Build it in-house or hire it out

A one-directional, read-only export from a single Wix store, owned by a team with a backend developer, is a reasonable in-house project. The picture changes when any of these is true:

• The sync is two-way (orders in, stock and tracking out) across marketplaces, an ERP or a warehouse system.
• More than one Wix store is involved, so you will meet both catalog versions.
• Nobody on your side wants to own webhook reliability, token handling and reconciliation long term.

Before you brief anyone, write down five answers: which direction data flows, which entities are involved (products, orders, customers), which catalog version each store is on, who owns the Wix account that can create an API key, and what should happen when a sync fails at 3 a.m. Those five answers are most of the scope.

If you want a second opinion or a build quote, request a free quote for your Wix integration with your store, the system you need to connect and the data involved. Pricing is set to scope.