Wix app APIs, SDKs and data handling

The Wix platform exposes a rich set of APIs and SDKs that your app can leverage to interact with every part of a Wix site: data, content, eCommerce, bookings, CRM, members, events and more. This lesson provides a comprehensive deep dive into the most important APIs, with practical examples showing how to use each one in your Wix app. Mastering these APIs is what separates basic apps from powerful, deeply integrated solutions.

The Wix SDK Landscape

Wix provides three layers of APIs for app developers. Understanding which to use and when is critical for building efficient, maintainable apps.

• Dashboard SDK (@wix/dashboard): Used in dashboard pages. Provides toasts, modals, navigation, page info and dashboard-specific utilities.
• Editor SDK: Used during the Wix Editor session. Lets your app respond to editor events, modify the page structure and configure widgets.
• Wix JavaScript SDK (@wix/sdk): The main SDK for data operations, authentication, CRM, eCommerce and all platform services. Used in both frontend and backend.
• REST APIs: HTTP-based APIs for server-to-server communication. Used when you need to call Wix from external services or webhooks.

Wix Data API: Database Operations

The Wix Data API is the most commonly used API in app development. It provides full CRUD operations on Wix database collections, including your app's custom collections and the site's existing collections (with appropriate permissions).

// Wix Data API - Complete CRUD example
import { items } from '@wix/data';
import { createClient, OAuthStrategy } from '@wix/sdk';

// Initialize the Wix SDK client
const wixClient = createClient({
  modules: { items },
  auth: OAuthStrategy({
    clientId: 'YOUR_APP_CLIENT_ID',
  }),
});

// CREATE - Insert a new item
async function createSeoReport(report) {
  const result = await wixClient.items.insertDataItem({
    dataCollectionId: 'SeoReports',
    dataItem: {
      data: {
        siteUrl: report.url,
        score: report.score,
        issues: report.issues,
        scannedAt: new Date().toISOString(),
      },
    },
  });
  return result;
}

// READ - Query items with filters
async function getRecentReports(siteUrl, limit = 10) {
  const result = await wixClient.items.queryDataItems({
    dataCollectionId: 'SeoReports',
    query: {
      filter: { siteUrl: { $eq: siteUrl } },
      sort: [{ fieldName: 'scannedAt', order: 'DESC' }],
      paging: { limit },
    },
  });
  return result.dataItems;
}

// UPDATE - Modify an existing item
async function updateReport(itemId, updates) {
  const result = await wixClient.items.updateDataItem({
    dataCollectionId: 'SeoReports',
    dataItemId: itemId,
    dataItem: {
      data: updates,
    },
  });
  return result;
}

// DELETE - Remove an item
async function deleteReport(itemId) {
  await wixClient.items.removeDataItem({
    dataCollectionId: 'SeoReports',
    dataItemId: itemId,
  });
}

Wix CRM and Contacts API

If your app needs to interact with the site's contacts, leads or members, the Wix CRM API provides everything you need. This is essential for marketing apps, lead generation tools and member management solutions.

• Query contacts: Search and filter the site's contact list by email, name, labels and custom fields
• Create contacts: Add new contacts programmatically (e.g., from form submissions or external imports)
• Update contacts: Modify contact information, add labels, and update custom fields
• Contact activities: Log activities against contacts for tracking engagement and interactions
• Labels and segments: Create and manage contact labels for segmentation and targeted marketing

Wix eCommerce API for Store Apps

The eCommerce API is one of the most powerful Wix APIs, providing access to products, orders, inventory, carts, checkout and more. If you are building a store enhancement app, this API is your foundation.

// Wix eCommerce API - Product operations example
import { products } from '@wix/stores';

// Query products with filters
async function getProductsForSeo(limit = 50) {
  const result = await wixClient.products.queryProducts()
    .limit(limit)
    .find();

  return result.items.map(product => ({
    id: product._id,
    name: product.name,
    slug: product.slug,
    description: product.description,
    seoTitle: product.seoData?.title || '',
    seoDescription: product.seoData?.description || '',
    images: product.media?.items?.length || 0,
    hasAltText: product.media?.items?.every(
      img => img.image?.altText
    ) || false,
  }));
}

// Check product SEO completeness
function auditProductSeo(product) {
  const issues = [];

  if (!product.seoTitle || product.seoTitle.length < 30) {
    issues.push('SEO title is missing or too short (min 30 chars)');
  }
  if (!product.seoDescription || product.seoDescription.length < 120) {
    issues.push('Meta description is missing or too short (min 120 chars)');
  }
  if (product.images === 0) {
    issues.push('Product has no images');
  }
  if (!product.hasAltText) {
    issues.push('One or more images are missing alt text');
  }

  return {
    ...product,
    seoScore: Math.max(0, 100 - (issues.length * 25)),
    issues,
  };
}

Wix Bookings and Events API

For apps serving service-based businesses, the Bookings API lets you interact with services, schedules, sessions and bookings. The Events API handles event management, ticketing and RSVPs.

• Services: List and query available services, their schedules and pricing
• Sessions: Access individual session slots, availability and booking status
• Bookings: Create, update and manage customer bookings programmatically
• Events: List events, manage tickets, track RSVPs and handle event registration
• Calendar: Access the site's calendar for scheduling and availability checks

Handling Webhooks and Real-Time Events

Webhooks let your app react to events happening on the Wix site in real time: new orders, updated contacts, published blog posts and more. This is how you build reactive, event-driven apps.

// src/backend/events/orders.ts
// Handle new order events from Wix Stores
import { orders } from '@wix/ecom';

