About the Categories API

With the Categories API, you can create robust solutions for organizing and managing event categories. You can use this API to display similar events on different site pages and sort events in your dashboard. For example, you can create separate pages for jazz, blues, and folk events, but also pages for different venues. The same jazz event can be displayed on your jazz page and also on your downtown location page.

With the Wix Event Category Management API, your app can:

Before you begin

It’s important to note the following points before starting to code:

Sample flows

Terminology

  • Category: A way to organize or classify events based on their characteristics or themes.
  • Event: A gathering organized by an individual or business for a group of people.
Did this help?

Categories: Supported Filters and Sorting

The following table shows field support for filters and sorting for the Category object:

FieldQuery Filter OperatorsSortable
createdDate$eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $existsSortable
name$eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $exists
states$hasSome
id$eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $exists

Related content: API Query Language, Query Categories endpoint

Did this help?

Categories: Sample Use Cases & Flows

This article shares some possible use cases your app could support, as well as a sample flow that could support each use case. This can be a helpful jumping off point as you plan your app's implementation.

Sync categories across all sites

If you have multiple event sites using your app, you may need to sync event categories across these sites. For example, if you've added a new city for some of your concerts, such as "Chicago," you’ll need to create a new category named "Chicago" and apply this change to other sites as well.

To sync the category across all sites:

  1. Call Query Categories on the site where you created a new category.

  2. Extract the entire category object. Remove unnecessary fields, like createdDate.

  3. For all other sites, call Query Events and extract the IDs of all relevant events.

  4. Call Create Category on the other sites, passing the new category to each.

  5. Call Bulk Assign Events and assign the new category to all the previously extracted events.

Did this help?

Category Object


Properties
idstringRead-onlyformat GUID

Category ID.


namestringminLength 1maxLength 30

Category name.


createdDatestringRead-onlyformat date-time

Date and time when category was created.


countsCountsRead-only

The total number of draft and published events assigned to the category.


statesArray <string>maxItems 3

Category state. Possible values:

MANUAL: Category is created manually by the user. AUTO: Category is created automatically. RECURRING_EVENT: Category is created automatically when publishing recurring events. HIDDEN: Category can't be seen.

Default: MANUAL.

Note: The WIX_EVENTS.MANAGE_AUTO_CATEGORIES permission scope is required to use states other than MANUAL.

Category
JSON
{ "category": { "id": "e9779de3-a085-4255-b3a6-9559990d4436", "name": "leather", "states": ["MANUAL"], "counts": { "assignedEventsCount": 2, "assignedDraftEventsCount": 8 }, "createdDate": "2021-04-01T09:49:37.068Z" } }
Did this help?

POST

Create Category


Creates a category.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Events - all permissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/events/v1/categories

Body Params
categoryCategoryRequired

Category to create.

Response Object
categoryCategory

Created category.

Create Category Example 1
Request
cURL
curl -X POST 'https://www.wixapis.com/events/v1/categories' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH TOKEN>' \ -d '{ "category": { "name": "leather", "states": ["MANUAL"] } }'
Response
JSON
{ "category": { "id": "e9779de3-a085-4255-b3a6-9559990d4436", "name": "leather", "states": ["MANUAL"] "createdDate": "2021-04-01T09:49:37.068Z" } }
Did this help?

POST

Bulk Create Category


Creates multipe categories at once.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Events - all permissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/events/v1/bulk/categories/create

Body Params
categoriesArray <Category>RequiredminItems 1maxItems 10

Categories to create.

Response Object
resultsArray <BulkCategoryResult>

Bulk create results.


bulkActionMetadataBulkActionMetadata

Metadata of results.

Bulk Create Category Example 1
Request
cURL
curl -X POST 'https://www.wixapis.com/events/v1/bulk/categories/create' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH TOKEN>' \ -d '{ "categories": [ { "name": "leather", "states": ["MANUAL"] }, { "name": "shoes", "states": ["HIDDEN"] } ] }'
Response
JSON
{ "results": [ { "itemMetadata": { "id": "6c313b96-1961-4f0f-b6d7-61788e1a25df", "originalIndex": 0, "success": true }, "item": { "id": "6c313b96-1961-4f0f-b6d7-61788e1a25df", "name": "leather", "createdDate": "2021-04-01T09:55:31.335Z" } }, { "itemMetadata": { "id": "022cdce2-6d8d-4dfd-9210-4b6671539173", "originalIndex": 0, "success": true }, "item": { "id": "022cdce2-6d8d-4dfd-9210-4b6671539173", "name": "shoes", "createdDate": "2021-04-01T09:55:31.335Z" } } ], "bulkActionMetadata": { "totalSuccesses": 2, "totalFailures": 0 } }
Did this help?

PATCH

Update Category


