The Collections API allows you to manage collections in a portfolio. A collection is a way to group similar projects together in your portfolio. Learn more about collections in Wix Portfolio.
With the Collections API, you can:
It’s important to note the following points before starting to code:
collectionIds
parameter of the Create Project or Update Project methods.This article presents possible use cases and corresponding sample flows that you can support. This can be a helpful jumping off point as you plan your implementation.
You can develop a photo analyzer to categorize related photography projects into collections based on theme.
Call Create Collection to create a collection for projects with a shared theme. Save the returned collection ID for a later step.
Analyze your projects and identify those with a shared theme.
Use the Projects API to add the projects with a shared theme to the collection by assigning the saved collection ID to each project.
Call Get Collection to display the collection.
You can use the Collections API to keep up with collection changes by Wix users.
Listen for the Collection Created, Collection Updated, and Collection Deleted events to detect changes made by Wix users.
Based on the event type, adjust your data to reflect the latest collections.
This article covers field support for filtering and sorting in the Collections API.
The following table shows field support for filters and sorting for the collections object when calling Query Collections:
Field | Supported Filters | Sortable |
---|---|---|
id | eq , ne , exists , in , hasSome , startsWith , ascending , descending | Sortable |
title | eq , ne , exists , in , hasSome , startsWith , ascending , descending | Sortable |
slug | eq , ne , exists , in , hasSome , startsWith , ascending , descending | Sortable |
description | eq , ne , exists , in , hasSome , startsWith , ascending , descending | |
sortOrder | eq , ne , exists , in , hasSome , startsWith , ascending , descending | Sortable |
hidden | eq , ne , exists , in , hasSome , startsWith , ascending , descending | |
createdDate | eq , ne , exists , in , hasSome , startsWith , ascending , descending | Sortable |
updatedDate | eq , ne , exists , in , hasSome , startsWith , ascending , descending | Sortable |
Collection ID.
Revision number, which increments by 1 each time the collection is updated. To prevent conflicting changes, the existing revision must be passed when updating the collection object.
Collection title.
Collection description.
Collection slug.
Collection cover image.
Whether the collection is hidden from the portfolio. Default: false
Index that determines which position a collection is displayed in the portfolio.
Default: Epoch timestamp.
Date and time the collection was created.
Date and time the collection was updated.
Collection page URL and and relative path. Returned when includePageUrl
is true
in the request.
Collection SEO data.
{
"id": "b13e1166-fdf2-425a-a35c-d698edcbafa7",
"revision": 2,
"title": "Bottles",
"description": "The Bottles collection offers a diverse selection of containers designed for carrying and consuming beverages",
"slug": "bottles-1",
"coverImage": {
"imageInfo": {
"id": "987e6543-e21a-10d2-b987-426614176789",
"url": "https://example.com/image.jpg",
"width": 1920,
"height": 1080
}
},
"hidden": false,
"sortOrder": 5.0,
"createdDate": "2024-06-26T09:28:08.288Z",
"updatedDate": "2024-06-26T11:10:35.577Z",
"url": {
"relativePath": "/collections/bottles-1",
"url": "https://www.example.com/collections/bottles-1"
},
"seoData": {
"tags": [
{
"type": "title",
"props": {
"text": "Bottles collection - Buy Online"
}
},
{
"type": "meta",
"props": {
"name": "description",
"content": "Explore our Bottles collection featuring various beverage containers."
}
},
{
"type": "link",
"props": {
"rel": "canonical",
"href": "https://www.example.com/collections/bottles-1"
}
}
],
"settings": {
"preventAutoRedirect": false,
"keywords": [
{
"term": "bottles",
"isMain": true
},
{
"term": "beverage containers",
"isMain": false
}
]
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a list all collections in a portfolio.
Maximum number of items to return in the results.
Pointer to the next or previous page in the list of results.
Pass the relevant cursor token from the pagingMetadata
object in the previous call's response.
Not relevant for the first request.
Whether to include the collection's page URL and relative path in the response. Default: false
List of collections.
Paging metadata.
curl -X GET \
'https://www.wixapis.com/portfolio/v1/collections' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
{
"collections": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"revision": 1,
"title": "Collection Title 1",
"description": "Description of collection 1.",
"slug": "collection-title-1",
"coverImage": {
"imageInfo": {
"id": "8c074c67-2926-4518-92ef-c79d7810b3a4"
}
}
"hidden": false,
"sortOrder": 1.0,
"createdDate": "2024-07-31T12:00:00Z",
"updatedDate": "2024-07-31T12:00:00Z",
"url": {
"relative": "/collections/collection-title-1",
"url": "https://example.com/collections/collection-title-1"
}
},
{
"id": "223e4567-e89b-12d3-a456-426614174000",
"revision": 1,
"title": "Collection Title 2",
"description": "Description of collection 2.",
"slug": "collection-title-2",
"coverImage": {
"imageInfo": {
"id": "42460836-02b9-4640-8d47-2d9fe9aba7e4"
}
}
"hidden": true,
"sortOrder": 2.0,
"createdDate": "2024-07-31T12:10:00Z",
"updatedDate": "2024-07-31T12:10:00Z",
"url": {
"relative": "/collections/collection-title-2",
"url": "https://example.com/collections/collection-title-2"
}
}
],
"metadata": {
"count": 2,
"offset": 0,
"total": 2,
"tooManyToCount": false,
"cursors": {
"next": "next_cursor",
"prev": "prev_cursor"
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates a collection.
You can only call this method when authenticated as a Wix app or Wix user identity.
Collection to create.
Created collection.
curl -X POST \
'https://www.wixapis.com/portfolio/v1/collections' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
"collection": {
"title": "New Collection Title",
"description": "This is a new collection description.",
"slug": "new-collection-title",
"coverImage": {
"imageInfo": {
"id": "8c074c67-2926-4518-92ef-c79d7810b3a4"
}
},
"hidden": false,
"sortOrder": 1.0,
"seoData": {
"settings": {
"keywords": [
{
"isMain": true,
"origin": "marketing-persona",
"term": "investment management"
}
],
"preventAutoRedirect": false
},
"tags": [
{
"children": "Investment Experts Share Growth Strategies",
"custom": false,
"disabled": false,
"type": "title"
},
{
"children": "",
"custom": false,
"disabled": false,
"props": {
"content": "Investment strategies explained by investment experts. Investment experts offer valuable insights for growth.",
"name": "description"
},
"type": "meta"
}
]
}
}
}'
{
"collection": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"revision": 1,
"title": "New Collection Title",
"description": "This is a new collection description.",
"slug": "new-collection-title",
"coverImage": {
"imageInfo": {
"id": "8c074c67-2926-4518-92ef-c79d7810b3a4"
}
}
"hidden": false,
"sortOrder": 1.0,
"createdDate": "2024-07-31T12:00:00Z",
"updatedDate": "2024-07-31T12:00:00Z",
"seoData": {
"settings": {
"keywords": [
{
"isMain": true,
"origin": "marketing-persona",
"term": "investment management"
}
],
"preventAutoRedirect": false
},
"tags": [
{
"children": "Investment Experts Share Growth Strategies",
"custom": false,
"disabled": false,
"type": "title"
},
{
"children": "",
"custom": false,
"disabled": false,
"props": {
"content": "Investment strategies explained by investment experts. Investment experts offer valuable insights for growth.",
"name": "description"
},
"type": "meta"
}
]
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a collection.
ID of the collection to retrieve.
Whether to include the collection's page URL and relative path in the response. Default: false
The requested collection.
curl -X GET \
'https://www.wixapis.com/portfolio/v1/collections/123e4567-e89b-12d3-a456-426614174000?includePageUrl=true' \
-H 'Authorization: <AUTH>'
{
"collection": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"revision": 1,
"title": "Collection Title",
"description": "Collection Description",
"slug": "collection-title",
"coverImage": {
"imageInfo": {
"id": "8c074c67-2926-4518-92ef-c79d7810b3a4"
}
},
"hidden": false,
"sortOrder": 1.0,
"createdDate": "2024-07-31T12:00:00Z",
"updatedDate": "2024-07-31T12:00:00Z",
"url": {
"relativePath": "/projects/project-title",
"url": "https://example.com/projects/project-title"
},
"seoData": {
"settings": {
"keywords": [
{
"isMain": true,
"origin": "marketing-persona",
"term": "Investment Management"
}
],
"preventAutoRedirect": false
},
"tags": [
{
"children": "Investment Experts Share Growth Strategies",
"custom": false,
"disabled": false,
"type": "title"
},
{
"children": "",
"custom": false,
"disabled": false,
"props": {
"content": "Investment strategies explained by investment experts. Investment experts offer valuable insights for growth.",
"name": "description"
},
"type": "meta"
}
]
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Deletes a collection.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection to delete.
ID of the deleted collection.
curl -X DELETE \
'https://www.wixapis.com/portfolio/v1/collections/123e4567-e89b-12d3-a456-426614174000' \
-H 'Authorization: <AUTH>' \
{
"collectionId": "123e4567-e89b-12d3-a456-426614174000"
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Updates a collection.
You can only call this method when authenticated as a Wix app or Wix user identity.
Collection ID.
Collection to update.
Updated collection.
curl -X PATCH \
'https://www.wixapis.com/portfolio/v1/collections/123e4567-e89b-12d3-a456-426614174000' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
"collection": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"revision": 1,
"title": "Updated Collection Title",
"description": "This is an updated collection description.",
"slug": "updated-collection-title",
"coverImage": {
"imageInfo": {
"id": "8c074c67-2926-4518-92ef-c79d7810b3a4"
}
}
"hidden": false,
"sortOrder": 1.0
}
}'
{
"collection": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"revision": 2,
"title": "Updated Collection Title",
"description": "This is an updated collection description.",
"slug": "updated-collection-title",
"coverImage": {
"imageInfo": {
"id": "8c074c67-2926-4518-92ef-c79d7810b3a4"
}
}
"hidden": false,
"sortOrder": 1.0,
"createdDate": "2024-07-31T12:00:00Z",
"updatedDate": "2024-07-31T12:30:00Z",
"url": {
"relative": "/collections/updated-collection-title",
"url": "https://example.com/collections/updated-collection-title"
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a list of collections given the provided paging, filtering, and sorting. Up to 100 collections can be returned per request.
The default sort
is id
in ASC
.
For a detailed list of supported operations, see Collections: Supported Filters and Sorting. To learn how to query collections, see API Query Language.
Query options.
Whether to include the collection's page URL and relative path in the response. Default: false
List of collections.
Paging metadata.
curl -X POST \
'https://www.wixapis.com/portfolio/v1/collections/query' \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
"query": {
"filter": {
"title": {
"$contains": "Collection"
}
},
"sort": [
{
"fieldName": "created_date",
"order": "ASC"
}
],
"cursorPaging": {
"limit": 10
}
},
"includePageUrl": true
}'
{
"collections": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"revision": 1,
"title": "Collection Title 1",
"description": "Description of collection 1.",
"slug": "collection-title-1",
"coverImage": {
"imageInfo": {
"id": "8c074c67-2926-4518-92ef-c79d7810b3a4"
}
},
"hidden": false,
"sortOrder": 1.0,
"createdDate": "2024-07-31T12:00:00Z",
"updatedDate": "2024-07-31T12:00:00Z",
"url": {
"relative": "/collections/collection-title-1",
"url": "https://example.com/collections/collection-title-1"
}
},
{
"id": "223e4567-e89b-12d3-a456-426614174000",
"revision": 1,
"title": "Collection Title 2",
"description": "Description of collection 2.",
"slug": "collection-title-2",
"coverImage": {
"imageInfo": {
"id": "42460836-02b9-4640-8d47-2d9fe9aba7e4"
}
},
"hidden": true,
"sortOrder": 2.0,
"createdDate": "2024-07-31T12:10:00Z",
"updatedDate": "2024-07-31T12:10:00Z",
"url": {
"relative": "/collections/collection-title-2",
"url": "https://example.com/collections/collection-title-2"
}
}
],
"metadata": {
"count": 2,
"offset": 0,
"total": 2,
"tooManyToCount": false,
"cursors": {
"next": "next_cursor",
"prev": "prev_cursor"
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a collection is created.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.portfolio.collections.v1.collection
.
Event name. Expected created
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"data": {
"eventType": "wix.portfolio.collections.v1.collection_created",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>",
// The identity field is sent as a stringified JSON
"identity": {
"identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
"anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR
"memberId": "<memberId>", // in case of MEMBER
"wixUserId": "<wixUserId>", // in case of WIX_USER
"appId": "<appId>" // in case of APP
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a collection is deleted.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.portfolio.collections.v1.collection
.
Event name. Expected deleted
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"data": {
"eventType": "wix.portfolio.collections.v1.collection_deleted",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>",
// The identity field is sent as a stringified JSON
"identity": {
"identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
"anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR
"memberId": "<memberId>", // in case of MEMBER
"wixUserId": "<wixUserId>", // in case of WIX_USER
"appId": "<appId>" // in case of APP
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a collection is updated.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.portfolio.collections.v1.collection
.
Event name. Expected updated
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"data": {
"eventType": "wix.portfolio.collections.v1.collection_updated",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>",
// The identity field is sent as a stringified JSON
"identity": {
"identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
"anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR
"memberId": "<memberId>", // in case of MEMBER
"wixUserId": "<wixUserId>", // in case of WIX_USER
"appId": "<appId>" // in case of APP
}
}
}