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:
It’s important to note the following points before starting to code:
The following table shows field support for filters and sorting for the Category object:
Field | Query Filter Operators | Sortable |
---|---|---|
createdDate | $eq , $ne , $lt , $lte , $gt , $gte , $in , $nin , $exists | Sortable |
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
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.
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:
Call Query Categories on the site where you created a new category.
Extract the entire category
object. Remove unnecessary fields, like createdDate
.
For all other sites, call Query Events and extract the IDs of all relevant events.
Call Create Category on the other sites, passing the new category to each.
Call Bulk Assign Events and assign the new category to all the previously extracted events.
Category ID.
Category name.
Date and time when category was created.
The total number of draft and published events assigned to the category.
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": {
"id": "e9779de3-a085-4255-b3a6-9559990d4436",
"name": "leather",
"states": ["MANUAL"],
"counts": {
"assignedEventsCount": 2,
"assignedDraftEventsCount": 8
},
"createdDate": "2021-04-01T09:49:37.068Z"
}
}
Creates a category.
You can only call this method when authenticated as a Wix app or Wix user identity.
Category to create.
Created category.
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"]
}
}'
{
"category": {
"id": "e9779de3-a085-4255-b3a6-9559990d4436",
"name": "leather",
"states": ["MANUAL"]
"createdDate": "2021-04-01T09:49:37.068Z"
}
}
Creates multipe categories at once.
You can only call this method when authenticated as a Wix app or Wix user identity.
Categories to create.
Bulk create results.
Metadata of results.
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"]
}
]
}'
{
"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
}
}
Updates an existing category.
You can only call this method when authenticated as a Wix app or Wix user identity.
Category ID.
Category to update.
Updated category.
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"
}
}
{
"category": {
"id": "6c313b96-1961-4f0f-b6d7-61788e1a25df",
"name": "workshop-leather",
"states": ["MANUAL"]
"createdDate": "2021-04-01T09:55:31.335Z"
}
}
Deletes a category.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of category to be deleted.
curl -X DELETE 'https://www.wixapis.com/events/v1/categories/6c313b96-1961-4f0f-b6d7-61788e1a25df' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH TOKEN>'
{}
Retrieves a list of categories, given the provided paging, filtering, and sorting. Query Categories runs with these defaults, which you can override:
createdDate
is sorted in ASC
orderpaging.limit
is 100
paging.offset
is 0
For field support for filters and sorting, see Categories: Supported Filters and Sorting.
To learn about working with Query endpoints, see API Query Language, Sorting and Paging, and Field Projection.Options to use when querying categories. See API Query Language for more details.
Predefined sets of fields to return.
COUNTS
: Returns assignedEventsCount
.List of categories.
Metadata for the paginated results.
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"
}
}
}
}
{
"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
}
}
Assigns events to a single category.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of category to which events should be assigned.
A list of events IDs.
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"
]
}'
{}
Unassigns events from a single category.
You can only call this method when authenticated as a Wix app or Wix user identity.
Category ID.
A list of events IDs.
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>'
{}
Assigns events to multiple categories at once.
You can only call this method when authenticated as a Wix app or Wix user identity.
A list of category IDs to which events should be assigned.
A list of events IDs.
Bulk assign results.
Metadata of results.
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"
]
}'
{
"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
}
}
Unassigns events from multiple categories at once.
You can only call this method when authenticated as a Wix app or Wix user identity.
A list of category IDs.
A list of events IDs.
Results.
Metadata.
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>'
{
"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
}
}
Retrieves a list of categories that are not in the `HIDDEN`` state.
Event ID.
A list of categories.
curl -X GET 'https://www.wixapis.com/events/v1/categories/e8e784a9-8f2b-47ed-9c42-238c0922da7e' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH TOKEN>'
{
"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"
}
]
}
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.
You can only call this method when authenticated as a Wix app or Wix user identity.
Category ID.
Event ID.
Move the event before defined eventId
.
Move the event after defined eventId
.
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"
}
{}
There is 1 error with this status code:
See the entire list and learn more about Wix errors.