# About the Portfolio Settings API

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](fallback::https://support.wix.com/en/article/wix-portfolio-an-overview) feature.

With the Portfolio Settings API, you can:

+ [Create](fallback::https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/create-portfolio-settings) or [update](fallback::https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/update-portfolio-settings) a site's portfolio settings. 
+ [Retrieve](fallback::https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/get-portfolio-settings) a site's existing portfolio settings. 
+ Listen for events when a site's portfolio settings are [created](fallback::https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/on-portfolio-settings-created).

## 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](fallback::https://www.wix.com/app-market/web-solution/wix-portfolio?appIndex=0&collimp_id=b54d3569-fdaa-49f6-83f8-2ac6e400bd11&referralSectionName=wix%20portfolio).
+ Since each site only has one portfolio, you only need to call [Create Portfolio Settings](fallback::https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/create-portfolio-settings) once to set it up. After that, call [Update Portfolio Settings](fallback::https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/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

+ [Configure portfolio settings for a new site](fallback::https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/sample-flows#configure-portfolio-settings-for-a-new-site).
+ [Update portfolio settings to reflect new preferences](fallback::https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/sample-flows#update-portfolio-settings-to-reflect-new-preferences).

@package_metadata:@wix/portfolio

To use the PortfolioSettings API, install the `@wix/portfolio` package.

#### Install the package

Follow the installation instructions for your development environment.

| Development environment | Installation method |
|--|--|
| Wix sites (editor or IDE) | Use the [package manager](fallback::https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-in-the-editor). |
| Wix sites (local IDE) | Run `wix install @wix/portfolio` using the [Wix CLI](fallback::https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-with-the-wix-cli).|
| Blocks apps | Use the same installation method as Wix sites. |
| CLI and self-hosted apps | Run `npm install @wix/portfolio` or `yarn add @wix/portfolio`. |
| Headless sites and apps | Run `npm install @wix/portfolio` or `yarn add @wix/portfolio`. |

#### Import the package

To import the package in your code:

```js
import { portfolioSettings } from '@wix/portfolio'
```

# 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](fallback::https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/get-portfolio-settings) to check for existing portfolio settings.

2. If there are existing settings, call [Update Portfolio Settings](fallback::https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/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](fallback::https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/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](fallback::https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/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](fallback::https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/update-portfolio-settings) to adjust the settings.

Coding Examples

Sled Tests

Go Headless

Build Apps

Client

API Preview

Ricos

Develop Websites

REST

Velo

Picasso

GraphQL (Alpha)

PortfolioSettings

Portfolio Settings 1 0 0

portfolioSettings

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](https://dev.wix.com/docs/rest/business-solutions/portfolio/portfolio-settings/update-portfolio-settings).

import { portfolioSettings } from '@wix/portfolio';

async function createPortfolioSettings(portfolioSettings) {
  const response = await portfolioSettings.createPortfolioSettings(portfolioSettings);
};

createPortfolioSettings

import { portfolioSettings } from '@wix/portfolio';
import { auth } from '@wix/essentials';

async function myCreatePortfolioSettingsMethod(portfolioSettings) {
  const elevatedCreatePortfolioSettings = auth.elevate(portfolioSettings.createPortfolioSettings);
  const response = await elevatedCreatePortfolioSettings(portfolioSettings);
}

createPortfolioSettings (with elevated permissions)

import { createClient } from '@wix/sdk';
import { portfolioSettings } from '@wix/portfolio';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { portfolioSettings },
  // Include the auth strategy and host as relevant
});


async function createPortfolioSettings(portfolioSettings) {
  const response = await myWixClient.portfolioSettings.createPortfolioSettings(portfolioSettings);
};

Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client).

createPortfolioSettings (self-hosted)

Manage Portfolio

import { portfolioSettings } from '@wix/portfolio';

async function getPortfolioSettings() {
  const response = await portfolioSettings.getPortfolioSettings();
};

getPortfolioSettings

import { portfolioSettings } from '@wix/portfolio';
import { auth } from '@wix/essentials';

async function myGetPortfolioSettingsMethod() {
  const elevatedGetPortfolioSettings = auth.elevate(portfolioSettings.getPortfolioSettings);
  const response = await elevatedGetPortfolioSettings();
}

getPortfolioSettings (with elevated permissions)

import { createClient } from '@wix/sdk';
import { portfolioSettings } from '@wix/portfolio';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { portfolioSettings },
  // Include the auth strategy and host as relevant
});


async function getPortfolioSettings() {
  const response = await myWixClient.portfolioSettings.getPortfolioSettings();
};

getPortfolioSettings (self-hosted)

GetPortfolioSettingsResponse

import { portfolioSettings } from '@wix/portfolio';

async function updatePortfolioSettings(portfolioSettings) {
  const response = await portfolioSettings.updatePortfolioSettings(portfolioSettings);
};

updatePortfolioSettings

import { portfolioSettings } from '@wix/portfolio';
import { auth } from '@wix/essentials';

async function myUpdatePortfolioSettingsMethod(portfolioSettings) {
  const elevatedUpdatePortfolioSettings = auth.elevate(portfolioSettings.updatePortfolioSettings);
  const response = await elevatedUpdatePortfolioSettings(portfolioSettings);
}

updatePortfolioSettings (with elevated permissions)

