Experiences

PUT Create or update a Page Designer page.

PUT /organizations/{organizationId}/pages/{pageId}

Operation ID: createOrUpdatePage. Security: AmOAuth2 (sfcc.experiences.rw).

This API is designed specifically for single page creation or updating existing pages with all necessary metadata, regions, and components.

Important:

• This is an admin-only operation requiring appropriate permissions.
• By default, the created page is in draft status.
• Page ID in URL must match the page ID in the request body.
• All required fields must be provided in the request body.
• This API supports both create and update operations using PUT semantics.

Parameters

• organizationId (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f_ecom_' followed by a 4-character realm identifier and a 3-character instance type identifier.

  Example

  f_ecom_zzxy_prd

• pageId (path, string, required) Identifier for the requested page.
  Maximum length: 256. Example: homepage.
• siteId (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.

  Example: SiteId

  RefArch

Request body (required)

Media type: application/json. Schema: PageRequest.

Example: CreatePageRequest Example request to create a new page

{
  "id": "new-homepage",
  "typeId": "storePage",
  "aspectTypeId": "pdpAspect",
  "name": "New Homepage",
  "description": "New home page for the storefront",
  "pageTitle": "New Homepage - My Shop",
  "pageDescription": "Welcome to our new homepage",
  "pageKeywords": "homepage, fashion, my shop",
  "thumbnail": "new-homepage.jpg",
  "data": {
    "site_map_priority": 0.8,
    "layout": "default"
  },
  "regions": [
    {
      "id": "header",
      "components": [
        {
          "id": "welcome-banner",
          "typeId": "commerce_assets.banner",
          "data": {
            "title": "Welcome to Our New Store",
            "bannerImage": "welcome-banner.jpg"
          }
        }
      ]
    },
    {
      "id": "main",
      "components": [
        {
          "id": "featured-products",
          "typeId": "commerce_assets.carousel",
          "data": {
            "title": "Featured Products",
            "category": "featured"
          }
        }
      ]
    },
    {
      "id": "footer",
      "components": []
    }
  ]
}

Example: UpdatePageRequest Example request to update an existing page

{
  "id": "new-homepage",
  "typeId": "storePage",
  "name": "Updated Homepage",
  "description": "Updated home page for the storefront",
  "pageTitle": "Updated Homepage - My Shop",
  "pageDescription": "Welcome to our updated homepage",
  "data": {
    "thumbnail": "updated-homepage.jpg",
    "priority": 1
  },
  "regions": [
    {
      "id": "header",
      "components": [
        {
          "id": "welcome-banner",
          "typeId": "commerce_assets.banner",
          "data": {
            "title": "Updated Welcome Banner",
            "bannerImage": "updated-welcome-banner.jpg"
          }
        }
      ]
    }
  ]
}

Responses

• 200 Page updated successfully

  Media type: application/json. Schema: Page.

  Example: UpdatedPage Example response for a successfully updated page

  {
    "id": "new-homepage",
    "typeId": "storePage",
    "aspectTypeId": "pdpAspect",
    "name": "Updated Homepage",
    "description": "Updated home page for the storefront",
    "pageTitle": "Updated Homepage - My Shop",
    "pageDescription": "Welcome to our updated homepage",
    "data": {
      "thumbnail": "updated-homepage.jpg",
      "priority": 1
    },
    "custom": {
      "thumbnail_full": "http://static.myshop.com/updated-homepage.jpg"
    },
    "regions": [
      {
        "id": "header",
        "components": [
          {
            "id": "welcome-banner",
            "typeId": "commerce_assets.banner",
            "data": {
              "title": "Updated Welcome to Our New Store",
              "bannerImage": "updated-welcome-banner.jpg"
            },
            "custom": {
              "banner_url": "http://static.myshop.com/updated-welcome-banner.jpg"
            }
          }
        ]
      }
    ],
    "creationDate": "2024-01-15T10:30:00.000Z",
    "lastModified": "2024-01-15T11:00:00.000Z",
    "online": true
  }

• 201 Page created successfully

  Media type: application/json. Schema: Page.

  Example: CreatedPage Example response for a successfully created page

  {
    "id": "new-homepage",
    "typeId": "storePage",
    "aspectTypeId": "pdpAspect",
    "name": "New Homepage",
    "description": "New home page for the storefront",
    "pageTitle": "New Homepage - My Shop",
    "pageDescription": "Welcome to our new homepage",
    "pageKeywords": "homepage, fashion, my shop",
    "thumbnail": "new-homepage.jpg",
    "data": {
      "site_map_priority": 0.8,
      "layout": "default"
    },
    "custom": {
      "thumbnail_full": "http://static.myshop.com/new-homepage.jpg"
    },
    "regions": [
      {
        "id": "header",
        "components": [
          {
            "id": "welcome-banner",
            "typeId": "commerce_assets.banner",
            "data": {
              "title": "Welcome to Our New Store",
              "bannerImage": "welcome-banner.jpg"
            },
            "custom": {
              "banner_url": "http://static.myshop.com/welcome-banner.jpg"
            }
          }
        ]
      },
      {
        "id": "main",
        "components": [
          {
            "id": "featured-products",
            "typeId": "commerce_assets.carousel",
            "data": {
              "title": "Featured Products",
              "category": "featured"
            },
            "custom": {
              "carousel_url": "http://static.myshop.com/featured"
            }
          }
        ]
      },
      {
        "id": "footer",
        "components": []
      }
    ],
    "creationDate": "2024-01-15T10:30:00.000Z",
    "lastModified": "2024-01-15T10:30:00.000Z",
    "online": false
  }

• 400 Invalid page data provided.

  Media type: application/json. Schema: ErrorResponse.

  Example: InvalidPageData Example error response for invalid page data

  {
    "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
    "title": "Bad Request",
    "detail": "The request body contains invalid page data",
    "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages",
    "issues": [
      {
        "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/required-field-missing",
        "detail": "Required field 'id' is missing",
        "field": "id"
      }
    ]
  }

  Example: MissingSiteId Example error response for missing site ID

  {
    "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
    "title": "Bad Request",
    "detail": "The siteId query parameter is required",
    "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage",
    "issues": [
      {
        "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/required-parameter-missing",
        "detail": "The siteId query parameter is required",
        "field": "siteId"
      }
    ]
  }

  Example: PageIdMismatch Example error response for page ID mismatch between path and body

  {
    "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/page-id-mismatch",
    "title": "Page Id Mismatch",
    "detail": "The page ID in the request path ('path-id') doesn't match the page ID in the request body ('body-id').",
    "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/path-id",
    "issues": [
      {
        "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/page-id-mismatch",
        "detail": "The page ID in the request path ('path-id') doesn't match the page ID in the request body ('body-id').",
        "pathPageId": "path-id",
        "bodyPageId": "body-id"
      }
    ]
  }

  Example: MissingTypeId Example error response for missing typeId field

  {
    "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
    "title": "Bad Request",
    "detail": "Field 'typeId' cannot be empty",
    "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage",
    "issues": [
      {
        "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-field-value",
        "detail": "Field 'typeId' cannot be empty.",
        "field": "typeId"
      }
    ]
  }

  Example: InvalidPageType Example error response for invalid page type ID during page creation

  {
    "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
    "title": "Bad Request",
    "detail": "No page type with ID 'invalidPageType' was found in site 'RefArch'.",
    "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage",
    "issues": [
      {
        "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-field-value",
        "detail": "No page type with ID 'invalidPageType' was found in site 'RefArch'.",
        "field": "typeId",
        "pageTypeId": "invalidPageType",
        "site": "RefArch"
      }
    ]
  }

  Example: InvalidPageId Example error response for invalid page ID format

  {
    "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/content-id-invalid",
    "title": "Content Id Invalid",
    "detail": "The ID 'test page' is invalid. The ID can't have leading or trailing whitespaces. It can only contain alphanumeric characters and the following special characters: _-~:[]@!'*,;=",
    "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/test page",
    "issues": [
      {
        "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/content-id-invalid",
        "detail": "The ID 'test page' is invalid. The ID can't have leading or trailing whitespaces. It can only contain alphanumeric characters and the following special characters: _-~:[]@!'*,;=",
        "id": "test page",
        "field": "id"
      }
    ]
  }

  Example: UnsupportedAspectType Example error response for unsupported aspect type

  {
    "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unsupported-aspect-type",
    "title": "Unsupported Aspect Type",
    "detail": "The aspect type 'invalidAspectType' isn't supported for page type 'storePage'.",
    "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage",
    "issues": [
      {
        "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unsupported-aspect-type",
        "detail": "The aspect type 'invalidAspectType' isn't supported for page type 'storePage'.",
        "aspectType": "invalidAspectType",
        "pageType": "storePage",
        "field": "aspectTypeId"
      }
    ]
  }

  Example: InvalidCustomDataFormat Example error response for invalid custom data format

  {
    "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
    "title": "Bad Request",
    "detail": "Field 'data' must be an object",
    "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage",
    "issues": [
      {
        "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-field-value",
        "detail": "Field 'data' must be an object",
        "field": "data"
      }
    ]
  }

  Example: InvalidVisibilityRule Example error response for invalid visibility rule format

  {
    "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
    "title": "Bad Request",
    "detail": "Field 'customerGroups' must be an array/list, but was: String",
    "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage",
    "issues": [
      {
        "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-field-value",
        "detail": "Field 'customerGroups' must be an array/list, but was: String",
        "field": "data.visibilityRule.customerGroups"
      }
    ]
  }

• 404

  The requested resource was not found. This can occur when:

  • The specified site ID does not exist.
  • An existing page's page type is missing or invalid.

  Media type: application/json. Schema: ErrorResponse.

  Example: SiteNotFound Example error response for site not found

  {
    "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-found",
    "title": "Not Found",
    "detail": "The specified site does not exist",
    "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages",
    "issues": [
      {
        "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
        "detail": "Site with ID 'invalid-site' does not exist",
        "field": "siteId"
      }
    ]
  }

  Example: PageTypeNotFound Example error response for page type not found when retrieving an existing page.

  {
    "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/page-type-not-found",
    "title": "Page Type Not Found",
    "detail": "No page type with ID 'invalidPageType' was found for page 'test-page' in site 'RefArch'.",
    "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/test-page",
    "issues": [
      {
        "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/page-type-not-found",
        "detail": "No page type with ID 'invalidPageType' was found for page 'test-page' in site 'RefArch'.",
        "pageTypeId": "invalidPageType",
        "pageId": "test-page",
        "site": "RefArch"
      }
    ]
  }

• 409 Page ID mismatch or validation error.

  Media type: application/json. Schema: ErrorResponse.

  Example: PageIdConflict Example error response for page ID conflict

  {
    "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/content-id-already-in-use",
    "title": "Conflict",
    "detail": "A Page with the specified ID already exists.",
    "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage",
    "issues": [
      {
        "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/content-id-already-in-use",
        "detail": "Page with ID 'new-homepage' already exists in the site.",
        "field": "id"
      }
    ]
  }