Updates an existing category.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Events - all permissions
Learn more about app permissions.
Endpoint
PATCH
https://www.wixapis.com/events/v1/categories/{category.id}

Path Params
category.idstringRequired

Category ID.

Body Params
categoryCategoryRequired

Category to update.

Response Object
categoryCategory

Updated category.

Update Category Example 1
Request
cURL
curl -X PATCH 'https://www.wixapis.com/events/v1/categories/6c313b96-1961-4f0f-b6d7-61788e1a25df' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH TOKEN>' \ { "category": { "name": "workshop-leather" } }
Response
JSON
{ "category": { "id": "6c313b96-1961-4f0f-b6d7-61788e1a25df", "name": "workshop-leather", "states": ["MANUAL"] "createdDate": "2021-04-01T09:55:31.335Z" } }
Did this help?

DELETE

Delete Category


Deletes a category.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Events - all permissions
Learn more about app permissions.
Endpoint
DELETE
https://www.wixapis.com/events/v1/categories/{categoryId}

Path Params
categoryIdstringRequired

ID of category to be deleted.

Response Object
Returns an empty object.
Delete Category Example 1
Request
cURL
curl -X DELETE 'https://www.wixapis.com/events/v1/categories/6c313b96-1961-4f0f-b6d7-61788e1a25df' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH TOKEN>'
Response
JSON
{}
Did this help?

POST

Query Categories


Retrieves a list of categories, given the provided paging, filtering, and sorting. Query Categories runs with these defaults, which you can override:

Permissions
Manage Events - all permissions
Read Events - all read permissions
Manage Events
Manage Guest List
Read Events
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/events/v1/categories/query

Body Params
queryQueryRequired

Options to use when querying categories. See API Query Language for more details.


fieldsetArray <string>maxItems 1

Predefined sets of fields to return.

  • COUNTS: Returns assignedEventsCount.
Response Object
categoriesArray <Category>

List of categories.


metaDataMetaData

Metadata for the paginated results.