export async function onOrderCreated(event) {
  const order = event.data;

  // Process the new order
  console.log('New order received:', order._id);

  // Example: Check if the order source page has good SEO
  const referringUrl = order.channelInfo?.externalOrderUrl;
  if (referringUrl) {
    await logOrderSource({
      orderId: order._id,
      source: referringUrl,
      value: order.totals?.total,
      timestamp: new Date().toISOString(),
    });
  }
}

// Handle order status changes
export async function onOrderUpdated(event) {
  const { previousOrder, currentOrder } = event.data;

  if (previousOrder.status !== currentOrder.status) {
    console.log(
      'Order status changed:',
      previousOrder.status,
      '->',
      currentOrder.status
    );
  }
}

Rate Limits, Pagination and Error Handling

Production Wix apps must handle API constraints gracefully. Here are the critical patterns you must implement.

• Rate limits: Wix APIs enforce rate limits per app instance. Implement exponential backoff for 429 responses.
• Pagination: Always use cursors or offset pagination for large data sets. Never assume all data fits in one response.
• Error handling: Wrap every API call in try/catch. Log errors with context (instance ID, operation, timestamp) for debugging.
• Caching: Cache frequently accessed data that does not change often. Use in-memory caching for the session or database collections for persistence.
• Timeouts: Set reasonable timeouts for API calls (10-30 seconds) and provide user feedback during long operations.

How to Use the Wix Data API to Build a CRUD Feature in Your App

Follow these steps to implement a complete data layer in your Wix app using the Wix Data API, from defining your collection schema to querying, writing and paginating data in production.

Implementing a robust Wix Data API layer in your app

• Step 1: Define your collection schema in wix.config.ts under the collections extension. Specify each field name, type (text, number, boolean, richText, dateTime, url, document), and set the permissions object to control who can read and write.
• Step 2: Import the items module from @wix/data and the createClient and OAuthStrategy functions from @wix/sdk at the top of your backend file. Initialise a wixClient with your app client ID.
• Step 3: Write a createItem helper function that calls wixClient.items.insertDataItem() with the dataCollectionId and a dataItem.data object. Wrap it in a try/catch that logs the error with the instance ID and operation name.
• Step 4: Write a queryItems helper using wixClient.items.queryDataItems(). Apply filter, sort and paging parameters. Return result.dataItems and the pagingMetadata.cursors.next value so callers can paginate.
• Step 5: Implement pagination in your dashboard page: store the cursor string in React state, pass it as a query parameter to the next page fetch, and disable the "Load More" button when no cursor is returned.
• Step 6: Write an updateItem helper using wixClient.items.updateDataItem(). Always fetch the existing item first, merge the updates, and include the existing _id and _rev fields to avoid overwrite conflicts.
• Step 7: Write a deleteItem helper using wixClient.items.removeDataItem(). Add a confirmation modal in your dashboard UI before calling delete to prevent accidental data loss.
• Step 8: Add an index to any field you filter or sort by frequently. In your wix.config.ts collection definition, add an indexes array with objects specifying fieldName and order (ASC or DESC) for each indexed field.
• Step 9: Implement in-memory caching for read-heavy data using a Map keyed by instanceId. Set a cache TTL of 60 seconds and clear the cache entry immediately on any write operation to prevent stale data.
• Step 10: Test your data layer with Wix dev mode: create, read, update and delete records using your dashboard UI, then verify the changes in the Wix CMS panel of the test site to confirm data persistence.

How to Integrate Wix eCommerce and CRM APIs Into Your App

Follow these steps to connect your Wix app to the eCommerce and CRM APIs, enabling store product analysis, order tracking and contact management within a single integrated dashboard.

Connecting your Wix app to eCommerce and CRM data sources

• Step 1: In wix.config.ts, add the required permission scopes for the APIs you need: WIX_STORES.READ_PRODUCTS and WIX_STORES.READ_ORDERS for eCommerce, and WIX_CRM.CONTACTS_READ for contacts. Only add scopes you will actively use.
• Step 2: Import the products module from @wix/stores in your backend service file. Add it to the wixClient modules object alongside your existing imports.
• Step 3: Write a getProductsForAudit function that calls wixClient.products.queryProducts().limit(50).find(). Map the result to a simplified object containing id, name, slug, seoTitle, seoDescription, images count and hasAltText boolean.
• Step 4: Write a auditProductSeo function that receives the mapped product object and returns an issues array and a numeric seoScore (starting at 100, deducting 25 points per issue found).
• Step 5: Import the contacts module from @wix/crm. Write a getContactsByLabel function using wixClient.contacts.queryContacts().hasSome("labels", [labelKey]).find() to retrieve segmented contact lists.
• Step 6: Handle pagination for both APIs: collect pagingMetadata.cursors.next from queryProducts and contacts queries. Build a fetchAll helper that loops until the cursor is null, collecting all results in an array.
• Step 7: Implement exponential backoff for rate-limited responses: catch errors with status 429, wait 2^attempt * 1000 milliseconds, and retry up to 3 times before throwing the error to the caller.
• Step 8: Build the dashboard UI to display product SEO audit results in a Wix Design System Table component. Add columns for product name, SEO score (colour-coded red/amber/green), and an expandable issues list.
• Step 9: Add a webhook handler in src/backend/events/ to respond to onProductCreated and onProductUpdated events. When a product is created or updated, automatically run the SEO audit and store the result in your app collection.
• Step 10: Test the full integration by installing your app on a test store with at least 10 products. Verify that all products appear in the dashboard, that score calculations are accurate, and that webhook events trigger the audit correctly.