Import and export pages¶

Pages can be imported and exported into Elevate using the Pages API. Both the import and export of pages are based on the market attribute, which must be supplied as a query parameter for the export, and in the request body for the import. Both endpoints require the Api-Key header.

Pages that are imported via the pages API are automatically published unless the previewOnly flag is set. Pages that already exist will be updated if the permissions allow it.

Note that importing a page will discard all currently unpublished changes made to that page. For this reason, imports should ideally be scheduled so that they don't collide with manual edits.

Import permissions for pages¶

Permissions for changes to pages are based on the source of the change, either via the apps or the via API. Within each source, permissions can be set to allow for changes in the page and product selections, or in the product lists.

The import permission settings for pages can be configured in Configuration tab in the Admin app. The Pages API can always create and remove pages, which means that a full import will NOT be affected by the configured permissions for the API.

Import permissions for pages

Update existing pages from the API¶

The following actions can be performed with Update existing pages from the API allowed:

Create pages
Remove pages
Add lists
- Set the list algorithm
- Limit the product selection
- Change the product selection of a list
Remove lists
Edit the page heading
Set if a selection should be inherited by child pages

Update settings for existing pages from the API¶

The following actions can be performed with Update settings for existing pages from the API allowed:

Pin products
Block products
Change list keywords
Change list facet selections
Change list sort orders

Locale-specific settings¶

While most settings on a page are locale independent, a few are set per locale. These settings take a mapping from the locale attribute to a setting value. Each locale is optional, meaning the settings can be set for only a subset (or none) of the available locales if desired.

Additionally, custom data can be added per locale using the customData object. Custom data is limited to 3 000 characters and 200 keys per locale. For more information, see Page.

In the full import example below, the headings and paths fields as well as the customData are locale-specific.

Export¶

The export endpoint exports all pages based on the supplied market attribute.

Examples¶

Full import¶

A full import will replace all existing pages of the specified market with the content of addOrUpdate.

JSON

{
  "market": "UK",
  "type": "FULL",
  "addOrUpdate": [
    {
      "id": "/",
      "heading": "",
      "recLists": [
        {
          "id": "home-1",
          "rules": "rule incl discount [5, 100]",
          "pinned": ["ABC123"],
          "blocked": ["DEF456"]
        }
      ]
    },
    {
      "id": "/tools/power-tools",
      "headings": {
        "en-GB": "Power tools",
        "sv-SE": "Elverktyg"
      },
      "paths": {
        "en-GB": "categories/power-tools", 
        "sv-SE": "kategorier/elverktyg"
      },
      "customData": {
        "en-GB": {
          "key": "value",
          "preamble": "All our power tools come with batteries included...",
          "isCategoryPage": "True",
          "banner_image": "/assets/banners/en/power_tools_01.jpg"
        },
        "sv-SE": {
          "preamble": "Alla våra elverktyg inkluderar batterier...",
          "isCategoryPage": "True",
          "banner_image": "/assets/banners/se/power_tools_01.jpg"
        },
      },
      "primaryList": {
        "rules": "rule incl custom.category_name { \"Power tools\" }",
        "pinned": [],
        "blocked": [],
        "keywords": {
          "enabled": false
        },
        "facetsOverride": {
          "enabled": false
        },
        "sortOrderOverride": {
          "enabled": false
        },
        "restrictChildRules": false
      },
      "recLists": [
        {
          "id": "rec-list-1",
          "rules": "rule incl newness 10d",
          "pinned": ["GHI789"],
          "blocked": []
        }
      ]
    }
  ]
}

Partial import¶

A partial import can both add pages to and remove pages from a market. In this example pages are added to a specified market.

JSON

{
  "market": "UK",
  "type": "PARTIAL",
  "addOrUpdate": [
    {
      "id": "/home/lighting",
      "headings": {
        "en-GB": "Lighting"
      },
      "primaryList": {
        "rules": "rule incl custom.category_name { \"Lighting\" }",
        "pinned": [],
        "blocked": [],
        "keywords": {
          "enabled": true,
          "headingAsKeyword": true,
          "additional": {
            "en-GB": ["lights", "lamp"]
          },
        },
        "facetsOverride": {
          "enabled": true,
          "facets": [
              { "attribute": "brand", "sortOrder": "ALPHABETICAL" },
              { "attribute": "newness" },
              { "attribute": "custom.number.items_in_package" },
              { "attribute": "weight", "unit": "g" },
              { "attribute": "variant.custom.socket_type", "sortOrder": "ALPHABETICAL" }
          ]
        },
        "sortOrderOverride": {
          "enabled": true,
          "sortOrders": [" RELEVANCE",
                        "NEWEST_FIRST",
                        "PRICE_INCREASING",
                        "PRICE_DECREASING",
                        "DISCOUNT",
                        "RATING"]
        },
        "restrictChildRules": false
      },
      "recLists": [
        {
          "id": "rec-list-1",
          "rules": "rule incl discount [5, 30]",
          "pinned": [],
          "blocked": []
        }
      ]
    }
  ],
  "remove": ["KLM012"]
}

Minimal examples¶

This example contains a primary list and a rec list. It does not override any default settings.

JSON

{
  "market": "UK",
  "type": "PARTIAL",
  "addOrUpdate": [
    {
      "id": "/home/lighting",
      "primaryList": {
        "rules": "rule incl custom.category_name { \"Lighting\" }",
      },
      "recLists": [
        {
          "id": "rec-list-1",
          "rules": "rule incl discount [5, 30]"
        }
      ]
    }
  ]
}

This example removes the page imported in the above example.

JSON

{
  "market": "UK",
  "type": "PARTIAL",
  "remove": [
    "/home/lighting"
  ]
}