About the Portfolio Settings 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 Portfolio Settings API allows you to manage a site's portfolio settings, including configurations for its media and project items. Learn more about the Wix Portfolio feature.

With the Portfolio Settings API, you can:

  • Create a site's portfolio settings.
  • Retrieve a site's existing portfolio settings.
  • Update a site's portfolio settings.

Before you begin

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

  • You can only use this API on sites where a Wix user has installed the Wix Portfolio app.
  • Since each site only has one portfolio, you only need to call Create Portfolio Settings once to set it up. After that, call Update Portfolio Settings to make any changes. If you call Create Portfolio Settings when a portfolio already exists, the API will return an 'Entity already exists' error message.

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.

Configure portfolio settings for a new site

When integrating with Wix Portfolio, you can configure a site's portfolio settings.

  1. Call Get Portfolio Settings to check for existing portfolio settings.

  2. If there are existing settings, call Update Portfolio Settings to update the portfolio settings as desired. If there aren't existing settings, proceed to the next step.

  3. Call Create Portfolio Settings to configure the portfolio settings for a site.

Update portfolio settings to reflect new preferences

You can update portfolio settings for a Wix user.

  1. A Wix user wants to update their portfolio settings such as media display options or project item organization.

  2. Call Get Portfolio Settings to retrieve the current portfolio settings. This allows you to review and confirm the existing configuration before making updates.

  3. Based on the new preferences provided by the Wix user, call Update Portfolio Settings to adjust the settings.

Did this help?

Portfolio Settings Object


Properties
revisionintegerRead-onlyformat uint64

Revision number. Increments by 1 each time the portfolio settings object is updated. To prevent conflicting changes, the existing revision must be passed when updating the portfolio settings object.


projectItemSettingsProjectItemSettings

Portfolio's project item settings.


mediaSettingsMediaSettings

Portfolio's media settings.


createdDatestringRead-onlyformat date-time

Date and time the portfolio settings were created.


updatedDatestringRead-onlyformat date-time

Date and time the portfolio settings were updated.

PortfolioSettings
JSON
{ "portfolioSettings": { "revision": 5, "projectItemSettings": { "addItemDirection": "GALLERY_END", "defaultItemName": "FILE_NAME" }, "mediaSettings": { "folderId": "5f6197ab-a4b4-426d-b1fb-02603e24c0be" }, "createdDate": "2024-07-31T12:00:00Z", "updatedDate": "2024-10-27T09:30:00Z" } }
Did this help?

GET

Get Portfolio Settings


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 site's portfolio settings.

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
GET
https://www.wixapis.com/portfolio/v1/settings

Request
This endpoint does not take any parameters.
Response Object
portfolioSettingsPortfolioSettings

Portfolio settings.

Get Portfolio Settings
Request
cURL
curl -X GET \ 'https://www.wixapis.com/portfolio/v1/settings' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "portfolioSettings": { "revision": 1, "projectItemSettings": { "addItemDirection": "GALLERY_END", "defaultItemName": "FILE_NAME" }, "mediaSettings": { "folderId": "5f6197ab-a4b4-426d-b1fb-02603e24c0be" }, "createdDate": "2024-07-31T12:00:00Z", "updatedDate": "2024-07-31T12:00:00Z" } }
Did this help?

POST

Create Portfolio Settings


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 site's portfolio settings.

Note:

This method is intended for creating portfolio settings. If settings already exist, the request will return an error. To update existing settings, call Update Portfolio Settings.

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/settings

Body Params
portfolioSettingsPortfolioSettingsRequired

The portfolio settings to create.

Response Object
portfolioSettingsPortfolioSettings

Newly created portfolio settings.

Create Portfolio Settings
Request
cURL
curl -X POST \ 'https://www.wixapis.com/portfolio/v1/settings' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH>' \ -d '{ "portfolioSettings": { "projectItemSettings": { "addItemDirection": "GALLERY_END", "defaultItemName": "FILE_NAME" }, "mediaSettings": { "folderId": "5f6197ab-a4b4-426d-b1fb-02603e24c0be" } } }'
Response
JSON
{ "portfolioSettings": { "revision": 1, "projectItemSettings": { "addItemDirection": "GALLERY_END", "defaultItemName": "FILE_NAME" }, "mediaSettings": { "folderId": "5f6197ab-a4b4-426d-b1fb-02603e24c0be" }, "createdDate": "2024-07-31T12:00:00Z", "updatedDate": "2024-07-31T12:00:00Z" } }
Event TriggersThis method triggers the following events:
Did this help?

PATCH

Update Portfolio Settings


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 site's portfolio settings.

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/settings

Body Params
portfolioSettingsPortfolioSettingsRequired

The portfolio settings to update.

Response Object
updatedPortfolioSettingsUpdatedPortfolioSettings

Updated portfolio settings.

Update Portfolio Settings
Request
cURL
curl -X PATCH \ 'https://www.wixapis.com/portfolio/v1/settings' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH>' \ -d '{ "portfolioSettings": { "revision": 2, "projectItemSettings": { "addItemDirection": "GALLERY_START", "defaultItemName": "EMPTY" }, "mediaSettings": { "folderId": "42460836-02b9-4640-8d47-2d9fe9aba7e4" } } }'
Response
JSON
{ "updatedPortfolioSettings": { "revision": 2, "projectItemSettings": { "addItemDirection": "GALLERY_START", "defaultItemName": "EMPTY" }, "mediaSettings": { "folderId": "42460836-02b9-4640-8d47-2d9fe9aba7e4" } "createdDate": "2024-07-31T12:00:00Z", "updatedDate": "2024-07-31T12:05:00Z" } }
Did this help?

Portfolio Settings 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 portfolio settings are 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.portfolio_app.v1.portfolio_settings.


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.portfolio_app.v1.portfolio_settings_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?