import { createClient } from '@wix/sdk';
import { portfolioSettings } from '@wix/portfolio';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { portfolioSettings },
  // Include the auth strategy and host as relevant
});


async function updatePortfolioSettings(portfolioSettings) {
  const response = await myWixClient.portfolioSettings.updatePortfolioSettings(portfolioSettings);
};

updatePortfolioSettings (self-hosted)

UpdatePortfolioSettingsResponse

---
title: Introduction
---

# About the Portfolio Settings API

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](https://support.wix.com/en/article/wix-portfolio-an-overview) feature.

With the Portfolio Settings API, you can:

+ [Create](https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/create-portfolio-settings) or [update](https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/update-portfolio-settings) a site's portfolio settings. 
+ [Retrieve](https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/get-portfolio-settings) a site's existing portfolio settings. 
+ Listen for events when a site's portfolio settings are [created](https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/on-portfolio-settings-created).

## 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](https://www.wix.com/app-market/web-solution/wix-portfolio?appIndex=0&collimp_id=b54d3569-fdaa-49f6-83f8-2ac6e400bd11&referralSectionName=wix%20portfolio).
+ Since each site only has one portfolio, you only need to call [Create Portfolio Settings](https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/create-portfolio-settings) once to set it up. After that, call [Update Portfolio Settings](https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/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

+ [Configure portfolio settings for a new site](https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/sample-flows#configure-portfolio-settings-for-a-new-site).
+ [Update portfolio settings to reflect new preferences](https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/sample-flows#update-portfolio-settings-to-reflect-new-preferences).


@package_metadata:@wix/portfolio

To use the PortfolioSettings API, install the `@wix/portfolio` package.

#### Install the package

Follow the installation instructions for your development environment.

| Development environment | Installation method |
|--|--|
| Wix sites (editor or IDE) | Use the [package manager](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-in-the-editor). |
| Wix sites (local IDE) | Run `wix install @wix/portfolio` using the [Wix CLI](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-with-the-wix-cli).|
| Blocks apps | Use the same installation method as Wix sites. |
| CLI and self-hosted apps | Run `npm install @wix/portfolio` or `yarn add @wix/portfolio`. |
| Headless sites and apps | Run `npm install @wix/portfolio` or `yarn add @wix/portfolio`. |

#### Import the package

To import the package in your code:

```js
import { portfolioSettings } from '@wix/portfolio'
```
  

# 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](https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/get-portfolio-settings) to check for existing portfolio settings.

2. If there are existing settings, call [Update Portfolio Settings](https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/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](https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/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](https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/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](https://dev.wix.com/docs/sdk/backend-modules/portfolio/portfolio-settings/update-portfolio-settings) to adjust the settings.

portfolio_portfolio-settings

Add new project items to the end of the gallery.

Add new project items to the beginning of the gallery.

AddItemDirection

DefaultItemName

EventMetadata

Event ID. With this ID you can easily spot duplicated events and ignore them.

string

A sequence number that indicates the order of updates to an entity. For example, if an entity was updated at 16:00 and then again at 16:01, the second update will always have a higher sequence number.
You can use this number to make sure you're handling updates in the right order. Just save the latest sequence number on your end and compare it to the one in each new message. If the new message has an older (lower) number, you can safely ignore it.

entityEventSequence

Fully Qualified Domain Name of an entity. This is a unique identifier assigned to the API main business entities.
For example, `wix.stores.catalog.product`, `wix.bookings.session`, `wix.payments.transaction`.

entityFqdn

ID of the entity associated with the event.

entityId

Event timestamp in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) format and UTC time. For example, `2020-04-26T13:57:50.699Z`.

eventTime

eventType

The identification type and identity data.

identity

IdentificationData

instanceId

If present, indicates the action that triggered the event.

originatedFrom

Event action name, placed at the top level to make it easier for users to dispatch messages.
For example: `created`/`updated`/`deleted`/`started`/`completed`/`email_opened`.

slug

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

triggeredByAnonymizeRequest

boolean

ID of a site visitor that has not logged in to the site.

anonymousVisitorId

appId

ID of a site visitor that has logged in to the site.

memberId

ID of a Wix user (site owner, contributor, etc.).

wixUserId

identityType

WebhookIdentityType

MediaSettings

folderId

OnPortfolioSettingsCreatedHandler

event

PortfolioSettingsCreatedEnvelope

void

Date and time the portfolio settings were created.

_createdDate

Date and time the portfolio settings were updated.

_updatedDate

mediaSettings

projectItemSettings

ProjectItemSettings

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.

revision

entity

metadata

The direction in which to add new project items to a gallery. Default: `GALLERY_START`

addItemDirection

Default title assigned to a project item if no title is provided. Default: `FILE_NAME`

defaultItemName

updatedPortfolioSettings

handler

Triggered when portfolio settings are created.

import { portfolioSettings } from '@wix/portfolio';

portfolioSettings.onPortfolioSettingsCreated((event) => {
    // handle your event here
});

onPortfolioSettingsCreated

import { createClient, AppStrategy } from '@wix/sdk';
import { portfolioSettings } from '@wix/portfolio';

const wixClient = createClient({
  auth: AppStrategy({
    appId: 'MY-APP-ID',
    publicKey: 'YOUR_APP_PUBLIC_KEY',
  }),
  modules: {
      portfolioSettings,
    },
});

wixClient.portfolioSettings.onPortfolioSettingsCreated((event) => {
    // handle your event here
});