About the Collections API

Developer Preview
APIs in Developer Preview are subject to change and are not intended for use in production.
Send us your suggestions for improving this API. Your feedback is valuable to us.

 

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:

  • Create, update, and delete collections.
  • Retrieve and query collections.
  • Listen for events when a collection is created, updated, and deleted.

Before you begin

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

  • After creating a collection, you can assign a new or existing project to the collection by specifying the collection's ID in the collectionIds parameter of the Create Project or Update Project methods.
  • You can only use this API on sites where a Wix user has installed the Wix Portfolio app.

Use cases

Did this help?

Sample Use Cases and Flows

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.

Organize photography projects by theme

You can develop a photo analyzer to categorize related photography projects into collections based on theme.

  1. Call Create Collection to create a collection for projects with a shared theme. Save the returned collection ID for a later step.

  2. Analyze your projects and identify those with a shared theme.

  3. Use the Projects API to add the projects with a shared theme to the collection by assigning the saved collection ID to each project.

  4. Call Get Collection to display the collection.

Keep your data current with collection events

You can use the Collections API to keep up with collection changes by Wix users.

  1. Listen for the Collection Created, Collection Updated, and Collection Deleted events to detect changes made by Wix users.

  2. Based on the event type, adjust your data to reflect the latest collections.

Did this help?

Collections: Supported Filters and Sorting

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:

FieldSupported FiltersSortable
ideq, ne, exists, in, hasSome, startsWith, ascending, descendingSortable
titleeq, ne, exists, in, hasSome, startsWith, ascending, descendingSortable
slugeq, ne, exists, in, hasSome, startsWith, ascending, descendingSortable
descriptioneq, ne, exists, in, hasSome, startsWith, ascending, descending
sortOrdereq, ne, exists, in, hasSome, startsWith, ascending, descendingSortable
hiddeneq, ne, exists, in, hasSome, startsWith, ascending, descending
createdDateeq, ne, exists, in, hasSome, startsWith, ascending, descendingSortable
updatedDateeq, ne, exists, in, hasSome, startsWith, ascending, descendingSortable
Did this help?

Collection Object


Properties
idstringRead-onlyformat GUID

Collection ID.


revisionintegerRead-onlyformat uint64

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.


titlestringmaxLength 100

Collection title.


descriptionstring

Collection description.


slugstring

Collection slug.


coverImageCoverImage

Collection cover image.


hiddenboolean

Whether the collection is hidden from the portfolio. Default: false


sortOrdernumberformat double

Index that determines which position a collection is displayed in the portfolio.

Default: Epoch timestamp.


createdDatestringRead-onlyformat date-time

Date and time the collection was created.


updatedDatestringRead-onlyformat date-time

Date and time the collection was updated.


urlUrlRead-only

Collection page URL and and relative path. Returned when includePageUrl is true in the request.


seoDataSeoData

Collection SEO data.

Collection
JSON
{ "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 } ] } } }
Did this help?

GET

List Collections


Developer Preview

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.

Permissions
Manage Portfolio
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/portfolio/v1/collections

Query Params
paging.limitintegerminimum 0maximum 100format int32

Maximum number of items to return in the results.


paging.cursorstringmaxLength 16000

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.


includePageUrlboolean

Whether to include the collection's page URL and relative path in the response. Default: false

Response Object
collectionsArray <Collection>

List of collections.


metadataMetadata

Paging metadata.

List Collections
Request
cURL
curl -X GET \ 'https://www.wixapis.com/portfolio/v1/collections' \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \
Response
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" } } }
Did this help?

POST

Create Collection


Developer Preview

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.

Authentication

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

Permissions
Manage Portfolio
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/portfolio/v1/collections

Body Params
collectionCollectionRequired

Collection to create.

Response Object
collectionCollection

Created collection.

Create Collection
Request
cURL
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" } ] } } }'
Response
JSON
{ "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" } ] } } }
Event TriggersThis method triggers the following events:
Did this help?

GET

Get Collection


Developer Preview

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.

Permissions
Manage Portfolio
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/portfolio/v1/collections/{collectionId}

Path Params
collectionIdstringRequired

ID of the collection to retrieve.

Query Params
includePageUrlboolean

Whether to include the collection's page URL and relative path in the response. Default: false

Response Object
collectionCollection

The requested collection.

Get Collection
Request
cURL
curl -X GET \ 'https://www.wixapis.com/portfolio/v1/collections/123e4567-e89b-12d3-a456-426614174000?includePageUrl=true' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "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" } ] } } }
Did this help?

DELETE

Delete Collection


Developer Preview

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.

Authentication

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

Permissions
Manage Portfolio
Learn more about app permissions.
Endpoint
DELETE
https://www.wixapis.com/portfolio/v1/collections/{collectionId}

Path Params
collectionIdstringRequired

ID of the collection to delete.

Response Object
collectionIdstringformat GUID

ID of the deleted collection.

Delete Collection
Request
cURL
curl -X DELETE \ 'https://www.wixapis.com/portfolio/v1/collections/123e4567-e89b-12d3-a456-426614174000' \ -H 'Authorization: <AUTH>' \
Response
JSON
{ "collectionId": "123e4567-e89b-12d3-a456-426614174000" }
Event TriggersThis method triggers the following events:
Did this help?

PATCH

Update Collection


Developer Preview

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.

Authentication

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

Permissions
Manage Portfolio
Learn more about app permissions.
Endpoint
PATCH
https://www.wixapis.com/portfolio/v1/collections/{collection.id}

Path Params
collection.idstringRequired

Collection ID.

Body Params
collectionCollectionRequired

Collection to update.

Response Object
collectionCollection

Updated collection.

Update Collection
Request
cURL
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 } }'
Response
JSON
{ "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" } } }
Event TriggersThis method triggers the following events:
Did this help?

POST

Query Collections


Developer Preview

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.

Permissions
Manage Portfolio
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/portfolio/v1/collections/query

Body Params
queryQueryRequired

Query options.


includePageUrlboolean

Whether to include the collection's page URL and relative path in the response. Default: false

Response Object
collectionsArray <Collection>

List of collections.


metadataMetadata

Paging metadata.

Query Collections
Request
cURL
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 }'
Response
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" } } }
Did this help?

Collection Created


Developer Preview

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.

Permissions
Manage Portfolio
Learn more about app permissions.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.portfolio.collections.v1.collection.


slugstring

Event name. Expected created.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


createdEventCreatedEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "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 } } }
Did this help?

Collection Deleted


Developer Preview

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.

Permissions
Manage Portfolio
Learn more about app permissions.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.portfolio.collections.v1.collection.


slugstring

Event name. Expected deleted.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


deletedEventstruct

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "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 } } }
Did this help?

Collection Updated


Developer Preview

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.

Permissions
Manage Portfolio
Learn more about app permissions.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.portfolio.collections.v1.collection.


slugstring

Event name. Expected updated.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).


originatedFromstring

If present, indicates the action that triggered the event.


updatedEventUpdatedEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "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 } } }
Did this help?