A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Wix API is how an app or AI agent works with a Wix site: querying the store catalog, recording an order, adding a contact, listing members, or storing data in a content collection. Access is granted either through an installed app that holds OAuth permissions a site owner approved, or through an account API key carrying an assigned set of permissions, and each call is scoped to one site. Wix versions each business area on its own track, and it can push an event to a registered app when something on the site changes.
How an app or AI agent connects to Wix determines what it can reach. There is an installed app that authenticates with OAuth, an account-level API key for direct calls, and a hosted server that exposes Wix tools to agents, and each is governed by the permissions behind it and the site it is called against.
The REST API is organized by business area, each at its own base path under https://www.wixapis.com, like /stores/v3, /ecom/v1, /contacts/v4, /members/v1, /wix-data/v2, and /events/v3. Requests and responses are JSON, a read-of-many is usually a POST to a query or search method that takes paging and filtering in the body, and a call authenticates with an OAuth app token or an account API key.
Wix runs a first-party hosted Model Context Protocol server at https://mcp.wix.com/mcp. It exposes tools that search the Wix REST, SDK, and app-building documentation, fetch the full request and response schema of an API method, and perform an action or query against a chosen account and site, so an AI client can both learn the API and call it. It is the official Wix MCP, built and maintained by Wix.
An app registers for the events it cares about and Wix POSTs a signed JSON Web Token to the app's endpoint when a matching event occurs on a site, like wix.ecom.v1.order created or a contact created. The app verifies the token with its app secret to confirm the event came from Wix, then acts on the payload, which avoids polling for changes.
A third-party app authenticates with OAuth. The app holds an app ID and secret, a site owner installs it from the Wix App Market and approves the permission scopes the app declared, and the app exchanges those for an access token tied to the app instance on that site. The token grants only the approved permissions, and a refresh token keeps it current. This is the only method available to third-party apps.
An account owner or co-owner creates an API key in the API Keys Manager and assigns it a set of permissions that determine which APIs it can call. The key calls the API directly, bypassing OAuth, with the account ID in the header for account-level requests or the site ID for site-level requests. API keys are an account-level tool and are not available to third-party apps.
The Wix REST API is split into business areas an agent can act on, like the store catalog, eCommerce orders, contacts, members, bookings, the CMS, and ticketed events. Each area is a separate set of methods with its own permissions, and a write in one area, like creating an order, does not imply access to another.
Methods for working with the store's product catalog (Catalog V3).
Methods for reading and recording eCommerce orders.
Methods for working with the site's contacts.
Methods for working with site members.
Methods for reading and creating bookings for a site's services.
Methods for storing and retrieving items in content collections.
Methods for reading ticketed events on the site.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Stores (catalog)Methods for working with the store's product catalog (Catalog V3).5 | ||||||
| POST | /stores-reader/v1/products/query | Query the store catalog for products with paging, filtering, and sorting (Catalog V1 reader). | read | Read Products | Current | |
Scope SCOPE.DC-STORES.READ-PRODUCTS. Catalog V1 reader; Catalog V3 uses the search method below. Acts onproduct Permission (capability) Read ProductsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /stores/v3/products/search | Search the catalog for products with paging, filtering, and sorting (Catalog V3). | read | Read Products | Current | |
Scope SCOPE.STORES.PRODUCT_READ (or PRODUCT_READ_ADMIN). Returns up to 100 products per page. Acts onproduct Permission (capability) Read ProductsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /stores/v3/products/{productId} | Retrieve a single product by its ID (Catalog V3). | read | Read Products | Current | |
Scope SCOPE.STORES.PRODUCT_READ. Acts onproduct Permission (capability) Read ProductsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /stores/v3/products | Create a product in the catalog (Catalog V3). Does not create inventory items by itself. | write | Manage Products | Current | |
Scope SCOPE.STORES.PRODUCT_WRITE. Use Create Product With Inventory to set stock in the same call. Acts onproduct Permission (capability) Manage ProductsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /stores/v3/products/{productId} | Update specified fields on a product (Catalog V3). | write | Manage Products | Current | |
Scope SCOPE.STORES.PRODUCT_WRITE. Bulk Update Products changes one field across up to 100 products. Acts onproduct Permission (capability) Manage ProductsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
eCommerce ordersMethods for reading and recording eCommerce orders.3 | ||||||
| POST | /ecom/v1/orders/search | Search eCommerce orders with paging, filtering, and sorting. | read | Read Orders | Current | |
Scope SCOPE.DC-STORES.READ-ORDERS. Acts onorder Permission (capability) Read OrdersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /ecom/v1/orders/{id} | Retrieve a single eCommerce order by its ID. | read | Read Orders | Current | |
Scope SCOPE.DC-STORES.READ-ORDERS (or MANAGE-ORDERS). Acts onorder Permission (capability) Read OrdersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /ecom/v1/orders | Record an order from an external system (POS, marketplace, or legacy platform) or a manual phone or email sale. | write | Manage Orders | Current | |
Scope SCOPE.DC-STORES.MANAGE-ORDERS. Online purchases create orders automatically at checkout. Acts onorder Permission (capability) Manage OrdersVersionAvailable since the API’s base version Webhook event order-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Contacts (CRM)Methods for working with the site's contacts.3 | ||||||
| POST | /contacts/v4/contacts/query | Query the site's contacts with paging, filtering, and sorting. Returns up to 1,000 contacts per request. | read | Read Contacts | Current | |
Scope SCOPE.DC-CONTACTS.READ-CONTACTS (or a broader Manage Contacts scope). Acts oncontact Permission (capability) Read ContactsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /contacts/v4/contacts | Create a contact. The contact must include at least a name, phone number, or email address. | write | Manage Contacts | Current | |
Scope SCOPE.DC-CONTACTS.MANAGE-CONTACTS. Acts oncontact Permission (capability) Manage ContactsVersionAvailable since the API’s base version Webhook event contact-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /contacts/v4/contacts/{contactId} | Update specified fields on an existing contact. | write | Manage Contacts | Current | |
Scope SCOPE.DC-CONTACTS.MANAGE-CONTACTS. Uses a revision to guard against conflicting updates. Acts oncontact Permission (capability) Manage ContactsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MembersMethods for working with site members.3 | ||||||
| GET | /members/v1/members | List site members with paging and fieldsets. Private members are excluded unless called with admin credentials. | read | Read Members | Current | |
Scope SCOPE.DC-MEMBERS.READ-MEMBERS. Acts onmember Permission (capability) Read MembersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /members/v1/members/query | Query site members with paging, filtering, and sorting. | read | Read Members | Current | |
Scope SCOPE.DC-MEMBERS.READ-MEMBERS. Pass the next cursor from pagingMetadata to page. Acts onmember Permission (capability) Read MembersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /members/v1/members/{id} | Retrieve a single site member by ID. | read | Read Members | Current | |
Scope SCOPE.DC-MEMBERS.READ-MEMBERS. Acts onmember Permission (capability) Read MembersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BookingsMethods for reading and creating bookings for a site's services.2 | ||||||
| POST | /_api/bookings-reader/v2/extended-bookings/query | Query bookings for a site's services with filtering and paging (Bookings Reader V2). | read | Read Bookings | Current | |
Bookings are read with the Reader V2 API; the Writer V2 API cannot return bookings. Acts onbooking Permission (capability) Read BookingsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /_api/bookings-service/v2/bookings | Create a booking for a service. Requires participantsChoices or totalParticipants on the request. | write | Manage Bookings | Current | |
Scope SCOPE.DC-BOOKINGS.MANAGE-BOOKINGS. Only Manage Bookings identities can set status CONFIRMED. Acts onbooking Permission (capability) Manage BookingsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Data Items (CMS)Methods for storing and retrieving items in content collections.3 | ||||||
| POST | /wix-data/v2/items/query | Query items in a content collection (CMS) with filtering, sorting, and paging. | read | Read Data Items | Current | |
Scope SCOPE.DC-DATA.READ. The collection's own permissions also govern which roles can read. Acts ondataItem Permission (capability) Read Data ItemsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /wix-data/v2/items | Insert an item into an existing content collection (CMS). An ID is assigned automatically unless supplied. | write | Manage Data Items | Current | |
Scope SCOPE.DC-DATA.WRITE. The collection must already exist (create one with the Data Collections API). Acts ondataItem Permission (capability) Manage Data ItemsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /wix-data/v2/items/save | Insert or update an item depending on whether the supplied ID already exists in the collection (upsert). | write | Manage Data Items | Current | |
Scope SCOPE.DC-DATA.WRITE. Creates the item if the ID is new, updates it if it exists. Acts ondataItem Permission (capability) Manage Data ItemsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
EventsMethods for reading ticketed events on the site.1 | ||||||
| POST | /events/v3/events/query | Query ticketed events on the site with paging, filtering, and sorting (Wix Events V3). | read | Read Events | Current | |
Scope SCOPE.DC-EVENTS.READ-EVENTS. Acts onevent Permission (capability) Read EventsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Wix can notify an app when something happens on a site, like an order being created or a contact being added. It sends a signed message describing what changed, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
wix.ecom.v1.order_created | An eCommerce order was created on the site, whether through checkout or recorded by the API. The payload carries the order line items, buyer info, pricing, and payment and fulfillment status. | /ecom/v1/orders |
Contact Created | A new contact was added to the site's CRM, for example through a form, a checkout, or the Create Contact method. | /contacts/v4/contacts |
Wix throttles how fast an app can call a site, and returns a clear status when a caller sends too many requests too quickly.
Wix throttles how many requests an app or key can send to a site in a short window. When a caller goes over, the API returns HTTP 429, and the documented guidance is to wait a minute and retry. Wix does not publish a single fixed request-per-minute number in its REST limits article, so an integration should treat 429 as the signal to back off and slow down rather than assume a fixed ceiling. Some modules, like the CMS data store, also note their own per-operation limits in their reference pages.
A list or query method is cursor-based. A query or search call takes paging, filtering, and sorting in the request body, returns up to a documented maximum per page, and includes a pagingMetadata.cursors object whose next value is passed on the following call to fetch the next page. Page-size maximums vary by module, for example Query Contacts returns up to 1,000 contacts per request and Query Events defaults to a page of 50.
Page-size ceilings are set per method, not globally. Bulk write methods cap the batch, for example Bulk Update Products acts on up to 100 products in one call. A query or search call returns at most the documented maximum for that method, after which the cursor is used to read the next page.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | INVALID_ARGUMENT | One or more request parameters is wrong or missing, or the request failed validation. | Read the message and details (an applicationError or validationError object), correct the parameters, and resend. The request is not retryable as-is. |
| 401 | UNAUTHENTICATED | Wix could not authenticate the caller, for example a missing, invalid, or expired token or key. | Confirm a valid OAuth token or API key is being sent, refresh an expired app token, and retry. |
| 403 | PERMISSION_DENIED | The caller was authenticated but lacks the permission scope this method requires. | Grant the method's required scope to the app at install, or assign the permission to the API key, then retry. |
| 404 | NOT_FOUND | The requested resource was not found or does not exist on this site. | Verify the resource ID and that the call targets the correct site. |
| 409 | ALREADY_EXISTS / FAILED_PRECONDITION | A conflict with server state, for example a resource that already exists or a revision mismatch on an update. | Re-read the current resource and its revision, reconcile, and retry the write. |
| 428 | PRECONDITION_REQUIRED | A precondition must be met before the request can succeed, such as a required revision on an update. | Supply the required precondition, like the current revision, and resend. |
| 429 | RESOURCE_EXHAUSTED | The caller was throttled for sending too many requests in a short period. | Wait a minute, slow the request rate, and retry with backoff. |
| 500 | INTERNAL | An error occurred on Wix's server. It may also appear as 503 or 504. | Retry later with backoff, and contact Wix if it persists. |
Wix versions each business area on its own track rather than pinning the whole platform to one dated version, so a module like the store catalog can move to a new major version while others stay put.
Wix does not pin the whole platform to one dated version. Each business area is versioned on its own track, so paths carry a per-module major version, like /stores/v3, /contacts/v4, /members/v1, /wix-data/v2, /ecom/v1, and /events/v3. A module's new major version is a separate set of paths, and an older version is deprecated with a published removal date rather than changed underneath callers. Changes ship through the API changelog.
The V1 Query Events method was replaced by the Wix Events V3 Query Events method and removed on this date, an example of Wix retiring an older module version on a published timeline rather than changing it in place.
Pin to a module's current major version and move up when that module ships a new one.
Wix API changelog ↗Bollard AI sits between a team's AI agents and Wix. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.