Query categories by name
Request
cURL
curl -X POST 'https://www.wixapis.com/events/v1/categories/query' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH TOKEN>' \ -d '{ { "query": { "filter": { "name": { "$eq": "food" } } } }
Response
JSON
{ "categories": [ { "id": "e9779de3-a085-4255-b3a6-9559990d4436", "name": "food", "states": ["MANUAL"], "createdDate": "2021-04-01T09:49:37.068Z" } ], "metaData": { "count": 2, "offset": 0, "total": 2 } }
Did this help?

POST

Assign Events


Assigns events to a single category.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Events - all permissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/events/v1/categories/{categoryId}/events

Path Params
categoryIdstringRequired

ID of category to which events should be assigned.

Body Params
eventIdArray <string>Requiredformat GUIDminItems 1maxItems 100

A list of events IDs.

Response Object
Returns an empty object.
Assign Events Example 1
Request
cURL
curl -X POST 'https://www.wixapis.com/events/v1/categories/e9779de3-a085-4255-b3a6-9559990d4436/events' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH TOKEN>' \ -d '{ "categoryId": "e9779de3-a085-4255-b3a6-9559990d4436", "eventId": [ "539a564e-48d2-4eac-8e14-d7a91be6b1c2", "abd39eb7-844c-4321-9ea2-0d43040be05e" ] }'
Response
JSON
{}
Did this help?

DELETE

Unassign Events


Unassigns events from a single category.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Events - all permissions
Learn more about app permissions.
Endpoint
DELETE
https://www.wixapis.com/events/v1/categories/{categoryId}/events

Path Params
categoryIdstringRequired

Category ID.

Query Params
eventIdArray <string>Required

A list of events IDs.

Response Object
Returns an empty object.
Unassign Events Example 1
Request
cURL
curl -X DELETE 'https://www.wixapis.com/events/v1/categories/e9779de3-a085-4255-b3a6-9559990d4436/events?eventId=539a564e-48d2-4eac-8e14-d7a91be6b1c2&eventId=abd39eb7-844c-4321-9ea2-0d43040be05e' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH TOKEN>'
Response
JSON
{}
Did this help?

POST

Bulk Assign Events


Assigns events to multiple categories at once.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Events - all permissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/events/v1/bulk/categories/events

Body Params
categoryIdArray <string>Requiredformat GUIDminItems 1maxItems 10

A list of category IDs to which events should be assigned.


eventIdArray <string>Requiredformat GUIDminItems 1maxItems 1

A list of events IDs.

Response Object
resultsArray <BulkCategoryResult>

Bulk assign results.


bulkActionMetadataBulkActionMetadata

Metadata of results.

Bulk Assign Events Example 1
Request
cURL
curl -X POST 'https://www.wixapis.com/events/v1/bulk/categories/events' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH TOKEN>' \ -d '{ "categoryId": [ "e9779de3-a085-4255-b3a6-9559990d4436", "027ac25d-cc64-4eb1-8666-4ea53cf7f134" ], "eventId": [ "539a564e-48d2-4eac-8e14-d7a91be6b1c2" ] }'
Response
JSON
{ "results": [ { "itemMetadata": { "id": "027ac25d-cc64-4eb1-8666-4ea53cf7f134", "originalIndex": 0, "success": true }, "item": { "id": "027ac25d-cc64-4eb1-8666-4ea53cf7f134", "name": "2", "createdDate": "2021-03-25T10:16:57.486Z" } }, { "itemMetadata": { "id": "e9779de3-a085-4255-b3a6-9559990d4436", "originalIndex": 1, "success": true }, "item": { "id": "e9779de3-a085-4255-b3a6-9559990d4436", "name": "technology", "createdDate": "2021-04-01T09:49:37.068Z" } } ], "bulkActionMetadata": { "totalSuccesses": 2, "totalFailures": 0 } }
Did this help?

DELETE

Bulk Unassign Events


Unassigns events from multiple categories at once.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Events - all permissions
Learn more about app permissions.
Endpoint
DELETE
https://www.wixapis.com/events/v1/bulk/categories/events

Query Params
categoryIdArray <string>Required

A list of category IDs.


eventIdArray <string>

A list of events IDs.

Response Object
resultsArray <BulkCategoryResult>

Results.


bulkActionMetadataBulkActionMetadata

Metadata.

Bulk Unassign Events Example 1
Request
cURL
curl -X DELETE 'https://www.wixapis.com/events/v1/bulk/categories/events?categoryId=e9779de3-a085-4255-b3a6-9559990d4436&categoryId=027ac25d-cc64-4eb1-8666-4ea53cf7f134&eventId=539a564e-48d2-4eac-8e14-d7a91be6b1c2' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH TOKEN>'
Response
JSON
{ "results": [ { "itemMetadata": { "id": "027ac25d-cc64-4eb1-8666-4ea53cf7f134", "originalIndex": 0, "success": true }, "item": { "id": "027ac25d-cc64-4eb1-8666-4ea53cf7f134", "name": "2", "createdDate": "2021-03-25T10:16:57.486Z" } }, { "itemMetadata": { "id": "e9779de3-a085-4255-b3a6-9559990d4436", "originalIndex": 1, "success": true }, "item": { "id": "e9779de3-a085-4255-b3a6-9559990d4436", "name": "technology", "createdDate": "2021-04-01T09:49:37.068Z" } } ], "bulkActionMetadata": { "totalSuccesses": 2, "totalFailures": 0 } }
Did this help?

GET

List Event Categories


Retrieves a list of categories that are not in the `HIDDEN`` state.

Permissions
Manage Events - all permissions
Read Events - all read permissions
Manage Events
Manage Guest List
Read Events
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/events/v1/categories/{eventId}

Path Params
eventIdstringRequired

Event ID.

Response Object
categoriesArray <Category>

A list of categories.

List Event Categories Example 1
Request
cURL
curl -X GET 'https://www.wixapis.com/events/v1/categories/e8e784a9-8f2b-47ed-9c42-238c0922da7e' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH TOKEN>'
Response
JSON
{ "categories": [ { "name": "workshop", "states": ["MANUAL"], "_id": "6ec293a8-1b47-4337-9c4e-9a6aeb35e66a", "_createdDate": "2022-12-13T11:03:19.174Z" }, { "name": "technology", "states": ["MANUAL"], "_id": "89d3e8d4-45bc-4439-9e74-7e21b3418c88", "_createdDate": "2023-07-12T11:07:35.776Z" } ] }
Did this help?

POST

Reorder Category Events


Change the order of events that are assigned to the same category on the Events Widget.

For more information on how events are displayed in the widget, read this article.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage Events - all permissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/events/v1/categories/{categoryId}/reorder

Path Params
categoryIdstringRequired

Category ID.

Body Params
eventIdstringformat GUID

Event ID.


ONE OF:

beforeEventIdstringformat GUID

Move the event before defined eventId.


afterEventIdstringformat GUID

Move the event after defined eventId.

Response Object
Returns an empty object.
Reorder Category Events Example 1
Request
cURL
curl -X POST 'https://www.wixapis.com/events/v1/categories/6c313b96-1961-4f0f-b6d7-61788e1a25df/reorder' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH TOKEN>' \ { "eventId": "4e5e4adb-9778-4171-a9bb-44e27834ac89", "afterEventId": "32c0eab1-b7a0-4ec2-9fb6-db76f76ee488" }
Response
JSON
{}
Errors
400Invalid Argument

There is 1 error with this status code:

See the entire list and learn more about Wix errors.

Did this help?